Skip to content

REFERENCE · 21

The developer-hosted registry grammar.

A registry is a git-hosted YAML file that mirrors the resolution fields of the payloads it serves, so the dispatcher can select the right artifact for the operator's platform without downloading every image. This page is the grammar of that file.

What it defines.

A registry is ANY git host repo carrying tpkg-registry.yaml; the git host’s releases ARE the storage. The registry MIRRORS only resolution-relevant fields (L3) — the dispatcher resolves, and selects the host-triplet artifact DECLARATIVELY, without downloading every payload.

Identity.

Field Value

schema

tpkg-registry

schema_version

1

schema_minor

10

status

normative

owner

crates/tebako-resolve (the model) in tamatebako/tebako

Sections.

Section What it declares

schema_version

This schema’s MAJOR (1).

signing

The registry’s signing-key self-description: key (armored OpenPGP public key, block scalar), fingerprint (the key’s OWN primary fingerprint, 40 hex — the add-registry gate refuses a mismatch as the registry’s malformation), url (optional https cross-check location).

payloads

Names unique.

The full grammar.

# =============================================================================
# tpkg-registry.yaml — the developer-hosted registry grammar (spec 18 §2.2,
# C8/C12; spec 04 §2 formalized)
#
# A registry is ANY git host repo carrying tpkg-registry.yaml; the git
# host's releases ARE the storage. The registry MIRRORS only
# resolution-relevant fields (L3) — the dispatcher resolves, and selects
# the host-triplet artifact DECLARATIVELY, without downloading every
# payload.
#
# SSOT: this file owns the grammar; crates/tebako-resolve/src/registry.rs
# (the model of record, one model — parse + validate) mirrors it. `tebako
# publish` validates against it before pushing (C12, producer-side).
# =============================================================================

schema: tpkg-registry
schema_version: 1 # MAJOR — breaking changes only
schema_minor: 10 # MINOR — additive changes only (1: engine/implementation on kind:runtime entries, 2: the version-level implementation compat read documented + the runtime_requirement mirror's implementation key, 3: the per-triplet oci mirror (spec 38 §7), 4: the blksum sidecar pins (spec 39 §3), 5: the runtime_requirement mirror's abi rule — carried only when one value holds for the whole entry (tebako#440), 6: the per-row release.ref — a platforms[<triplet>] entry names the shard tag serving its bytes when a version line unions per-platform shard releases (tebako#711), 7: the head signing: block — the registry's self-description of its signing key for the add-registry TOFU pin (spec 09 §9.1, tebako#617), 8: the one-grammar lock (tebako#549) — payload-level engine/implementation is the ONLY authored spelling of the runtime axis; the version-level spellings stay reader-compat (MINOR 2) but the producer gate (tebako registry validate) names the old spelling, the mixed spelling, and the parse-dropped version-level engine key, 9: the variant dimension (spec 28 §2–§3, tebako#557) — a version entry carries EITHER the shorthand (platforms + runtime_requirement) OR variants: (a list of {runtime_requirement?, platforms, blksum?} arms, keyed by requirement), plus the payload-level default_variant, 10: the row's mirrors: list (spec 04 §2) — ordered fallback references held to the row's sha256 pin)
status: normative
owner: crates/tebako-resolve (the model) in tamatebako/tebako
edge: C8 (loader → registry), C12 (everything → registries)

# The schema evolution law (spec 18 §3) — every schema in this registry
# obeys it; per-schema specializations are noted under `notes:`.
evolution:
  major_minor: >-
    schema_version is a single integer MAJOR; schema_minor an additive
    counter. MAJOR breaks, MINOR adds.
  unknown_fields: >-
    Readers ignore unknown fields within their MAJOR — but never invent
    semantics for them. A field you do not understand changes nothing you do.
  unknown_major: >-
    A named refusal naming the artifact, its schema + version, the consumer
    and its max spoken version, and "upgrade". Exit code per spec 18 §7.
    (S45: newer MAJOR → upgrade refusal.)
  missing_schema_version: >-
    Era 1 — a named refusal ("pre-era document; regenerate with a current
    tool"), never a silent default. (S46: "republish the registry".)
  type_changes: >-
    MAJOR only — no silent coercion (string→list, int→string, kebab→snake).
    Renames ride the deprecation window.
  deprecation_window: >-
    To rename/retype a field inside one MAJOR: writers emit BOTH old and
    new for two consecutive MINOR versions (noted under `deprecated:` with
    the window dates); readers prefer new and warn on old; after two MINORs
    the old field is dropped in the next MINOR.
  critical_flag: >-
    Any container that skips unknown entries supports `critical: true` on
    an entry: a reader that does not understand a critical entry refuses
    with a named error instead of skipping it (spec 18 §3.7).
  lists_stay_lists: >-
    Ordered/multiplicity data is a list of entries carrying their identity
    fields — never keyed maps. (Here: payloads and versions are LISTS;
    entries carry `name:` / `version:`. The per-triplet artifact selection
    is the one sanctioned map — a host-triplet index, not multiplicity
    data.)

declaration:
  where: tpkg-registry.yaml at a git host repo's default-branch root (contents API), as a release artifact, or at a tfs+git path (spec 04 §2 — exactly one location per form)
  format: YAML (authored-manifest rule, invariant 6)

grammar:
  schema_version: {type: int, required: true, notes: this schema's MAJOR (1)}
  signing: {type: map, required: false, notes: "MINOR 7 (spec 09 §9.1) — the registry's signing-key self-description: key (armored OpenPGP public key, block scalar), fingerprint (the key's OWN primary fingerprint, 40 hex — the add-registry gate refuses a mismatch as the registry's malformation), url (optional https cross-check location). Pre-MINOR-7 readers ignore the block (additive); the TOFU consent and pin are tebako add-registry's"}
  payloads:
    type: list
    required: false
    notes: names unique
    entry:
      name: {type: string, required: true, notes: single non-empty path component (a cache key)}
      kind: {type: enum, values: [app, data, toolkit, runtime, language], required: true}
      engine: {type: string, required: false, notes: "REQUIRED when kind: runtime (MINOR 1) — the edge-discovery key (spec 30 §1): kind:runtime edges resolve by (engine, implementation?, constraint); a runtime entry without engine: is pre-discovery legacy and invisible to edges. Payload level only (MINOR 8): an engine: key on a version row parses to NOTHING (the model has no slot for it) — the producer gate names the misplaced key"}
      implementation: {type: string, required: false, notes: "spec 28 §8's implementation axis (e.g. temurin); an edge naming an implementation matches only entries carrying the same value. Compat read (MINOR 2): registries published before MINOR 1 carried `implementation` at VERSION level — that spelling is read when the payload-level key is absent and every version carrying it agrees; it never wins over the payload-level key. MINOR 8 (tebako#549): the payload-level spelling is the ONLY authored one — the producer gate names the version-level spelling (and a mix of both) an authoring violation; the reader stays lenient so already-published registries keep resolving"}
      versions:
        type: list
        required: true
        notes: N>=1; versions unique per payload
        entry:
          version: {type: string, required: true}
          implementation: {type: string, required: false, notes: "the pre-MINOR-1 spelling of the payload-level axis (MINOR 2's compat read) — never authored anew; payload-level wins when both are present. The producer gate names any version-level spelling an authoring violation (MINOR 8)"}
          platforms:
            type: "\"universal\" | map(vcpkg triplet → {artifact, sha256, oci?, blksum?, mirrors?, release?})"
            required: "iff variants: is absent (MINOR 9's MECE law — exactly one of the two forms)"
            notes: >-
              The declarative host-triplet selection (spec 04 §2):
              `universal` for pure-language payloads (one artifact, the
              single-.tfs rule), else the triplet → artifact map. The
              dispatcher reads platforms[host].artifact — never
              adapter-side guessing. The additive `oci` field (spec 38,
              MINOR 3) mirrors the artifact's OCI locator
              (`tfs+oci://<host>/<repo>:<tag>` — the tag derives per
              artifact class, spec 38 §3: `<version>-<triplet>` for
              payloads, the bundle stem for runtime bundles); readers
              ignore it unless the registry book declares `channel: oci`,
              and pre-OCI readers skip it as an unknown key. The
              additive `blksum` field (spec 39 §3, MINOR 4) pins the
              artifact's lazy-mount digest sidecar:
              `{filename, sha256}` — the sidecar
              (`<artifact>.blksum.json`, published beside the image) is
              fetched and verified against this sha256 BEFORE the first
              range read, exactly like `image.sha256` anchors the image;
              mirror-only (spec 03 §4's tier-3 rule), and covered by the
              index's signature exactly like `image.sha256` where the
              index is signed (spec 09 §5). Present but torn (a missing
              or empty half) is a named validation error — the loud
              blksum-missing eager fallback (spec 39 §3) applies to an
              ABSENT pin, never a broken one. The additive `release`
              field (MINOR 6, tebako#711) is the row's own shard release
              ref — `{ref: tfs:<service>:<owner>/<repo>:<shard-tag>}`,
              the same grammar discipline as the version-level ref under
              per-triplet platforms (no #artifact, no ?sha256= pin, a
              service release): when a version line unions rows from
              several per-platform shard tags, the version-level ref
              cannot name the tag serving a given row's bytes, so the row
              carries it. MINOR readers prefer the row's ref over the
              version-level one; pre-MINOR readers ignore it as an
              unknown key. The additive `mirrors` field (MINOR 10, spec
              04 §2) is the row's ordered fallback locators — ordinary
              references serving the SAME bytes, tried after the primary
              and held to this row's `sha256`; each member must parse
              (a producer-gate refusal, never skipped), and the list is
              non-empty when present.
          variants:
            type: "list of {runtime_requirement?, platforms, blksum?}"
            required: "iff platforms: is absent (MINOR 9, spec 28 §3 — the variant dimension)"
            notes: >-
              One arm per (runtime_requirement × platforms) build of the
              same version (tebako#557). MECE with the shorthand: an
              entry carries EITHER top-level platforms:/runtime_requirement:
              OR variants:, never both — both present, neither present, a
              duplicate derived variant id inside one version, a variant
              requirement carrying abi: with no implementation, and
              implementation-spanning variants with no payload-level
              default_variant are all named registry validation errors
              (spec 28 §10). The variant id DERIVES from the requirement
              (spec 28 §2: universal when no abi-line is in force, else
              <engine>-<implementation>-<X.Y>); it is never authored. Each
              arm's platforms is the same grammar as the shorthand's
              (universal | triplet map); an arm's blksum pin lives at the
              arm level when that arm is universal (the version-level
              blksum belongs to the shorthand's universal row alone —
              variants + version-level blksum is a named error). The abi
              mirror rule is per-arm (MINOR 5's one-value-holds rule
              applied to the arm's platforms). No-selector resolution
              picks the payload's default_variant if declared, else the
              newest requirement line (spec 28 §4 rule 1). Pre-MINOR-9
              readers see a variants-only entry as a version with no
              top-level platforms: and refuse it loudly (the clean break).
            entry:
              runtime_requirement: {type: map, required: false, notes: "the arm's key — the same shape as the shorthand's mirror"}
              platforms: {type: "\"universal\" | map(vcpkg triplet → {artifact, sha256, oci?, blksum?, mirrors?, release?})", required: true}
              blksum: {type: map, required: false, notes: "the arm-universal row's sidecar pin (the version-level rule applied per arm)"}
          blksum:
            type: map
            required: false
            notes: >-
              The UNIVERSAL row's sidecar pin (spec 39 §3, MINOR 4) —
              same `{filename, sha256}` shape as the per-triplet field.
              A `platforms: universal` row names ONE artifact by the
              single-.tfs rule, so its pin lives here at the version
              level; spelled on a per-triplet row it is a named
              validation error (exactly one location per form).
            fields:
              filename: {type: string, required: true, notes: "the sidecar's asset name within the same release (<artifact>.blksum.json)"}
              sha256: {type: string, required: true, notes: 64 lowercase hex — the sidecar bytes' digest}
          mirrors:
            type: list of strings
            required: false
            notes: >-
              The UNIVERSAL row's ordered fallback locators (spec 04 §2,
              MINOR 10) — ordinary references serving the SAME bytes as
              the primary. Same one-location rule as `blksum`: valid on
              a `platforms: universal` shorthand row only (a per-triplet
              entry carries its list in the platforms map); spelled on a
              variants entry, or on a per-triplet row at the version
              level, it is a named validation error. A universal row
              pins nothing but its ref's `?sha256=`, so a list under a
              ref without that pin is the named authoring error — the
              mirror chain holds to that digest or the install has
              nothing to hold it to.
          release:
            type: map
            required: true
            fields:
              ref: {type: string, required: true, notes: "a spec 04 §1 reference (any class); for kind: runtime entries it ALSO derives the per-engine download base (spec 05 §2's chain, registry-derived step)"}
          signature:
            type: map
            required: false
            fields:
              keyid: {type: string, required: true, notes: 16 lowercase hex}
              asc: {type: string, required: true, notes: asset name within the release, or a full reference}
          runtime_requirement:
            type: map
            required: false
            fields:
              engine: {type: string, required: true}
              constraint: {type: string, required: true}
              abi: {type: string, required: false, notes: "the runtime's platform string for native-extension payloads (resolution checks BOTH lines). MINOR 5 (tebako#440): the abi is per-triplet by construction — the mirror carries it only when one value holds for the WHOLE entry (a universal or single-platform row); a multi-platform per-triplet entry OMITS it, and the authoritative per-platform abi lives in each slice's embedded manifest"}
              implementation: {type: string, required: false, notes: "spec 28 §8 (MINOR 2) — the mirror of the L1 entry's implementation key; REQUIRED in the mirror when abi is present (an abi is per-implementation), absent for pure-language payloads. The mirror stays the single-map form: an L1 any_of list mirrors its first entry (the full set rides the embedded manifest L1)"}
          entrypoints:
            type: list of string
            required: false
            notes: the command names the payload PROVIDES; each becomes a registered shim at install
      default: {type: string, required: false, notes: the registry-side default version (the version chain's last resort)}
      default_variant: {type: string, required: false, notes: "MINOR 9 (spec 28 §3–§4) — the no-selector variant pick: names a derived variant id of the default version's variants:; absent → the newest requirement line wins. Naming no variant of the default version is a named validation error; implementation-spanning variants REQUIRE it"}

refusals:
  - case: schema_version absent (S46)
    behavior: era-1 refusal — "republish the registry"
  - case: schema_version MAJOR newer than the reader speaks (S45)
    behavior: upgrade refusal (both versions printed)
  - case: entry abi has no host match (S47)
    behavior: filtered; named error when nothing remains
  - case: registry unreachable and the cache older than the 24 h TTL (S48)
    behavior: the stale cache serves with a loud stderr warning + journal line (spec 05 §4, roadmap 86); cache ABSENT stays the named error (TEBAKO_OFFLINE=1 = cache-or-named-error)

deprecated: [] # no field is in a deprecation window

The source of truth is docs/spec/schemas/tpkg-registry.yaml in the product repository; this page is regenerated from it by tools/sync-schemas.rb.