Section 6.6 Experimental Constructs

The schema comes in two versions. The production schema describes the stable PreTeXt vocabulary: constructs we expect to support indefinitely, and to change only through a formal deprecation cycle that announces the change and provides for a smooth conversion. The development schema contains everything in the production schema, plus experimental constructs: features that work today, and may even be in wide use, but whose markup may still change—possibly without notice, and without the usual deprecation machinery. New features enter the development schema first, and are promoted to the production schema once their design settles.

Validation consults both versions, and its report keeps the two concerns separate. Errors are judged against the development schema, so a document employing experimental features is not flooded with complaints about them, and a genuine mistake cannot hide in that flood. A separate section of the report is an inventory of the experimental constructs in use: each is located precisely (file, path, line) and accompanied by advice about what it is and what is most likely to change. The inventory is not a list of errors. It is there so you can weigh the risk of relying on experimental features, and so you can recognize the cause if one of them changes underneath you.

If you validate within an editor using a schema file directly, you face a choice the report does not ask you to make: the production schema will complain about every experimental construct, while the development schema accepts them all without comment. Point your editor at whichever matches your project’s appetite for risk, and let the validation report be the authority on which construct is which.