.mtgr

Appearance

0013: One canonical format ​

Status: Accepted

Context ​

PGN defines two levels of the same format (section 3). The import format is "rather flexible" and is "used to describe data that may have been prepared by hand"; programs reading PGN must accept it. The export format is strict and canonical, "used for program generated output", so that two programs exporting the same game produce identical bytes.

.mtgr files are not expected to be written by hand. Nobody realistically remembers a Magic game in enough detail to type up a full record afterwards. At launch, every file comes from a program recording MTGO or Arena. Future sources (for example video capture of a paper game from a top-down camera) are also programs.

Decision ​

  1. The spec defines one format: a strict, canonical format equivalent to PGN's export format. Tag order, spacing, line structure, and every other lexical detail are fixed, so the same game written by two conforming writers is byte-for-byte identical.
  2. Writers MUST produce the canonical format.
  3. Parsers MAY reject anything that is not canonical. The spec defines no lenient import format.
  4. Revisit if a hand-written source appears. This is a deliberate departure from PGN (design principle 7), justified by the fact that no source of hand-prepared files exists. If one appears, a lenient import format can be added without breaking canonical files, because every canonical file would also be valid import format.

Rules basis ​

The Comprehensive Rules (effective 2026-09-25) do not cover file formats; this decision is a format choice.

PGN basis, checked against "Standard: Portable Game Notation Specification and Implementation Guide" (Steven J. Edwards, 1994), https://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm:

  • Section 3.1: the import format "is rather flexible and is used to describe data that may have been prepared by hand", and "a program that can read PGN data should be able to handle the somewhat lax import format".
  • Section 3.2: the export format is "used for program generated output".

Alternatives rejected ​

  • Both import and export formats, as in PGN. Rejected for now: the import format exists for hand-prepared data, and .mtgr has no such source. It would double the grammar and make every parser more complex for no current user. No speculative features.
  • A single lenient format. Rejected: loses byte-for-byte reproducibility, which makes files comparable with a plain diff, deduplicable by hash, and testable exactly against conformance fixtures.

Consequences ​

  • The spec defines one grammar, and conformance fixtures can compare writer output byte for byte.
  • Annotation (decision 0011) is added by programs, such as a viewer's annotation feature, which write canonical output.