2.6. Compatibility🔗

The contract for every reader and writer:

Readers MUST:

• Accept rows whose schema_version is in their supportedVersions set (currently the singleton {1}).

• Reject rows whose schema_version is outside that set, missing, or non-integer with an explicit error that names the unsupported version. Silent best-effort reads of unknown versions risk producing wrong results.

• Tolerate unknown extra keys: ignore them rather than failing.

• Tolerate missing optional keys (treating them as null / absent / the documented default).

• Reject rows whose kind is missing or whose value mismatches the parser (e.g. a fixed-shaped row arriving at the parametric parser).

Readers MAY:

• Decline to interpret rows whose required fields are missing or malformed — those are emitter bugs and surfacing them as a parse error is the right behaviour.

Writers MUST:

• Emit schema_version exactly once per row.

• Emit every required field for the row's kind.

• Use the documented status strings exactly. Unknown status strings are reserved for future use.

Writers MAY:

• Add new optional fields without bumping schema_version, provided every existing reader's "ignore unknown" rule keeps the output valid.

• Order the keys however they like. Consumers MUST NOT depend on key order.