STXT
ESEN .stxt

Stability and versions

A document that is valid in STXT 1.0 is valid across the whole 1.x line.

What is frozen

Surface Promise
The language —the five specifications: STXT-SPEC, STXT-SCHEMA-SPEC, STXT-TEMPLATE-SPEC, STXT-DISCOVERY-SPEC and STXT-TREE-SPEC— Whatever is valid in 1.0 is valid in any 1.x, and means the same. A 1.x only adds; it never invalidates or reinterprets.
The canonical tree (STXT-TREE-SPEC) The JSON produced by stxt describe and exposed by the libraries is a stable interchange format: same fields, same meaning, same result in every implementation.
The error codes (INDENTATION_MIXED, CHILD_NOT_DECLARED, SCHEMA_NOT_FOUND…) They are identical in every implementation and are neither renamed nor reused. A test that depends on a code keeps working.
The in-memory API of each library, within its 1.x line What @stxt-lang/core, dev.stxt:stxt-core or stxt exports in its 1.0 is still there, with the same signature, in all of its 1.x releases. Each library has its own line (see below).

What is not frozen

  • The text of error messages. It gets refined and translated. What is stable is the code ([CHILD_NOT_DECLARED]), not the sentence next to it; a test or a script that compares messages will break sooner or later.
  • The convenience facades and adapters of the libraries —what exists to type less in the easy case, or to bind the library to a platform's file system or environment—. They are outside the normative scope and may grow or change shape within a 1.x; the core API they wrap may not.
  • The human-facing output of the command line: the layout of the validate report, the --help text. What goes to machines —the exit codes 0/1/2, --format json and the canonical tree— is stable.
  • The style rules (the sections marked SHOULD in the specifications): they are recommendations and may be refined without any document becoming invalid.

The specification version and the package version

Each specification carries its own number, major.minor, in its Metadata, and all five start at 1.0. They are independent: the core is expected to be very stable, while schema or template may evolve at their own pace, as XML Schema does with respect to XML. "STXT 1.0", said on its own, is the version of STXT-SPEC.

Each library carries its package version —@stxt-lang/core on npm, dev.stxt:stxt-core on Maven Central, stxt on PyPI—, which goes up when the library changes, not when the language does.

The rule that ties the two together: conformance is declared against the version of the specification, not of the package. If @stxt-lang/core is at 1.3 and dev.stxt:stxt-core at 1.1, they still read the same STXT: both implement STXT-SPEC 1.0. Each library exposes that version as a constant (SPEC_VERSION) and proves its conformance by running the conformance kit of the specification repository. A third-party port does the same.

How the numbers go up

The rule is in STXT-SPEC §1.1:

  • The major of a specification goes up if something that was valid stops being valid or changes meaning: a deliberate change of intent, not a clarification of the text.
  • The minor goes up if something is only added without invalidating anything.

The libraries follow semantic versioning within their line: an incompatible change in the in-memory API is a package major, and is announced as such. A specification major is a different matter and far less frequent: none is planned, and should one occur, the implementations would indicate it through SPEC_VERSION and it would come with an explanation and a migration path; never as a silent reinterpretation.