Specification · draft

Draft. This is the draft of the METAIS specification at commit f7f57020f4fe5067f6107bae90bb3ae07e1fa803, not a released revision. It may change before it is released.

4. Versions

Normative. Areas: VER.

A package names the version of this specification it targets, and carries a version of its own that its author assigns. This chapter specifies both versions, what compatibility a specification version promises within its major, and how a processor states the specification versions it implements and treats a package of a version it does not.

4.1 The specification version

A specification version is MAJOR.MINOR. It names a set of rules, so it has no patch part: a revision of this text that changes nothing a program can observe does not change the set. Revision 1.0 is the first; there is no 0.x.

MTS-VER-001 The manifest's metais member MUST be present, and a processor MUST refuse a manifest without it with package.version.missing, listing the specification versions it implements.

MTS-VER-002 metais MUST be a string, and a processor MUST refuse one that is a number, even one whose value looks right (metais: 1.0 in YAML is the number 1, and 1.10 would be 1.1), or of any other type, with package.version.not_string, giving the type and, for a number, the text as written.

MTS-VER-003 metais MUST match ^(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$, and a processor MUST refuse one that does not, such as "1" or "1.00", with package.version.malformed.

4.1.1 What a processor implements

A processor implements a set of specification versions, and within each major it implements every minor from .0 to its highest: one that implements 1.3 implements 1.0, 1.1 and 1.2. It processes a package under exactly the rules of the version the package declares: that minor's manifest schema, input forms, keywords, filters, tags, variables, transforms and findings.

MTS-VER-004 A processor MUST refuse a package that declares a major it does not implement with package.version.unsupported_major, giving the declared version and every version it implements, in ascending order.

MTS-VER-005 A processor MUST refuse a package that declares a minor newer than the highest it implements in that major with package.version.unsupported_minor, giving the declared version and every version it implements: it cannot know what a newer minor added, so it cannot tell a package it renders correctly from one it renders wrongly.

MTS-VER-006 A processor MUST judge metais before any other rule of the manifest's content and, when it refuses the version, report no other finding about the manifest: a manifest that names another set of rules cannot be judged by this one's.

MTS-VER-007 (not observable) A processor MUST make the specification versions it implements available on request, every one listed explicitly in ascending order of major and then minor, so a caller tests membership without knowing which minors imply which.

Note. metais, the reference tool, makes them available as the specification.implements member of metais version --json. TestVersion in internal/cli requires that member to equal the list Implements in internal/version returns, and the document's bytes to hold it as ["1.0"]; TestImplements in internal/version proves that list ascends by major and then minor and names every minor of a major from .0 to the highest.

4.1.2 What a minor promises

A minor adds only constructs that every earlier minor of the same major refuses: a manifest member, an enumeration value, an input form, a JSON Schema keyword not beginning x-, a filter, a tag, a variable member, a transform or one of its options, or a warning. A minor never changes what an accepted construct means, removes one, changes a default, refuses or renders differently any package and input set an earlier minor of the same major accepts, gives meaning to a JSON Schema keyword beginning x-, or asserts a format an earlier minor accepted without asserting it. So changing a package's metais from 1.m to any later 1.k, and nothing else, changes neither its validity nor any byte it renders, for any input set; it may add warnings.

Every statement this specification adds after 1.0 carries the minor that added it, so a processor carries the same table. A package that uses a construct added after the minor it declares is refused, naming the construct and the minor that added it; in revision 1.0 there is no such construct.

4.2 The package version

MTS-VER-008 The manifest's version member MUST be a Semantic Versioning 2.0.0 version of at most 128 characters, pre-release and build metadata allowed, and a processor MUST refuse one that is not, a leading v included, with manifest.pattern, and one that is not a string, such as version: 1.0 in YAML, with manifest.type.

A package's version is identity and information. A release is identified by its name and version together, and its bytes by its package digest (chapter 2). No processor compares one package's version with another's: there is no registry and no dependency between packages, so nothing needs precedence, and two versions differing only in build metadata are two releases.

MTS-VER-009 (not observable) An author SHOULD raise a package's major version when some input set the previous version accepted is refused or an output path it wrote for an accepted input set is no longer written, its minor version when every input set the previous version accepted is still accepted and writes at least the same output paths, and its patch version when the accepted input sets and output paths are unchanged and only output content changes.