Stability and versions

A date and a status, not a version number

The STXT specifications carry no version number. Each one carries, in its Metadata, two things:

• A date (Last modif): that of the last modification of its text, be it a typo or a change of rule. There is no version other than the current one, and a date identifies a text: "STXT-SPEC 2026-09-07" is that specification as it stood on that day.
• A status (Status): how much stability is promised. It has four possible values, in this order, and it only moves forward:

An incompatible change is one by which a document that was valid stops being valid or changes meaning: a deliberate change of intent, not a clarification of the text. The normative definition of the four statuses is in STXT-SPEC §1.1.

The status of each specification

"STXT", said on its own, is STXT-SPEC, and STXT-SPEC is in Zenith: what an STXT document is, how it is parsed and which tree it produces will not change. That is what backs the statement at the top.

Why Aurora for the other three. Schemas, templates and discovery define what it means for a document to conform to a definition and where that definition is looked for. They are younger than the core and have seen less real use, and we do not want to promise that they will not move an inch before we know it. Aurora is a deliberate step down from the "valid across the whole 1.x line" promise published on 2026-08-31 for all five, and we prefer to say it that way. What Aurora means in practice:

• An Aurora definition rests on a Zenith core: a schema or a template is an STXT document and never stops parsing. What could change is a validation or resolution rule, not the document.
• An incompatible change, should one come, is always announced, with the date on which it is made, which documents it affects and how they adapt; it is never a silent reinterpretation.
• The move of each one to Zenith will be announced with its date, and from then on the same promise as for the core applies.

What is frozen

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 date and the package version

The specifications carry a date and a status, each its own, independent of the others': the core is in Zenith while schema, template or discovery may evolve at their own pace, as XML Schema does with respect to XML.

The libraries carry their package version —@stxt-lang/core on npm, dev.stxt:stxt-core on Maven Central, stxt on PyPI—, under semantic versioning, which goes up when the library changes, not when the language does. An incompatible change in the in-memory API is a package major, and is announced as such.

The rule that ties the two together: conformance is declared against the specification, not against the package, and is proved with the conformance kit of the specification repository. The kit carries its own date and pins the date of every specification it certifies; a conforming implementation exposes the STXT-SPEC one as a constant, SPEC_VERSION, with a YYYY-MM-DD value. If @stxt-lang/core is at 1.3 and dev.stxt:stxt-core at 1.1, they still read the same STXT: both expose the same date and pass the same kit. A third-party port does the same.

How a status moves forward, and how it is announced

• A status only moves forward: Genesis → Aurora → Zenith → Twilight. A specification never returns to an earlier status, and Twilight is terminal.
• Each step, and each incompatible change in Aurora, is announced with its date: in the specification itself (Status and Last modif), in the release notes of the specification repository and on this page. The conformance kit is regenerated with the new date, and the ports that pass it expose it in SPEC_VERSION.
• A specification in Zenith does not leave Zenith backwards. Should the core ever need an incompatible change, there would be no "STXT 2": there would be a new specification, with a new name, living alongside this one, and today's documents would stay valid and keep their meaning.
• Clarifications of the text that do not change the specification's intent only update Last modif; they change neither the status nor the meaning of any document.