STXTSemantic Text
ESEN .stxt

Stability and versions

A document that is valid in STXT 1.0 is valid across the whole 1.x line. This page states what 1.0 freezes, what it does not, and how to read the version numbers.

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 or JSON Schema with respect to JSON. "STXT 1.0", said on its own, is the version of STXT-SPEC: the base syntax is what defines what a document is.

Each library carries its package version, and that one is a number per product: @stxt-lang/core on npm, dev.stxt:stxt-core on Maven Central, stxt on PyPI. It goes up when the library changes —a new function, a fix—, not when the language does.

From this follows the rule: 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, because both implement STXT-SPEC 1.0. The three libraries expose that version as a constant (SPEC_VERSION) and stxt --version prints it next to the command line's own. A third-party port does the same: it declares which specification version it conforms to.

Up to 1.0 the three libraries have shared the same number and the same scope. From there on, the number that ties them together is the specification's; the package number follows the evolution of each one.

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 "clarification" that invalidates what a conforming implementation accepted counts too: the effect decides, not the intent.
  • 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.