ascribe.toml format contract: how content varies

The normative contract for the content model’s dimensions, versions and releases, lifecycle states, and features.

Part of the ascribe.toml format contract, whose contents list every section. What these keys are for, with examples, is in the reference’s how content varies.

11. [dimensions.<name>]

A dimension is an axis content varies along (SPEC §4.3), and whose values are availability targets (SPEC §4.4).

[dimensions.deployment]
label = "Deployment"
values = ["cloud", "self-managed"]
versionless = ["cloud"]
labels = { cloud = "Quill Cloud", self-managed = "Self-managed" }

<name> is the dimension’s name (key rule, §1.2). It’s written as an attribute key in @variant, as a key in variant frontmatter and build selections, and as a target in availability specs, where it stands for all its values.

Rules (§25.4): a value MUST NOT belong to two dimensions (model-dimension-value-shared), and dimension names and values are subject to the one-role rule (model-name-multiple-roles).

12. [versions]

How versions in availability specs are compared (SPEC §4.4). Which release is current is a target’s own, in [releases.<target>] (§12.1).

[versions]
scheme = "numeric"

The numeric scheme. A version is any string matching SPEC Appendix A’s version rule: numbers separated by dots (3, 3.4, 3.4.1). Versions compare component by component, numerically, from the left, with missing trailing components treated as 0: 3.4 equals 3.4.0, 3.10 is later than 3.9, and 4 is later than 3.99.1. Leading zeros don’t matter (3.04 equals 3.4). This is semantic versioning’s major.minor.patch ordering. It has no pre-release or build suffixes, because the spec’s grammar doesn’t allow them; express a pre-release with a lifecycle state (preview 3.4) instead.

Rules (§25.5): scheme MUST be "numeric" (model-invalid-value). current MUST NOT be set (model-versions-current): a target’s current release is its newest live line in [releases.<target>].

12.1 [releases.<target>]

The release lines of a versioned target, by the target’s name. A line is a version as the list writes it, and holds every version that starts with its parts: 3.4 holds 3.4, 3.4.2, and 3.4.2.1. A project chooses how fine its lines are by how it writes them: ["3.4", "3.5"] for a line for each minor release, ["0.2.0"] for one for each patch release. The newest live line is the target’s current line; it isn’t written down, so it can’t disagree with the list.

[releases]
planned-label = "planned"

[releases.self-managed]
live = ["3.4", "3.5"]
planned = ["3.6"]

[releases.self-managed.ends]
"3.4" = 2027-01-31

[releases.self-managed.archived]
"3.3" = { url = "https://docs.example.com/archive/3.3/", ended = 2026-06-30 }
"3.2" = {}

The target is a versioned value of a declared dimension, such as self-managed, or a name no dimension has. [releases.<target>] declares a name no dimension has as a value of the implicit dimension release, which exists only while it has a value. [releases] label is the dimension’s label, Release unless set, and [releases.<target>] label is the target’s, its name unless set:

[releases.ascribe]
label = "Ascribe"
live = ["0.4.1"]

Everything that names a dimension names release as it names a declared one: @variant {release=ascribe}, a switcher’s sync, a build’s variants, dimension: targets in ascribe refs, and the elements’ dimension attribute. It comes after the declared dimensions in their order.

[releases] takes two keys of its own, beside the targets’ tables:

Rules. <target> MUST be a declared dimension value that isn’t versionless, or a name (name-word) that’s no declared dimension’s value or name, which declares it a value of the implicit dimension release. A loader MUST add the implicit dimension, after the declared ones, when at least one target is left to it, and only then. While one is, a declared dimension MUST NOT be named release, and each such target is the error (model-releases-target). [releases.<target>] label MUST NOT be set for a target a declared dimension has (model-releases-target). The implicit dimension’s name and values are subject to the one-role rule (model-name-multiple-roles). Each line MUST be a version (SPEC Appendix A rule version), listed once, and every line of one target, in every list, MUST have the same number of parts (model-releases-line). A line MUST be in one list, every planned line MUST be newer than every live line, and every archived line older (model-releases-order). A key of ends MUST be a live line, as written (model-releases-ends), and its value a TOML local date (model-wrong-type). A key of archived is a line as written, and its table MAY have url, a non-empty string, and ended, a TOML local date, and no other key. planned-label MUST NOT be empty. The order of a list carries no meaning.

13. [lifecycle.<state>]

Lifecycle states (SPEC §4.4). Five are built in:

A project adds states by declaring them, and can change the available flag or label of a built-in state. Built-in states can’t be removed.

[lifecycle.sunset]
available = false
label = "sunset"

[lifecycle.beta]
label = "Beta"

<state> is the state’s name (name-word).

Rules (§25.4): ga MUST count as available (model-lifecycle-ga-unavailable). A new state MUST set available (model-lifecycle-available-required). Lifecycle states, built-in ones included, are subject to the one-role rule (model-name-multiple-roles).

14. [features.<key>]

The features registry (SPEC §4.4): named availability specs, so a feature going generally available takes one edit.

[features.streaming-sync]
name = "Streaming sync"
available = "cloud, self-managed preview 3.4"

<key> is the feature key (name-word). Writing it as a whole @available primary, or as the whole available frontmatter value, stands for the spec.

Rules (§25.4): a feature’s spec MUST parse as an availability spec (model-availability-syntax); each of its targets MUST be a declared dimension value or dimension name, and each state a declared state (model-availability-unknown-name); a versionless target or a dimension name MUST NOT have versions (model-availability-versionless); a history MUST be in chronological order (model-availability-history-order); and the spec MUST NOT be a feature key (model-feature-nested). Feature keys are subject to the one-role rule (model-name-multiple-roles).