The registry
On this page
- Status
- 1. Terms
- 2. Documents
- 3. Kind declaration
- 4. Registry document
- 5. Overlays
- 6. References
- 7. Validation
- 8. Resolution
- 9. YAML import
- 10. Facts
- 11. Emitters
- 12. Diagnostic codes
- 13. Versioning and stability
- 14. Machine-readable form and rows
- 15. Conformance classes
- 16. Security and privacy
- 17. What this text settles, and what is open
Status
This document is a companion document of the Judgment Pack specification. It defines a registry format: kind declarations, registries, overlays and references; their validation, and their resolution for one environment; the YAML subset they are authored in; the facts documents and facts contracts through which a pack judges registry entries; and the contract between a host and the emitters that turn resolved registries into files.
This text is registry format 1.0.0, status released. The version is this document's own: it is
not a Core specVersion, and no pack declares it. The companion is released on its own scoped tag,
registry-v<major>.<minor>.<patch>, beside Core and independent of specVersion; its first
release is registry-v1.0.0 (§13). A text no registry tag released is normative for nothing, and
no conformance claim may cite it. This text, released on registry-v1.0.0, is normative for the
conformance classes of §15, and for nothing else. Publication beside a Core release, on the site or
in a Core bundle, releases nothing.
Its design records are RFC 0034 (the profile),
RFC 0035 (references),
RFC 0036 (the emitter contract) and
RFC 0037 (facts contracts), accepted on 2026-11-16,
and they are informative. A fifth record of the same line,
RFC 0038, defines a source kind of the dialect, and its
text is in the dialect companion (dialect.md §4.5), where the dialect's source kinds
are defined. The maintainer accepted the five on one review round by a model from the drafting
vendor, with the different-vendor review of the interim review regime waived, as each record's
Acceptance section says. That is a same-vendor review, not a cross-vendor claim. Where this text
and a record differ, this text governs; §17 lists what this text settles that the records left
open, and what it leaves open.
Version 1.0.0 is released, on registry-v1.0.0, and not yet stable, the bar its records set:
- Its rows are published. Its machine-readable code list and its hand-written, synthetic
rows under
conformance/registry/1.0.0/(§14) are in that release's own bundle, and its release record names each file's digest (§13). No Core bundle carries them, and the site does not serve them. - Its schemas are published. The closed schemas of its documents under
schema/registry/1.0.0/(§14) are in the same bundle, and the site serves each at its$id, and not as a file. No Core bundle carries them. - One reader exists. The reference runtime (Go) implements §§2 to 10, and §11's host and
harness since
v0.48.0. No second, independently written reader, host or harness exists. The stable bar is two readers agreeing on every row (§15).
Core is unchanged by this document. A registry is not a pack, no Core document carries a registry selector, and every pack Core accepts it still accepts, with the same results. A facts document of §10 is an ordinary facts document to Core.
1. Terms
The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY have their BCP 14 meanings only in capitals.
- A kind declaration (§3) names a kind of entry and fixes the schema of its values, which of its members are secret references, entry references or overlayable, and its bounds.
- A registry (§4) lists environments, owners, the kind declarations it pins, its entries and its overlays. An entry is one value of one kind, with an id and an owner, that applies in some of the registry's environments.
- An overlay (§5) holds one environment's patches, each of which replaces values in one entry for that environment.
- Resolution (§8) gives one environment's resolved registry: every entry that applies there, with its patches applied.
- A reference (§6) is a string at a declared position: an entry reference names another entry, and a secret reference names one pinned version of a secret in a store.
- A reader validates registries and resolves them (§§2 to 8). An importer converts YAML to registry documents (§9). A facts writer maps resolved entries to facts documents and generates facts contracts (§10). An emitter is a program that reads a request and answers with files; a host runs it (§11). §15 makes these conformance classes.
- Code-point order compares two strings by their Unicode code points, first difference first. For the strings this document orders (member names, kind names, ids, pointers and the like), it is the order of their UTF-8 bytes. JCS is the RFC 8785 canonical form of a JSON value.
- A pointer is an RFC 6901 JSON Pointer. "At
p" names the position a pointerpaddresses;""is the whole document.
2. Documents
2.1 Documents and selectors
The companion defines these JSON documents. Each carries an exact format selector at its root. A reader that does not support that exact selector MUST refuse the document. There are no aliases and no compatible selectors.
| Document | Selector member | Value in 1.0.0 |
Section |
|---|---|---|---|
| Kind declaration | kindFormatVersion |
"1.0.0" |
§3 |
| Registry | registryFormatVersion |
"1.0.0" |
§4 |
| Resolved registry, one environment | resolvedFormatVersion |
"1.0.0" |
§8 |
| Validation report | reportFormatVersion |
"1.0.0" |
§7.4 |
| Facts contract | factsContractVersion |
"1.0.0" |
§10.3 |
| Pack check report | factsCheckFormatVersion |
"1.0.0" |
§10.5 |
| Emitter manifest | emitterManifestVersion |
"1.0.0" |
§11.1 |
| Emit request | emitRequestVersion |
"1.0.0" |
§11.2 |
| Emit response | emitResponseVersion |
"1.0.0" |
§11.3 |
| Harness report | harnessReportVersion |
"1.0.0" |
§11.5 |
The pack check report has its own selector, and so does every other document a reader writes. The
facts document (§10.1) has none: it is a facts document of Core, and its bytes follow from a
resolved registry. A change to the facts document's bytes is therefore made only under a new
resolvedFormatVersion, never under the same one.
2.2 Admission
A reader admits a kind declaration, a registry, a facts contract and a resolved registry by these steps, in order. Each refusal names its document (§7.3). Admission is validation's step 1 (§7.1).
- Size. A document longer than its bound is refused,
REG-DOC-SIZEat"", without being parsed. A reader that stops reading at the bound gives the same diagnostic.
| Document | Bound |
|---|---|
| Kind declaration | 256 KiB (262 144 bytes) |
| Registry | 8 MiB (8 388 608 bytes) |
| Resolved registry | 8 MiB |
| Facts contract | 8 MiB |
| Nesting depth of any of these | 32 |
Depth counts containers: the root object is at depth 1, and each object or array inside a container is one deeper than it.
- Parse. The bytes are read as one JSON value (RFC 8259). One failure refuses the document, with no later step, and it is chosen in this order:
- bytes that are not UTF-8, anywhere in the input:
REG-DOC-JSONat""; - otherwise, reading the value from its first byte, whichever of these is reached first:
a syntax error, a byte-order mark included (
REG-DOC-JSONat""); an object or array that opens at depth 33 (REG-DOC-DEPTHat its pointer); or a member name that an earlier member of the same object has, compared as decoded, reached at the name and before its value is read (REG-DOC-DUPLICATEat the later member's pointer); - otherwise, anything after the value but whitespace:
REG-DOC-JSONat""; - otherwise, a string whose escapes encode a lone surrogate:
REG-DOC-STRINGat"".
So {"a":1,"a":2,"b":} is REG-DOC-DUPLICATE; {"a":1,"a":2} followed by the byte FF is
REG-DOC-JSON; and a lone surrogate escape before a repeated member name is
REG-DOC-DUPLICATE.
-
Numbers. Every number outside the number rule below is
REG-DOC-NUMBERat its pointer. All of them are reported, and a document with one is refused. -
Selector. A root that is not an object is
REG-DOC-SELECTORat"". A root whose selector member is missing, is not a string, or is not a selector the reader supports isREG-DOC-SELECTORat the selector member's pointer, such as/kindFormatVersion.
The number rule. These documents are I-JSON (RFC 7493), and every number is one of these:
- a literal with no fraction and no exponent is an integer, and its magnitude is at most 2^53 − 1 (9 007 199 254 740 991);
- any other literal is finite, and its exact decimal value equals the exact decimal value of the
shortest decimal that reads back as the same IEEE 754 double. So
1.5,1.50,0.1,1e2and20.000are admitted, and0.10000000000000001and9007199254740993.0are not.
No number is negative zero, in any form (-0, -0.0, -0e0), because its canonical form would be
0. Every other zero is admitted.
Admitted form. Admission replaces each number by its canonical form, and every later step
reads that form, never the literal as written. An integer literal is its own canonical form. Any
other literal is written as JCS writes the double it equals: 20.000 becomes 20, 1.50 becomes
1.5 and 1e2 becomes 100. So trailing zeros after the point, and an exponent, never outlive
admission, and an admitted number is at most 25 bytes. The rule adds no bound beyond the number
rule above. A reader may refuse early a literal other than zero that has more than 17 significant
digits, counted once leading and trailing zeros are dropped, or whose leading significant digit's
exponent is outside −324 to 308, because no such literal meets it; it is REG-DOC-NUMBER
(step 3). So 1.00000000000000000000 is admitted as 1, and 0e999999 as 0.
A number is compared, and is canonical, by its value: 1.50 and 1.5 are the same number, and
both are written 1.5 in JCS.
2.3 Canonical form and digests
A document's identity bytes are its JCS bytes. A digest is sha256: followed by the 64 lowercase
hexadecimal digits of the SHA-256 of the bytes it names. A pin's digest (§4), a registry's digest
in a report and in a resolved registry, and a contract's digest are digests of JCS bytes.
The one digest of a document's bytes as supplied is a location's kindDocument (§7.3): it names a
kind declaration that may not parse, so it cannot be a digest of its canonical form.
Every document this companion writes (a resolved registry, a facts contract, a report, a request) is written as its JCS bytes. A command line may end its output with one line feed, which is not part of the document.
3. Kind declaration
{
"kindFormatVersion": "1.0.0",
"id": "https://example.invalid/kinds/db-role",
"version": "1.2.0",
"kind": "db-role",
"owner": "platform-data",
"description": "A database role a service connects as.",
"entryId": { "pattern": "^[a-z][a-z0-9-]{0,62}$" },
"schema": {
"type": "object",
"required": ["database", "privileges"],
"additionalProperties": false,
"properties": {
"database": { "type": "string", "maxLength": 63 },
"privileges": { "type": "array", "items": { "enum": ["read", "write", "admin"] }, "uniqueItems": true },
"password": { "type": "string" },
"connectionLimit": { "type": "integer", "minimum": 1, "maximum": 500 }
}
},
"secrets": ["/password"],
"references": [ { "pointer": "/database", "kinds": ["database"] } ],
"overlayable": ["/connectionLimit", "/password"],
"bounds": { "maxEntries": 1000, "maxEntryBytes": 16384 }
}
3.1 Members
A kind declaration has these members and no other. id, version, kind, owner and schema
are required, besides the selector; the rest are optional. A member not listed is
REG-KIND-UNKNOWN-MEMBER at its pointer, a required member that is absent is
REG-KIND-MISSING-MEMBER at the pointer it would have, and a member that is not of its form is
REG-KIND-FORM at its pointer unless a code below is named.
| Member | Form |
|---|---|
id |
an absolute URI (RFC 3986 absolute-URI: a scheme and no fragment) of at most 2048 characters, with no white space |
version |
SemVer 2.0.0, with no build metadata |
kind |
the local name entries use, matching ^[a-z][a-z0-9-]{0,62}$ |
owner |
1 to 128 characters from A–Z, a–z, 0–9 and ., _, @, /, - |
description |
a string, informative |
entryId |
an object of exactly one member, pattern, a string in the pattern subset (§3.4). A pattern outside the subset is REG-KIND-PATTERN at /entryId/pattern. The default is ^[a-z][a-z0-9-]{0,62}$ |
schema |
the schema every entry's resolved value satisfies, in the subset of §3.2 |
secrets |
an array of pointer patterns (§3.5): the positions that hold a secret reference (§6.3) |
references |
an array of objects of exactly two members, pointer, a pointer pattern, and kinds, a non-empty array of distinct kind names: the positions that hold an entry reference (§6.2) to an entry of one of those kinds |
overlayable |
an array of pointer patterns: the positions an overlay may set (§5). The default is empty |
bounds |
an object of maxEntries, an integer of at least 1 (default 10 000), and maxEntryBytes, an integer from 1 to 8 388 608 (default 65 536), each optional |
deprecated |
a boolean. A pinned kind that is deprecated is the warning REG-KIND-DEPRECATED (§7.1, step 4) |
The owner is an opaque identity. This companion gives it no meaning, and enforcement (who may change a kind) is the repository's own review rule.
Inside these members, diagnostics are located as follows:
- in
secretsandoverlayable, an item that is not a string, or repeats an earlier item, isREG-KIND-FORMat the item; a string that is not a pointer pattern isREG-KIND-POINTER-FORMat the item; - in
references, an item that is not an object, or whosepointeris not a string, or whosekindsis not an array or is empty, isREG-KIND-FORMat the item; a member of an item other thanpointerandkindsisREG-KIND-UNKNOWN-MEMBERat that member; akindsitem that is not a kind name, or repeats an earlier one, isREG-KIND-FORMat/references/<i>/kinds; apointerthat is not a pointer pattern isREG-KIND-POINTER-FORMat/references/<i>/pointer; - in
bounds, an unknown member isREG-KIND-UNKNOWN-MEMBER, and a value out of its rangeREG-KIND-FORM, each at that member.
A pointer pattern of secrets, overlayable or references that can match no position the schema
allows (§3.5) is REG-KIND-POINTER-UNREACHABLE at it. This is decided only when the schema
compiled with no diagnostic. A pattern of secrets that can match a position a pattern of
references can match is REG-KIND-POINTER-CONFLICT at /secrets/<i>.
A kind declaration with any diagnostic of step 1 or step 2 (§7.1) is unusable. A registry that pins it is invalid, and its entries are not checked (§7.1).
3.2 The schema subset
A kind's schema is a JSON Schema 2020-12 schema restricted to the keywords below, and read with
JSON Schema's meaning, as §7.2 states it. Any other keyword, including $schema, $id,
$dynamicRef, format, oneOf, if, then, else, patternProperties, dependentSchemas
and unevaluatedProperties, is REG-KIND-SCHEMA-KEYWORD at its pointer. The keyword is not
ignored: it makes the declaration unusable.
| Group | Keyword | Form (otherwise REG-KIND-SCHEMA-FORM) |
|---|---|---|
| Type | type |
a type name, or a non-empty array of distinct type names, from null, boolean, object, array, number, integer and string |
enum |
a non-empty array; more than 1 024 values is REG-KIND-SCHEMA-LIMIT |
|
const |
any value | |
| Objects | properties |
an object whose members are subschemas |
required |
an array of distinct strings | |
additionalProperties |
a subschema | |
minProperties, maxProperties |
a count | |
propertyNames |
an object of pattern and maxLength only (another keyword inside it is REG-KIND-SCHEMA-KEYWORD) |
|
| Arrays | items |
a subschema (an array of subschemas is REG-KIND-SCHEMA-FORM) |
minItems, maxItems |
a count | |
uniqueItems |
a boolean | |
| Strings | minLength, maxLength |
a count, in Unicode code points |
pattern |
a string in the pattern subset (§3.4), otherwise REG-KIND-PATTERN |
|
| Numbers | minimum, maximum, exclusiveMinimum, exclusiveMaximum |
a number |
| Composition | anyOf, allOf |
a non-empty array of subschemas; more than 16 is REG-KIND-SCHEMA-LIMIT |
not |
a subschema | |
| Definitions | $defs |
at the root only, an object whose members are subschemas |
$ref |
#/$defs/<name> (§3.3) |
|
| Annotations | title, description |
a string |
default |
any value | |
deprecated |
a boolean | |
examples |
an array |
A subschema is an object or a boolean. A count is a number with a non-negative integer value
of at most 2^53 − 1 (2.0 is a count). $defs anywhere but the root is REG-KIND-SCHEMA-FORM.
Annotations do not change validation. default is applied neither by validation nor by
resolution; an emitter may read it. A value at a position whose subschema says
"deprecated": true is the warning REG-VALUE-DEPRECATED (§7.2), never an error.
3.3 Reading a schema: references, limits and order
References. A $ref is #/$defs/ followed by a name: one reference token, non-empty, with
~0 and ~1 decoded as RFC 6901 decodes them and no other ~ escape. Any other form is
REG-KIND-SCHEMA-REF at the $ref. A name that $defs does not define is REG-KIND-SCHEMA-REF at
each $ref that names it. $ref may sit beside other keywords, and applies with them.
No cycles. A definition from which a chain of $ref leads back to itself is a cycle. One
REG-KIND-SCHEMA-REF is reported for all the cycles of a schema, at the first $ref, in reading
order, that sits in a definition from which a cycle can be reached. The check covers every $ref
that names a defined name, whatever other diagnostic the schema has.
Reading order. A reader reads the definitions of $defs first, by name in code-point order, and
then the root schema. Within a schema it reads keywords in code-point order, the members of
properties in code-point order and the branches of a composition by index. The order fixes which
$ref is first and which subschemas count against the limit.
Size limit. A schema has at most 4 096 subschemas, counted in reading order: the root, every
definition, and every subschema of properties, additionalProperties, items, anyOf, allOf
and not, with propertyNames counting as one. The 4 097th is REG-KIND-SCHEMA-LIMIT at
/schema, and no later subschema is read. A composition of more than 16 branches is
REG-KIND-SCHEMA-LIMIT at the keyword, and its branches are not read.
Expanded size. A schema's expanded size is also at most 4 096. It counts the subschemas that
validation can visit at one position: the root schema and its subschemas as the size limit counts
them, but without the members of $defs. Instead, each $ref also counts the expanded size of the
definition it names, every time it is reached. A definition that no $ref reaches is not counted
here, since the size limit already holds it. So a chain of definitions that each name the next one sixteen times is refused,
even though it is small as written. A reader computes each definition's expanded size once, and
may stop counting past 4 096. A schema over the bound is REG-KIND-SCHEMA-LIMIT at /schema.
The check runs only when the schema has no other error.
3.4 The pattern subset
pattern, propertyNames.pattern and entryId.pattern use a regular-expression subset that has
one meaning in RE2, ECMAScript (with the u flag) and Python's re. A pattern outside it is
REG-KIND-PATTERN at its pointer.
A pattern is at most 256 code points. It is a sequence of these, and nothing else:
- literal code points, other than
\,.,^,$,|,?,*,+,(,),[,],{and}; - escapes:
\.\/\\\(\)\[\]\{\}\*\+\?\|\^\$, and\d; every other escape is refused, among them\w,\s,\b,\p, a back-reference such as\1, and\-outside a class; .;^only as the first character and$only as the last;- groups
( … ), balanced, whose capture is not relied on.(?begins no group: named groups, look-around, flags and every other(?form are refused; |;- quantifiers
*,+,?,{n},{n,}and{n,m}, each after an atom (a literal, an escape,., a class or a group) and never after another quantifier, so lazy and possessive forms are refused.nandmare 1 to 4 digits with no leading zero (or0), andn ≤ m ≤ 1000. A{that does not begin a quantifier, and a}or]that ends nothing, are refused. Along every chain of quantifiers nested through groups, the product of their counts is at most 1 000:{n,m}counts m,{n}and{n,}count n, and*,+,?and a count of 0 count 1. A chain may start at any quantifier.{0}and{0,0}only stop a chain that reaches them from above: the chains that start below them are still checked. So(a{32}){32}and((a{2}){501}){0}are refused, and(a{10}){100}and((a{2}){500}){0}are admitted; - bracket classes
[ … ], with an optional leading^, holding literal code points, the escapes above,\-, and rangesa-bwhose ends are a literal or an escaped code point and whose first end is not greater than its second. A class is not empty ([]and[^]are refused), holds no unescaped[, holds none of--,&&,~~or||, uses\donly alone and never as a range end, and is closed.
A pattern that ends with \ is refused.
One meaning. A reader translates the pattern for its engine so that it has these meanings:
.matches any code point except U+000A, U+000D, U+2028 and U+2029;$matches only at the end of the string (in Python,\Z; in RE2,\z);\dis[0-9];- a pattern matches when it matches anywhere in the string, so anchoring is the author's.
Linear time. A reader MUST match a pattern in time linear in the input, for example with an automaton. A backtracking engine is not conformant on adversarial input. A pattern within the subset that a reader's engine cannot compile within its own limits is not pinned by this version (§17).
Program size. A pattern's size is counted on the pattern as written, by these rules:
- each literal code point, escape,
., class,^and$counts 1; - a group counts its content, since its capture is not relied on;
*counts 2 plus its atom, and+and?count 1 plus their atom;{n}counts n times its atom;{n,}counts 1 plus n times its atom ({0,}counts as*);{n,m}counts m times its atom plus m − n;- a sequence counts the sum of its parts, and an alternation of k alternatives counts the sum of its alternatives plus k − 1;
- every construct counts at least 1, an empty alternative and
x{0}included.
Size is counted only for a pattern within the subset, and a pattern has one code: one outside
the subset is REG-KIND-PATTERN alone, whatever its size. A pattern of size over 4 096 is
REG-KIND-PATTERN-LIMIT at its pointer. A kind's patterns are
also held together to 65 536. They are counted with entryId.pattern first and then the
schema's patterns in reading order (§3.3); the default entryId pattern, when entryId is absent,
is not counted. The pattern that
would take the total past 65 536 is REG-KIND-PATTERN-LIMIT at its pointer. A refused pattern
is not counted, so each later pattern is judged against the patterns admitted before it. The
size bounds what a linear-time matcher builds: {n,m} makes m copies of its atom, so without a
bound one pattern of 256 code points could compile to a quarter of a million instructions.
3.5 Pointer patterns
A pointer pattern is an RFC 6901 pointer whose reference tokens may be *, which matches any member
name or any array index at that position. A literal member named * is written ~2, an escape this
companion adds; ~0 and ~1 keep their RFC 6901 meanings, and every other ~ escape is refused. A
pattern begins with / ("" is refused) and is at most 512 bytes of UTF-8, counted as written,
escapes included. A pattern outside these rules is
REG-KIND-POINTER-FORM.
A pattern matches a concrete pointer of the same number of tokens when each token is * or
equals the concrete token after unescaping. /grants/*/role matches /grants/0/role.
Reachability. A pattern is reachable when some position the schema allows matches it. A reader decides this from the schema, never from values, by following each token from the root:
- through
$ref, and through every branch ofallOfandanyOf(a token is reachable if any branch reaches it);notis not followed; - at an object position, a literal token is reachable through its
propertiesmember, or else throughadditionalPropertiesunless that isfalse;*is reachable when either is; - at an array position, a token that is
*or an array index is reachable throughitems; - a position whose
typeallows neither objects nor arrays has no token below it; one with notypeallows both; - a subschema that is
falsereaches nothing, and an absentadditionalPropertiesoritems, or one that istrue, reaches every token below it.
An array index token is a decimal of at most 9 digits with no leading zero (or 0).
3.6 Kind versions
A kind's version follows these rules, so that a range over kind versions (§11.1) means something:
- A patch version changes only annotations (§3.2) and
description. Every value has the same diagnostics under both versions. - A minor version only widens: every value valid under the previous version is valid under the
new one. It may add optional members, widen an
enum, relax a bound, addoverlayablepatterns, raiseboundsand setdeprecated. It MUST NOT changekind,entryId,secretsorreferences. - Anything else is a new major version.
Validation checks a registry against the exact declarations it pins, and does not compare two versions of a kind. A tool that compares them applies these rules. A consumer that reads a kind by range MUST accept members it does not know, because a minor version may add them.
4. Registry document
{
"registryFormatVersion": "1.0.0",
"id": "https://example.invalid/registries/platform",
"version": "4.0.0",
"environments": ["dev", "prod"],
"owners": ["platform-data", "team-billing"],
"kinds": [
{ "kind": "database", "id": "https://example.invalid/kinds/database", "version": "1.0.0", "digest": "sha256:…" },
{ "kind": "db-role", "id": "https://example.invalid/kinds/db-role", "version": "1.2.0", "digest": "sha256:…" }
],
"entries": [
{ "kind": "database", "id": "billing", "owner": "platform-data", "value": { "engine": "postgres" } },
{ "kind": "db-role", "id": "billing-api", "owner": "team-billing",
"value": { "database": "entry:database/billing", "privileges": ["read", "write"],
"password": "secret:gcp-sm:projects/example-dev/secrets/billing-db/versions/3" } },
{ "kind": "db-role", "id": "billing-backfill", "owner": "team-billing", "environments": ["dev"],
"value": { "database": "entry:database/billing", "privileges": ["read"] } }
],
"overlays": [
{ "environment": "prod", "patches": [
{ "kind": "db-role", "id": "billing-api",
"set": { "/password": "secret:gcp-sm:projects/example-prod/secrets/billing-db/versions/7",
"/connectionLimit": 120 } } ] }
],
"secretScopes": { "dev": { "gcp-sm": ["example-dev"] }, "prod": { "gcp-sm": ["example-prod"] } }
}
A registry has these members and no other. overlays and secretScopes are optional, and the rest
are required, besides the selector.
| Member | Form |
|---|---|
id |
an absolute URI, as a kind's id (§3.1) |
version |
SemVer 2.0.0, with no build metadata |
environments |
1 to 32 distinct names, each matching ^[a-z][a-z0-9-]{0,31}$ |
owners |
a non-empty array of distinct owners, each of a kind owner's grammar (§3.1): the closed list of parties entries may name |
kinds |
an array of pins, each an object of exactly kind (a kind name), id (an absolute URI), version (SemVer, no build metadata) and digest (§2.3): the kind declarations the registry uses |
entries |
an array of entries |
overlays |
an array of overlays (§5) |
secretScopes |
the projects each environment's secrets come from (§6.4) |
An entry is an object of exactly kind, id, owner and value, and optionally
environments:
kindis a kind name, andowneran owner;idis a string; its grammar is checked at step 5 (§7.1);environmentsis a non-empty array of distinct strings, the environments the entry applies in. Without it, the entry applies in every environment of the registry;valueis any JSON value.
A reader is given the kind declarations apart from the registry, and matches each pin to a declaration by its digest. A declaration that is missing, or that does not match, is a refusal and never a fetch.
Canonical order. kinds is sorted by kind, and entries by kind and then by id, each in
code-point order. An importer writes this order (§9), and a registry out of it is invalid, so two
registries that say the same thing have the same bytes.
Diagnostics of the shape. They are validation's step 3 (§7.1), each in document registry:
- A member of the registry that is not listed is
REG-REGISTRY-UNKNOWN-MEMBERat it, and a required one that is absent isREG-REGISTRY-MISSING-MEMBERat the pointer it would have. Either stops validation before any other member is read. id,version,entriesoroverlaysnot of its form isREG-REGISTRY-FORMat that member.environmentsorownersthat is not a non-empty array, orenvironmentsof more than 32, isREG-REGISTRY-FORMat it. An item that is not a string of its grammar isREG-REGISTRY-FORMat the item, and an item equal to an earlier one isREG-REGISTRY-DUPLICATEat the item.kindsthat is not an array isREG-REGISTRY-FORMat it. A pin that is not an object, or whose members are not of their forms, isREG-REGISTRY-FORMat the pin, and a member of a pin that is not listed isREG-REGISTRY-UNKNOWN-MEMBERat that member.- A diagnostic in this list so far stops validation after step 3.
secretScopesis read only when none was given (§6.4), and its form diagnostics stop validation too. - An entry that is not an object is
REG-REGISTRY-FORMat the entry. A member of an entry that is not listed isREG-REGISTRY-UNKNOWN-MEMBERat it, and a required one that is absentREG-REGISTRY-MISSING-MEMBERat the pointer it would have. Otherwise akindorownernot of its grammar, anidthat is not a string, or anenvironmentsthat is not a non-empty array, isREG-REGISTRY-FORMat that member, and anenvironmentsitem that is not a string, or repeats an earlier one, isREG-REGISTRY-FORMat the item. An entry with any of these is dropped: it is not an entry for any later step, and validation goes on. - Among the pins, the first whose
kindis less than thekindof the pin before it isREG-REGISTRY-ORDERat that pin. Among the entries that were not dropped, the first whosekindandidare less than those of the entry before it isREG-REGISTRY-ORDERat that entry. Each is reported at most once, and neither stops validation.
5. Overlays
An overlay is an object of exactly environment, an environment of the registry, and patches,
an array of patches. A patch is an object of exactly kind, id and set. set is an object whose
member names are pointers into the entry's value, and whose values replace the values at those
pointers. Set keys are plain RFC 6901 pointers: ~2 is not an escape in them.
Rules.
- At most one overlay per environment.
- A patch never adds an entry, and an entry has at most one patch per overlay. An entry that
exists in some environments says so with its
environmentsmember. - The entry must apply. A patch for an entry that does not apply in its overlay's environment is an error, because it can never take effect.
- The target must be overlayable and reachable. A set key matches one of the kind's
overlayablepatterns (§3.5), and addresses a member or an array element that exists in the entry's value, or a member that the schema declares in apropertieskeyword at an object position that exists in the value (through$ref,allOfandanyOf, as §3.5 follows them). - No deletions. A set value of
nullwould delete, and is refused: a member that varies by being absent is expressed in the base value and the kind's schema. - Order does not matter. Within one patch, no set key is a prefix of another (in reference tokens), so the order in which a patch's values are applied cannot change the result.
Diagnostics. They are validation's step 6 (§7.1), each in document registry. A diagnostic
that names its entry does so only when the patch's kind is a kind name and its id is of the
entry-id grammar (§6.2).
- An overlay that is not an object of exactly its two members, of their forms, is
REG-REGISTRY-FORMat the overlay. An overlay whose environment is not declared isREG-OVERLAY-ENVIRONMENT, and one whose environment an earlier overlay has isREG-OVERLAY-DUPLICATE, each at/overlays/<i>/environment. Such an overlay's patches are not read. - A patch that is not an object of exactly its three members, of their forms, is
REG-REGISTRY-FORMat the patch, with no entry named. - A patch for an entry an earlier patch of the same overlay names is
REG-OVERLAY-PATCH-DUPLICATEat the later patch, which is not read. - A patch for an entry the registry does not have (among entries step 3 did not drop) is
REG-OVERLAY-ENTRY-MISSINGat the patch. A patch for an entry that failed step 5 is not read, and has no diagnostic. A patch for an entry that does not apply in the environment isREG-OVERLAY-ENTRY-ABSENTat the patch. - Otherwise the set keys are read in code-point order. A key that is not a pointer is
REG-OVERLAY-POINTER, and a key nooverlayablepattern matchesREG-OVERLAY-NOT-OVERLAYABLE, each at.../set: a location never spells a key the kind does not declare overlayable. Otherwise a key whose target is not reachable isREG-OVERLAY-TARGET, and else a key whose value isnullisREG-OVERLAY-NULL, each at.../set/<the key, escaped as a reference token>. A key that passed these checks and is a prefix of a key read before it, or has one as its prefix, isREG-OVERLAY-PREFIXat the later key.
A patch with any diagnostic, and an entry with two patches in one overlay, fail their entry in that environment: the entry is not checked by step 7 or by the size bound of step 8 in that environment, and stays checked in every other.
6. References
6.1 Where references are read
A string is a reference only at a position its kind's references or secrets patterns match
(§3.5). Anywhere else, a string that begins with entry: or secret: is an ordinary string: no
escaping is needed, and no reader guesses. At a references position the value MUST be an entry
reference, and at a secrets position a secret reference. A kind in which one position can be
matched by both is invalid (REG-KIND-POINTER-CONFLICT, §3.1).
The positions a pattern matches in a value are the positions that exist in it. A pattern that matches nothing in an entry's value, as for an optional member that is absent, checks nothing there.
6.2 Entry references
entry-ref = "entry:" kind "/" entry-id [ "#" pointer ]
kind = <a kind name, §3.1>
entry-id = 1*128( %x21-7E except "/" and "#" )
pointer = <an RFC 6901 JSON Pointer of at most 512 code points, as written, possibly "">
In each environment in which the referring entry is checked (step 7), the first of these that
applies is reported, at the reference's position, in document value:
REF-ENTRY-FORM: the value is not a string of the grammar.REF-ENTRY-KIND:kindis not one of the kinds of the pattern that matched the position.REF-ENTRY-MISSING: the registry has no entry(kind, entry-id)among the entries step 3 did not drop.REF-ENTRY-ABSENT-IN-ENVIRONMENT: the entry does not apply in the environment.REF-ENTRY-POINTER: the reference has a#pointer, the target was checked in this environment by step 7, and the pointer addresses nothing in the target's resolved value there. A target not checked there (it failed step 5, or its patch failed) gives no diagnostic at this step.""addresses the whole value.
A reference may name its own entry, and references may form cycles, because nothing is substituted.
6.3 Secret references
secret-ref = "secret:" store ":" locator
store = "gcp-sm" ; the one store of format 1.0.0, Google Cloud Secret Manager
locator = "projects/" project "/secrets/" name "/versions/" version
project = <a project id, matching ^[a-z][a-z0-9-]{4,28}[a-z0-9]$>
name = 1*255( ALPHA / DIGIT / "_" / "-" )
version = %x31-39 *8DIGIT ; a positive integer of at most 9 digits, no leading zero
A value at a secret position that is not a secret reference is given exactly one code, by the first
of these that applies, at its position in document value:
REF-SECRET-FORM: the value is not a string, does not begin withsecret:, or has no:after the store.REF-SECRET-STORE: the store is notgcp-sm(an empty store included).REF-SECRET-FORM: the locator does not have the six/-separated segmentsprojects/<p>/secrets/<n>/versions/<v>.REF-SECRET-PIN:<n>matchesname,<v>is not empty, and either<v>holds a character other than a digit (latest, or any alias), or<p>is all digits (a project number, which is not the project id a scope compares).REF-SECRET-FORM: anything else the grammar does not match. This includes a version of0, a version with a leading zero, a version of ten or more digits, and a malformed project id.
So "not pinned" is kept for a reference that names a secret correctly but floats, or names its
project by number. A version out of range is a form error. Another store is added only by a later
minor format version, with its own locator grammar and pin rule, and a reader of 1.0.0 refuses a
store it does not know.
6.4 Secret scopes
secretScopes is an object with one member per environment of the registry, and no other. Each
member is an object whose members are stores (gcp-sm alone in 1.0.0), and each store's value is
an array of distinct project ids: the projects that environment's secrets come from.
Form. REF-SECRET-SCOPE-FORM, in document registry, is reported:
- at
/secretScopes, when it is not an object, or lacks a member for an environment; - at
/secretScopes/<environment>, for a member that names no environment of the registry, or that is not an object; - at
/secretScopes/<environment>/<store>, for a store that is notgcp-sm, or whose value is not an array; - at
/secretScopes/<environment>/<store>/<i>, for an item that is not a project id, or repeats an earlier item.
A form diagnostic stops validation after step 3, as the shape's do.
Sharing. No project is listed for two environments. Reading the environments in code-point
order, a project listed for an environment read earlier is REF-SECRET-SCOPE-SHARED at the later
listing, /secretScopes/<environment>/<store>/<i>. It does not stop validation. Production and
development therefore never share a project.
Scope. In step 7, a secret reference that passed §6.3, in an entry's resolved value for
environment e, MUST name a project listed for e and its store, or it is REF-SECRET-SCOPE at its
position. In a registry without secretScopes, every such reference is instead the warning
REF-SECRET-UNSCOPED. A registry that wants this as an error declares scopes.
A secret that must differ by environment is listed in its kind's overlayable, and each
environment's overlay sets its own reference.
6.5 What nothing does
- Validation, resolution, the facts writer and emitters never contact a secret store. They never check that a secret or a version exists, and never read a secret's value. Existence is the platform's concern at deployment, where the credentials are.
- No reference is replaced by what it refers to. A resolved registry carries every reference as written. Only the facts document (§10.1) maps them, and never to a secret's value.
- A diagnostic names the location of a bad reference, never its text. The reference is not a secret, but it names infrastructure, and a report is often posted in a CI log.
7. Validation
7.1 The steps
Validation of a registry, given the kind declarations supplied with it, runs these steps in this order. Each step runs only on the documents, declarations and entries that passed the steps before it, and reports every applicable diagnostic of its own, not only the first. A registry is valid when validation finds no error.
- Admission (§2.2), of the registry and of each kind declaration supplied. A declaration that
is refused is not a declaration for any later step. A registry that is refused ends validation
after step 2, so that the diagnostics of the declarations step 1 admitted are still reported.
Two supplied declarations whose JCS bytes are equal are one declaration: it is read once, and
its diagnostics name the copy whose
kindDocument, the digest of its bytes as supplied (§2.3), is least in code-point order. - Kind declarations (§3): each one's members, its schema (§§3.2 and 3.3), its patterns (§3.4) and its pointer patterns (§3.5).
- Registry shape (§4), and the form and sharing of
secretScopes(§6.4). A diagnostic §4 or §6.4 says stops validation ends it here. Entries that §4 drops are not entries for any later step. - Kind pins, in pin order, each at the pin (
/kinds/<i>, withkindnamed): - a pin whosekindan earlier pin has isREG-REGISTRY-DUPLICATE, and is not otherwise read; - a pin whose digest no supplied declaration has (among those step 1 admitted) isREG-PIN-MISSING; - a pin whose declaration is unusable (§3.1) has no diagnostic of its own: the declaration's say why; - a pin whose declaration has anotherkind,idorversionthan the pin isREG-PIN-MISMATCH; - a pin whose declaration is deprecated is the warningREG-KIND-DEPRECATED.
A pin that has none of the errors pins its declaration, and its kind is usable. Each
supplied declaration that is usable and whose digest no pin has is the warning REG-PIN-UNPINNED, at
{"document": "kind", "kindDocument": …, "kind": …, "pointer": ""}.
5. Entries, each at its own member under /entries/<i>:
- an entry whose kind no pin names is REG-ENTRY-KIND at .../kind; an entry whose kind's pin
is not usable is not checked, and has no diagnostic;
- otherwise, every one of these that applies: an id that fails the kind's entryId pattern or
the entry-id grammar (§6.2) is REG-ENTRY-ID at .../id, with no entry named; an entry whose
kind and id an earlier entry has is REG-ENTRY-DUPLICATE at .../id; an owner not in
owners is REG-ENTRY-OWNER at .../owner; and an environments item the registry does
not declare is REG-ENTRY-ENVIRONMENT at .../environments/<j>.
An entry with none of these passes.
6. Overlays (§5).
7. Per environment, in the order of environments. In environment e, the entries checked
are those that passed step 5, apply in e, and whose patch for e did not fail. Each one's
resolved value (§8) is checked, in entry order, against:
- its kind's schema (§7.2);
- its kind's secrets (§§6.3 and 6.4);
- its kind's references (§6.2).
8. Bounds.
- A usable kind with more entries than its maxEntries (counting every entry of that kind
step 3 did not drop) is REG-BOUND-ENTRIES at its pin.
- An entry checked in step 7 whose resolved value's JCS bytes are longer than its kind's
maxEntryBytes is REG-BOUND-ENTRY-BYTES at
{"document": "value", "entry": …, "environment": e, "pointer": ""}.
- An environment whose resolved registry (§8) would be longer than 8 MiB is REG-DOC-SIZE, and
one that would nest deeper than 32 is REG-DOC-DEPTH, each at
{"document": "registry", "environment": e, "pointer": ""}: an overlay can set a value at a
depth the registry itself does not reach.
7.2 Value validation
A resolved value is checked against its kind's schema by JSON Schema 2020-12's meaning of each
keyword of the subset, with numbers compared by their exact value. Every keyword of a schema is
checked independently, and each failure is reported at the pointer of the value it is about, in
document value:
| Keyword | Diagnostic, when the value fails it |
|---|---|
a false schema |
REG-VALUE-TYPE |
type |
REG-VALUE-TYPE; integer is a number with an integer value, so 2.0 is an integer |
enum, const |
REG-VALUE-ENUM, REG-VALUE-CONST, by JSON equality (numbers by value, objects regardless of member order) |
required |
REG-VALUE-REQUIRED, once per absent member, at the pointer the member would have |
minProperties, maxProperties |
REG-VALUE-PROPERTY-COUNT, at the object |
propertyNames |
REG-VALUE-PROPERTY-NAME, at the member whose name fails; maxLength counts code points |
additionalProperties |
for a member that properties does not name: REG-VALUE-ADDITIONAL at the member when it is false, and otherwise the member is checked against it |
properties, items |
each member it names that is present, and each item, is checked against its subschema |
minItems, maxItems |
REG-VALUE-ITEM-COUNT, at the array |
uniqueItems |
REG-VALUE-UNIQUE, once, at the array |
minLength, maxLength |
REG-VALUE-LENGTH, counting code points |
pattern |
REG-VALUE-PATTERN (§3.4) |
minimum, maximum, exclusiveMinimum, exclusiveMaximum |
REG-VALUE-RANGE |
allOf |
every branch is checked, and each branch's diagnostics are reported |
anyOf |
when some branch holds (has no error), the diagnostics of the first that holds, which are warnings only, are reported; when none holds, one REG-VALUE-ANY-OF at the value, and none of the branches' own |
not |
REG-VALUE-NOT when the inner schema holds |
$ref |
the definition is checked, beside the schema's other keywords |
deprecated: true |
the warning REG-VALUE-DEPRECATED, at a value that is present |
A keyword that does not apply to the value's type (maxLength on a number, say) holds.
Work bound. The bounds of §3.3, §3.4 and §7.1 keep each check finite, but a registry of many
large values can still make value validation costly. A reader MAY stop value validation once its
work over the registry passes a bound of its own. It then reports REG-BOUND-VALIDATION-WORK, an
error, at the value it stopped at (pointer "" in document value), and checks neither that value nor any it reaches later against
its schema. The reference
runtime counts in units of about one schema node visited, and stops past 67 108 864 (2^26). Every
value costs one unit per 16 bytes of its canonical form. A value equal to one already checked
against the same kind declaration (by digest) costs nothing more. Every other step still
runs. A registry that passes one reader's bound and not another's is not pinned by this version
(§17). A conformance row stays well within the reference runtime's bound.
7.3 Locations
A diagnostic's location is an object of these members, in this order of comparison:
| Member | Form | Present |
|---|---|---|
document |
registry, kind, value, yaml, facts, contract or pack; for the emitter host's own diagnostics (§11), also manifest, options, request, response or repository; and for the conformance harness's (§11.5), these and vector |
always |
manifest |
an integer from 1: the position of another manifest among those the host is given beside the one it runs | in document manifest only, when the pointer is into that other manifest (on EMIT-OWNS-OVERLAP's diagnostic at the other manifest's glob); absent for the manifest being run |
kindDocument |
the digest of a kind declaration's bytes as supplied (§2.3) | on every diagnostic about a supplied kind declaration, except REG-DOC-SIZE for one that was not read whole |
kind |
a kind name | on a pin's diagnostic of step 4 or 8, on REG-PIN-UNPINNED, on a facts contract's (§10), and on every diagnostic of step 2 for a declaration whose kind member is a kind name |
entry |
{"kind", "id"} |
on a diagnostic about one entry, when the entry's kind is a kind name and its id is of the entry-id grammar (§6.2) |
environment |
an environment | on a diagnostic of one environment: of step 7, of step 8's sizes, of the facts writer, and of the emitter host or harness (§11) where it resolves the registry for one environment, forms the request of one environment (with "each"), or runs that request and reads its response |
pointer |
a pointer into document |
always; "" for the whole document |
line, column |
integers from 1, counting code points | in document yaml only, where pointer is always "" |
path |
a slash-separated relative path: in document vector, below the vectors directory; in document repository, below the repository root |
in documents vector and repository only, naming the file or directory the host or harness read or would write; absent when the diagnostic is about the vectors directory or the repository as a whole |
variable |
the name of an environment variable, never its value | on EMIT-ENV-UNSET, naming the variable the manifest's env lists that the host's environment does not set |
In document value, the pointer is into the entry's resolved value in environment. In document
kind, it is into the declaration named by kindDocument. A path is never absolute, never a
path on the host outside the vectors directory or the repository, and never carries a value; its
pointer is into the file it names when that file is a JSON document, and "" otherwise.
A location never holds a value from a document beyond these identifiers: a pointer is built from member names and indices of the document, and the identifiers are the document's own names for its kinds, entries and environments.
7.4 The report
{
"reportFormatVersion": "1.0.0",
"valid": false,
"registry": { "digest": "sha256:…" },
"diagnostics": [
{ "code": "REG-ENTRY-OWNER", "severity": "error", "message": "…",
"location": { "document": "registry", "entry": { "kind": "db-role", "id": "billing-api" }, "pointer": "/entries/1/owner" } }
]
}
The validation report holds:
valid:trueexactly when validation found no error;registry: the registry's digest (§2.3), present once step 3 passed and absent otherwise;diagnostics: each withcode, from §12's closed list;severity,errororwarning, the code's;location(§7.3); andmessage, a fixed text per code that carries no value from any document.
Order. The diagnostics are sorted by location.document, location.kindDocument,
location.kind, location.entry.kind, location.entry.id, location.environment,
location.pointer, location.line, location.column and then code, each string compared in
code-point order and each integer by value, with an absent member sorting as "" or 0.
Diagnostics equal in all of these are one diagnostic, reported once.
Bound. A report lists at most the first 1 000 distinct diagnostics in this order. When
validation found more, the report lists those 1 000 and then one more, the warning
REG-REPORT-TRUNCATED, at {"document": "registry", "pointer": ""}, which is the one diagnostic
out of order. valid is decided on every diagnostic found, whether listed or not, so a truncated
report may list no error and still say false.
The same bound holds wherever a facts contract is read (§10). Its diagnostics are capped at
1 000 in this order, and the REG-REPORT-TRUNCATED that follows them is at
{"document": "contract", "pointer": ""}.
No values. A diagnostic carries no value from any document: no member value, no reference, and no pattern text. A reader MUST NOT add one in any member of a diagnostic, and the message is never compared.
Agreement. Two readers agree on a registry and its declarations when their reports are equal
with every message removed. Messages are informative.
8. Resolution
Resolution of a valid registry for one of its environments e gives a resolved registry:
{
"resolvedFormatVersion": "1.0.0",
"registry": { "id": "https://example.invalid/registries/platform", "version": "4.0.0", "digest": "sha256:…" },
"environment": "prod",
"kinds": [ { "kind": "database", "id": "…", "version": "1.0.0", "digest": "sha256:…" },
{ "kind": "db-role", "id": "…", "version": "1.2.0", "digest": "sha256:…" } ],
"entries": [
{ "kind": "database", "id": "billing", "owner": "platform-data", "value": { "engine": "postgres" } },
{ "kind": "db-role", "id": "billing-api", "owner": "team-billing",
"value": { "database": "entry:database/billing", "privileges": ["read", "write"],
"password": "secret:gcp-sm:projects/example-prod/secrets/billing-db/versions/7",
"connectionLimit": 120 } }
]
}
Procedure.
registryis the registry'sid,versionand digest (§2.3), andenvironmentise.kindsis every pin of the registry, as written, in its order.entrieshas one item per entry that applies ine, in the registry's order, of exactlykind,id,ownerandvalue. Itsvalueis the entry's value with, for each set key ofe's patch for the entry, the value at that pointer replaced, or the member added, by the set value. An entry that does not apply ineis omitted, and so is itsenvironmentsmember from every entry.- The document is written as its JCS bytes.
A registry that is not valid is not resolved. A reader MUST NOT write a resolved registry for one.
What resolution does not do. It applies no default. It replaces no reference with what it refers to, and fetches no secret.
The resolved registries and their kinds' declarations (§11.2) are the only input an emitter reads
from a registry. A resolved registry's registry.digest binds it to the exact registry it came
from.
9. YAML import
Authors may write YAML, but no reader interprets it. An importer converts one YAML file in the
subset below to the JCS bytes of the registry or kind declaration it holds, and every other step
reads only JSON. The document is a registry when its root mapping has registryFormatVersion, and
a kind declaration when it has kindFormatVersion; one with neither or both is REG-DOC-SELECTOR.
A registry's kinds and entries are written in canonical order (§4), by a stable sort, when each
item has those members as strings. The same file always gives the same bytes. A file outside the
subset is refused with a report, and nothing is written.
The subset is YAML 1.2, restricted to:
- one document, with no directive (
REG-YAML-DIRECTIVE); no file, or more than one document, isREG-YAML-DOCUMENTS; - UTF-8 with no byte-order mark, holding only characters YAML allows, and none of U+0085,
U+2028 and U+2029 as characters (
REG-YAML-ENCODING). YAML 1.1 reads those three as line breaks and YAML 1.2 does not, so a file that holds one would be read two ways. Written as an escape in a double-quoted scalar (\N,\L,\P, or a\x,\uor\Uescape of the code point), they have one reading and are admitted; - no tags (
REG-YAML-TAG), no anchors or aliases (REG-YAML-ANCHOR), no merge key<<(REG-YAML-MERGE); - no empty node (
REG-YAML-EMPTY): writenullor""; - keys that are strings on one line, of at most 1 024 characters, neither explicit (
?) nor in flow form, and whose plain text reads as a string (REG-YAML-KEY); a duplicate key isREG-DOC-DUPLICATE; - plain scalars read as:
true,falseandnull; an integer matching^-?(0|[1-9][0-9]*)$and a decimal matching^-?(0|[1-9][0-9]*)\.[0-9]+$, each held to the number rule (§2.2,REG-DOC-NUMBER); and otherwise a string, unless another reader would read it as another value, which isREG-YAML-SCALAR. A scalar has another reading when it matches one of these whole: y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF,~|null|Null|NULL;[-+]?0b[01_]+,[-+]?0[0-7_]+,[-+]?(?:0|[1-9][0-9_]*),[-+]?0x[0-9a-fA-F_]+,[-+]?[1-9][0-9_]*(?::[0-5]?[0-9])+,[-+]?[0-9]+,0o[0-7]+,0x[0-9a-fA-F]+;[-+]?(?:[0-9][0-9_]*)?\.[0-9_]*(?:[eE][-+][0-9]+)?,[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+\.[0-9_]*,[-+]?(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)(?:[eE][-+]?[0-9]+)?,[-+]?\.(?:inf|Inf|INF),\.(?:nan|NaN|NAN);[0-9]{4}-[0-9]{1,2}-[0-9]{1,2}, the same followed by a time ((?:[Tt]|[ \t]+)[0-9]{1,2}:[0-9]{1,2}:[0-9]{1,2}(?:\.[0-9]*)?(?:[ \t]*(?:Z|[-+][0-9]{1,2}(?::[0-9]{2})?))?),<<and=;- or it begins with a digit or a sign and, with every
_removed, matches^[-+]?(?:0[bB][01]+|0[oO][0-7]+|0[xX][0-9a-fA-F]+|[0-9]+|(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)(?:[eE][-+]?[0-9]+)?)$.
These are the readings of YAML 1.1, of the YAML 1.2 core schema and of a widely used Go YAML
library. A plain key with another reading is REG-YAML-SCALAR, and one that reads as a number, a
boolean or null is REG-YAML-KEY.
Reading. Every refusal is located at {"document": "yaml", "pointer": "", "line": …, "column":
…}, never by a pointer, which could spell a name the file holds. A refusal that leaves the structure
readable (a tag, an anchor or alias on a value, a merge key, a refused scalar or key text, an empty
node, a duplicate key, a lone surrogate, a number outside the rule) is reported and reading goes on;
every other refusal stops reading. After 1 000 refusals, the next is REG-YAML-TRUNCATED at its
place, and reading stops. This bound is the importer's alone: a validation report is bounded by
§7.4. The bytes written are then admitted as §2.2 admits their document, and a refusal there is
located at the line and column of the node its pointer reaches. A file over 8 MiB is REG-DOC-SIZE
at {"document": "yaml", "pointer": ""}. The report is a validation report with no registry
member, sorted as §7.4 says.
10. Facts
10.1 The facts document
For one entry of a valid registry's resolved registry for environment e (§8), the facts document
is an object of exactly:
registry: the registry'sid,versionand digest;environment:e;entry: the entry'skind,idandowner;value: the entry's resolved value, mapped by the rules below;references: an object, always present, with one member per entry reference in the value. Its name is the pointer of the reference's position in the value, and its value is the target'skind,idandvalue: the target's resolved value inemapped by the rules below as its own kind's, or, for a reference with#pointer, the value it addresses. One level only: the target's own references stay strings.
Mapping rules. Strings, booleans, null, arrays and objects are copied, with member names and
order kept. Every number becomes a string in one normal form: a number with an integer value in base
10, with - for a negative and no leading zero (1.0 and 1e2 become "1" and "100"), and any
other with no exponent, no trailing zero after the point and a digit on each side of it (1.50
becomes "1.5", 1e-7 becomes "0.0000001"). Every value at a secret position becomes
{"store": <store>, "scope": <project>}, so no facts document holds a secret reference.
The document is written as its JCS bytes. One whose JCS bytes are over 10 MiB, that nests deeper
than 128 (the root at depth 1), that holds more than 250 000 values, or that holds a string over
1 MiB in UTF-8, is FACTS-DOCUMENT-LIMIT at {"document": "facts", "entry": …, "environment": e,
"pointer": ""}, and nothing is written. It is never truncated.
10.2 Batches
A batch for one kind and environment has one line per entry of the kind that applies there, in
entry order: the JCS bytes of {"facts": <facts document>, "id": "<kind>/<entry-id>"} and a line
feed. Over every environment, the lines of each environment follow in the registry's order, with ids
<environment>:<kind>/<entry-id>. An invalid registry writes no line.
A line's id is 1 to 256 bytes of UTF-8, the bound the reference runtime's batch evaluation holds an
item's id to. Every id of this section is within it: <environment>:<kind>/<entry-id> is at most
225 bytes, its names being bounded at 32, 63 and 128 (§4, §3.1, §6.2). A tool that writes lines of
this shape from another source, such as the reference runtime's batch of the dialect's
terraform-file source (dialect.md §4.5), checks every selected item's id before it
writes any line, and one outside the bound refuses the whole run with FACTS-ID-LIMIT, which never
carries the id. No line is written: a batch that left the item out would let a gate pass without
judging it.
10.3 The facts contract
{
"factsContractVersion": "1.0.0",
"id": "https://example.invalid/kinds/db-role",
"version": "1.2.0",
"source": { "kind": { "id": "https://example.invalid/kinds/db-role", "version": "1.2.0", "digest": "sha256:…" } },
"facts": [ { "pointer": "/value/connectionLimit", "type": "decimal", "present": "optional" } ]
}
A contract has exactly these members. id is an absolute URI and version is SemVer with no
build metadata, as a kind's are (§3.1). source is {"authored": true} for a contract written by
hand, or {"kind": {"id", "version", "digest"}} for one generated from a kind. facts lists every
position a facts document under the contract may hold a value at, each an object of:
pointer: a pointer that begins with/, of at most 35 tokens, in which*is any member name or index and~0,~1and~2are escapes (§3.5);type:string,decimal(a string of Core §2.2's decimal grammar),boolean,null,arrayorobject;present:always(whenever the parent is present) oroptional;items(on anarrayonly): the element type;values(optional): a non-empty list of distinct values of the type, only on astring,decimalorboolean, or on anarraywhoseitemsis one of them, the values then ofitems;secretReference(optional):true, on theobjectthat stands for a secret reference.
facts is sorted strictly by pointer and then type, each in code-point order. A contract is
read as a registry is admitted (§2.2, document contract, bound 8 MiB); then a member not listed is
FACTS-CONTRACT-FORM at "", a member of the wrong form FACTS-CONTRACT-FORM at it (an item's,
at the item or its member), more than 65 536 facts or a pointer of more than 35 tokens
FACTS-CONTRACT-LIMIT, and an item out of order FACTS-CONTRACT-ORDER at it. A contract's digest
is that of its JCS bytes.
10.4 Generating a contract
A writer generates a kind's contract from the kind and the registry, and writes its JCS bytes, with
id and version the kind's and source.kind its id, version and pin digest:
- Fixed rows:
/entry(object),/entry/id,/entry/kind(values: the kind),/entry/owner,/environment(values: the registry's environments, in order),/registry(object),/registry/digest,/registry/id,/registry/version,/references(object) and/value, allalways, and strings unless marked. No row has the pointer"". - Value rows: every position the schema allows, objects included, with its type from
type(integerandnumberbecomedecimal; notypeallows every type). A member isalwayswhen its parent's schema requires it, and an array element isoptional, at<p>/*.valuesis the intersection of theenumandconstliterals of the position's schemas, kept only when it is closed.allOfand$refnarrow,anyOfis a union,notis ignored, and afalseschema allows nothing. An array row hasitemswhen its element has one type and is not open. An object whoseadditionalPropertiesis absent has an open position<p>/*. - Open positions: a position with no constraint (
{}, notypewith nothing else, or every type with no members, no other members' schema and no element schema) is listed once per type atpand once per type atp/*, and nothing deeper. A pack check treats every pointer below such ap/*as listed (§10.5). - Secret positions become an
objectrow withsecretReference, andscope(always) andstore(always, values["gcp-sm"]) below it. - References: a literal reference pattern gives
/references/<the pattern's pointer, escaped as one token>,alwayswhen every step of it is a required member of an object position, and otherwiseoptional; a pattern with*gives/references/*,optional. Below each:id(always),kind(always, values the pinned kinds the pattern allows), andvalue, the union of the mapped shapes of every target kind and of everything they may hold. The union is wider than any one target; whether it should be narrowed is open (§17). - Bounds: a contract over 8 MiB or 65 536 facts, or a generation over its work bound, is
FACTS-CONTRACT-LIMITat{"document": "contract", "kind": …, "pointer": ""}.
10.5 Checking a pack against a contract
This check is defined, and is outside every conformance class of this version (§15). Its rows bind no claim. Core is unchanged: its advisories never change an evaluation.
A checker admits the pack as Core does and reads its evaluation form, then visits each fact
condition in applicability, each exceptions[i].when and each rules[i].when, through not
(/condition) and all and any (/conditions/<i>), in that order. For each it reports at most
one advisory, a warning at {"document": "pack", "pointer": <the condition's pointer>}:
FACTS-POINTER-UNKNOWN: the contract lists no fact at the condition's path, or the path is not a pointer. A token matches a literal row and*; below an openp/*, every pointer is listed;FACTS-TYPE-ORDERED: an ordered operator, and no row at the path isdecimal;FACTS-VALUE-UNREACHABLE: anequalsornot-equalsoperand, or any item of anin, that no row at the path admits. A JSON number is never admitted (facts hold decimals as strings); an object is admitted only when its members are listed and admitted and thealwaysmembers are present.
The report is {"factsCheckFormatVersion": "1.0.0", "contract": {"digest"}, "pack": {"digest"},
"diagnostics": […]}, with the pack's digest that of its bytes as supplied, and the advisories in
visit order. A contract that is refused is not checked against: its report is
factsCheckFormatVersion and the contract's diagnostics alone, with neither contract nor
pack. A check over its work bound (4 194 304) or a path deeper than 128 is FACTS-CHECK-LIMIT,
an error, at the condition it stopped at, and no later condition is checked. The report needs no
cap of its own: it has at most one advisory per fact condition, and the pack's own bounds and the
work bound limit the conditions. The contract's diagnostics, when it is refused, are capped as
§7.4 caps them.
10.6 Typed facts builders
A contract, generated or authored, is the input of a reference emitter with "input":
"factsContracts" (§11.1). For Go it generates a struct per object position and a Build function
that returns the canonical facts JSON: decimal fields are a decimal type that renders §10.1's
normal form, always fields are constructor arguments, and values become typed constants with a
build-time check. For TypeScript it generates interfaces, string-literal unions and a buildFacts
function; decimal accepts a decimal string or a bigint, never a number. Its goldens are checked
by the harness (§11.5), not by a reader.
11. Emitters
This section is the normative text of the emitter contract of RFC 0036 §§1–7, and settles what the RFC left open (§17).
11.1 The manifest
An emitter manifest has exactly: emitterManifestVersion; id (absolute URI); version (SemVer, no
build metadata); owner (§3.1); description (optional, a string); reads, each {"kind", "id",
"versions"}, no two of one kind, with versions one of ^x.y.z, ~x.y.z, =x.y.z or
>=x.y.z <x.y.z; input (optional, "resolved", the default, or "factsContracts");
requestVersions, a non-empty array of distinct request selectors, each SemVer with no build
metadata; environments, "each" or "all", required with "resolved" and absent with
"factsContracts"; options (optional), a schema in §3.2's subset, default
{"type": "object", "additionalProperties": false}; command, an argv whose first item, the
program, follows §11.3's path rules after an optional leading ./, so that it is a program name
with no / or a relative path in the repository, and none of whose items begins with /, has a
.. segment or holds NUL; owns, a non-empty array of distinct globs of *, ** and literal
characters naming every path the emitter writes; env (optional), distinct variable names
matching ^[A-Z_][A-Z0-9_]{0,63}$ other than PATH, HOME, LANG, TZ and
SOURCE_DATE_EPOCH; and deprecated (optional, a boolean), under which, when true, the host
and harness run it with the warning EMIT-DEPRECATED. The owns of two manifests in one
repository MUST NOT overlap, and neither command nor owns names a path outside the repository
root. A host given the repository's other manifests beside the one it runs refuses an overlap, a
glob of each that one path can match, with EMIT-OWNS-OVERLAP at both globs, the other manifest's
named by §7.3's manifest.
An owns glob follows the path rules of §11.3, with * allowed in a segment and ** only as a
whole segment, and its first segment holds no *: **, **/*, */** and * are refused, since
a glob that owns the whole tree would let a response of one file delete every other file of the
repository. In a glob, * matches any run of characters within one segment, a leading .
included; ** between two segments matches zero or more segments, so a/**/b matches a/b; and a
trailing ** matches one or more, so gen/** never matches a file named gen. A manifest that is
not of this section's form is EMIT-MANIFEST, in document manifest. Bytes that are not
admissible JSON (§2.2's steps 1 to 3, under the host's size bound) are one EMIT-MANIFEST, at the
pointer of the first refusal those steps give in §7.4's order, and nothing more is read. A root
that is not an object is one at "", and a root whose emitterManifestVersion is missing or not
one the host supports is one at /emitterManifestVersion, with no other, as with
REG-DOC-SELECTOR. Otherwise there is one at the pointer of each member that is missing, not
defined or not of its form.
11.2 The request
The host resolves the registry per environment, removes every entry and pin of a kind the manifest
does not read, refuses a pin of a kind it reads whose kind id is not the one the manifest reads
under that name (EMIT-KIND-ID) or whose version is outside its range (EMIT-KIND-RANGE), each at
the pin, validates options against the manifest's options schema, refusing options that are not
admissible JSON or fail it (EMIT-OPTIONS, in document options), and writes
{"emitRequestVersion", "emitter": {"id", "version"}, "options", "declarations": […],
"resolved": […]} as JCS, with one resolved registry for "each" and every environment in order
for "all". declarations holds the declaration of each kind whose pins remain, exactly as
admitted, in its JCS form, sorted by kind. A declaration's SHA-256 is its pin's digest (§2.3,
§4): an emitter checks each pin against its declaration and MUST refuse the run, by exiting
non-zero or with an error diagnostic, when a declaration is missing or does not match, or when a
declaration has no pin. The resolved documents are unchanged, §8's format as registry
resolve writes it. With "factsContracts" the request holds factsContracts (generated contracts
of the kinds read, and the authored ones named, sorted by id then version) in place of
declarations and resolved. The host writes the highest request version it supports that the
manifest lists, or refuses the run (EMIT-REQUEST-VERSION), as it does when the registry needs a
later resolved format than a listed request version carries. A request is at most 64 MiB of
canonical bytes; the host refuses a larger one (EMIT-REQUEST) before any emitter runs. Request
1.0.0 carries resolvedFormatVersion and factsContractVersion 1.0.0.
11.3 The response
The emitter writes one {"emitResponseVersion", "files", "diagnostics"} on standard output and
exits 0, with a response version whose major and minor do not exceed the request's. The three
members are required, and files and diagnostics may be empty arrays. A non-zero exit or a
time-out is EMIT-PROCESS, and output that is not one valid response EMIT-RESPONSE, located in
document response at the pointer of each member that fails. Each file has a path and exactly
one of text (UTF-8, ending in a line feed, with no carriage return) or base64 (RFC 4648 §4: the
standard alphabet, padded, with no line break or other character, and no bit set past the data),
and an optional mode, "0644" (default) or "0755". A path uses /, is relative, has no .,
.. or empty segment and no segment beginning with ~, does not end with /, holds no NUL,
backslash, : or control character, matches an owns glob, and is unique once case is folded;
files is sorted by path. So that a path means one file on every system, no segment ends in .
or a space, which Windows drops; none is a Windows device name, which is CON, PRN, AUX,
NUL, CONIN$, CONOUT$, or COM or LPT followed by a digit 1 to 9 or by ¹, ² or ³,
compared in any case with the segment's part before its first ., trailing spaces removed
(nul.txt is one, COM0 is not); and none is a name git reads as .git, as git's own
is_ntfs_dotgit and is_hfs_dotgit checks read it: .git or git~1 in any ASCII case, followed
only by dots and spaces, or .git once the code points HFS+ ignores (U+200C to U+200F, U+202A to
U+202E, U+206A to U+206F and U+FEFF) are skipped. An emitter diagnostic has exactly code,
severity (error or warning) and location. Its code is x- and lower-case words of a to
z and 0 to 9 joined by - (^x-[a-z0-9]+(-[a-z0-9]+)*$), at most 64 bytes; its location is
of §7.3's form; and it carries no value. That location uses only §7.3's registry documents
(registry, kind, value, yaml, facts, contract and pack, never the host's or the
harness's) and members other than path; any other is EMIT-RESPONSE at
/diagnostics/<i>/location. An emitter diagnostic of severity error fails the run: it is
reported, and is also EMIT-RESPONSE at /diagnostics/<i>, its own index, in document response.
The grammar keeps a code short and plain, but cannot keep an emitter from spelling a value in one,
and no host can tell that it has (§16).
Bounds: a response of 64 MiB, 10 000 files, 16 MiB per file and 512 bytes per path.
11.4 The host
The host runs command from the repository root with the request on standard input and an
environment of only PATH, HOME (a fresh empty directory), LANG=C.UTF-8 and the manifest's
env names, never printing an env value; a name the host's own environment does not set is not
passed, with the warning EMIT-ENV-UNSET (§7.3's variable). It reads at most 64 KiB of standard
error, reports only its size unless asked to pass it through, and imposes a wall-clock limit (120 s
by default). In write mode it validates the whole response first, writes each file through a
temporary file and a rename, deletes owned files the response does not hold, never entering a
directory git reads as .git (§11.3), refuses a symbolic link, or another reparse point such as a
junction, at or above an owned path or a response path (EMIT-LINK),
and reports what it wrote and deleted: exit 0 written, 2 not written. In check mode it writes
nothing and compares byte for byte and mode for mode: exit 0 identical, 1 different (listing paths,
never contents), 2 could not check. A command line that cannot be parsed exits 3. An emitter MUST
give the same response bytes for the same request bytes: no clock, host name, absolute path,
locale, time zone, map order or network.
The host's other refusals and warnings are in document repository at the path, unless named
otherwise:
EMIT-PATH-UNREADABLE: an input it cannot read, in that input's document; or an owned path that is not a regular file or a directory, or that it cannot list or read;EMIT-WRITE: a file it cannot write or delete; or a response path that a directory holds, or whose directory is a file noownsglob matches, which it refuses before anything is staged or deleted;EMIT-INTERRUPTED: an interrupt or a termination signal stopped the run, in documentmanifestat/command, and notEMIT-PROCESSfor an emitter it ended; a write already begun is finished, and none starts after the signal;EMIT-STAGING-LEFTOVER, a warning: a temporary file of the host's that an earlier run left in a directory it writes to, which noownsglob matches, and which it therefore does not delete;EMIT-REPORT-TRUNCATED, a warning in documentresponse: its report lists the first 1 000 diagnostics of a list, the emitter's or its own, and more were found.
11.5 The harness
The harness runs an author's vectors at the level named by vectors/harness.json
({"harnessLevel": "1.0"}, the default). A vector is a directory holding exactly one of
request.json and registry.json, with kinds/ and an optional options.json beside
registry.json and neither beside request.json, from which the harness forms the request as the
host does; and exactly one of expected/, holding the files the response must contain by their
paths below it, and expected-failure.json; and nothing else. Any other entry, a directory where
a file belongs or a file where a directory belongs, and a symbolic link in place of any of them is
not of this layout, nor is a symbolic link beside the vectors in the vectors directory. Since git
keeps no empty directory, a run that writes no files is recorded by the marker expected/~empty:
a zero-byte regular file alone at the root of expected/, read as no files, which no response path can name (§11.3). The marker anywhere else,
of another size or kind, or beside any other entry is not of this layout, nor is an expected/ that
holds no regular file and no marker; a missing expected/ is never read as empty. --update writes
expected/ from a run, or the marker alone for a run that wrote no files. A vector not of this
layout refuses the whole run, as do a harness.json not of its form or of a level the harness does
not apply, a vectors directory that holds no vector, and vectors past a bound on the vectors:
EMIT-VECTOR, in document vector.
Level 1.0 applies six checks to every vector:
- golden equality;
- determinism over three runs with a different
HOME,TZ,LANGandSOURCE_DATE_EPOCH; - every path rule and bound of §11.3, with crafted responses substituted for the emitter's;
- kind filtering: the harness forms the request again from the registry with an entry of a
synthetic kind the manifest does not read, and that kind's declaration and pin, added; sets
every registry digest in it to the original request's at the same place (each resolved
document's
registry.digest), since the entry changes the registry's digest and an emitter may write that digest into a file it generates; requires the result to be the original request's bytes; and only then runs the emitter on it and requires the response unchanged; - references: for each string R at a secret position of the request (in every environment it
holds) and each file, as text or its bytes read as Latin-1, the file fails when it holds a run of
at least 32 consecutive characters of R (all of R, if R is shorter) that lies inside no complete
occurrence of any string at a secret position of the request. Two whole references that share a
prefix pass; a reference cut short, or rewritten around its name and version, fails. A failure
names the file, the entry and the pointer of R's first position and, for
"each", the environment, never R; - no stray writes (
EMIT-STRAY-WRITE).
A vector that gives its request whole skips checks 4 and 5, having no registry to add a kind to or
to find secret positions by; a facts-form request skips check 5, since it holds no secret position;
a request refused before the emitter runs skips both, and a run that fails skips check 5. A check
that can fail a vector is added only at a new level. The report (harnessReportVersion "1.0.0")
names the level and has one row per vector and check: pass, fail, skip with its reason, or info. The
harness exits 0 when nothing fails, 1 when a check fails, and 2 when it could not run.
A harness that runs the emitter in a copy of the repository, to find stray writes, refuses a link
that leads out of the repository (EMIT-HARNESS-BOUND), except one that git does not track and that
no owned path and no path to the vectors could name: it leaves that one out of the copy, with the
warning EMIT-LINK-OMITTED at the link's path.
Besides EMIT-VECTOR, the harness could not run on EMIT-HARNESS-BOUND, a check it could not
complete: past a bound of its own, such as on the repository copy, the registry with the synthetic
kind or the references scan, or for want of a fresh HOME for a determinism run; on EMIT-PATH-UNREADABLE, a file it could not read; and on
EMIT-INTERRUPTED, as the host's (§11.4), at the vector. EMIT-HARNESS-BOUND and
EMIT-PATH-UNREADABLE are located by §7.3's path, in document vector for a vector's own files
and in document repository for the repository copy. An --update that cannot write expected/
is EMIT-WRITE at the vector.
11.6 Reference emitters
The specification's reference emitters (a Go typed loader and TypeScript constants, and the builders of §10.6) each promise their manifest, the kinds they read and their options, not the bytes they write.
12. Diagnostic codes
The list is closed: a reader reports only these codes, each with its severity. The machine-readable
list is
codes.json,
and every code's status in 1.0.0 is active. The TF- codes of the dialect's terraform-file
source are the dialect's (dialect.md §4.5); FACTS-ID-LIMIT, which that source's
batch reports, is this list's (§10.2).
| Code | Severity | § | Raised when |
|---|---|---|---|
REG-DOC-SIZE |
error | §2.2 | a document is over its size bound, or a resolved document is (step 8) |
REG-DOC-JSON |
error | §2.2 | the bytes are not one JSON value in UTF-8 |
REG-DOC-DEPTH |
error | §2.2 | a value nests deeper than 32, or a resolved document does (step 8) |
REG-DOC-DUPLICATE |
error | §2.2 | an object has two members of one name |
REG-DOC-STRING |
error | §2.2 | a string escapes a lone surrogate |
REG-DOC-NUMBER |
error | §2.2 | a number is outside the number rule |
REG-DOC-SELECTOR |
error | §2.2 | the root is not an object, or its selector is missing or not supported |
REG-KIND-UNKNOWN-MEMBER |
error | §3.1 | a kind declaration, its bounds or a reference pattern has a member not defined |
REG-KIND-MISSING-MEMBER |
error | §3.1 | a required member of a kind declaration is absent |
REG-KIND-FORM |
error | §3.1 | a member of a kind declaration is not of its form |
REG-KIND-DEPRECATED |
warning | §3.1 | a pinned kind is deprecated |
REG-KIND-SCHEMA-KEYWORD |
error | §3.2 | a schema uses a keyword outside the subset |
REG-KIND-SCHEMA-FORM |
error | §3.2 | a keyword's value is not of its form |
REG-KIND-SCHEMA-REF |
error | §3.3 | a reference is malformed, names no definition, or starts a cycle |
REG-KIND-SCHEMA-LIMIT |
error | §3.3 | a schema has more than 4096 subschemas as written or expanded, an enum more than 1024 values, or a composition more than 16 branches |
REG-KIND-PATTERN |
error | §3.4 | a pattern is outside the pattern subset |
REG-KIND-PATTERN-LIMIT |
error | §3.4 | a pattern's size is over 4096, or would take the kind's patterns past 65536 |
REG-KIND-POINTER-FORM |
error | §3.5 | a pointer pattern is malformed |
REG-KIND-POINTER-UNREACHABLE |
error | §3.5 | a pointer pattern matches no position the schema allows |
REG-KIND-POINTER-CONFLICT |
error | §3.5 | a secret pattern and a reference pattern can match one position |
REG-REGISTRY-UNKNOWN-MEMBER |
error | §4 | the registry or one of its pins or entries has a member not defined |
REG-REGISTRY-MISSING-MEMBER |
error | §4 | a required member of the registry or of an entry is absent |
REG-REGISTRY-FORM |
error | §4 | a member of the registry, a pin, an entry, an overlay or a patch is not of its form |
REG-REGISTRY-DUPLICATE |
error | §4 | an environment or a pinned kind name is listed twice |
REG-REGISTRY-ORDER |
error | §4 | the pins or the entries are not in canonical order |
REG-PIN-MISSING |
error | §7.1 | no supplied kind declaration has a pin's digest |
REG-PIN-MISMATCH |
error | §7.1 | the declaration with a pin's digest has another kind, id or version |
REG-PIN-UNPINNED |
warning | §7.1 | a supplied kind declaration is not pinned |
REG-ENTRY-KIND |
error | §7.1 | an entry's kind is not pinned |
REG-ENTRY-ID |
error | §7.1 | an entry's id fails its kind's entryId pattern or the entry-id grammar |
REG-ENTRY-DUPLICATE |
error | §7.1 | two entries have one kind and id |
REG-ENTRY-OWNER |
error | §7.1 | an entry's owner is not in owners |
REG-ENTRY-ENVIRONMENT |
error | §7.1 | an entry names an environment the registry does not declare |
REG-OVERLAY-ENVIRONMENT |
error | §5 | an overlay's environment is not declared |
REG-OVERLAY-DUPLICATE |
error | §5 | two overlays have one environment |
REG-OVERLAY-PATCH-DUPLICATE |
error | §5 | two patches of one overlay name one entry |
REG-OVERLAY-ENTRY-MISSING |
error | §5 | a patch names no entry |
REG-OVERLAY-ENTRY-ABSENT |
error | §5 | a patch names an entry that does not apply in the overlay's environment |
REG-OVERLAY-POINTER |
error | §5 | a set key is not a JSON Pointer |
REG-OVERLAY-NOT-OVERLAYABLE |
error | §5 | no overlayable pattern matches a set key |
REG-OVERLAY-TARGET |
error | §5 | a set key addresses no reachable position |
REG-OVERLAY-NULL |
error | §5 | a set value is null |
REG-OVERLAY-PREFIX |
error | §5 | a set key is a prefix of another |
REG-VALUE-TYPE |
error | §7.2 | a value is not of an allowed type, or a false schema applies |
REG-VALUE-ENUM |
error | §7.2 | a value is not in its enum |
REG-VALUE-CONST |
error | §7.2 | a value is not its const |
REG-VALUE-REQUIRED |
error | §7.2 | a required member is absent |
REG-VALUE-ADDITIONAL |
error | §7.2 | a member is not allowed |
REG-VALUE-PROPERTY-COUNT |
error | §7.2 | an object has too few or too many members |
REG-VALUE-PROPERTY-NAME |
error | §7.2 | a member name fails propertyNames |
REG-VALUE-ITEM-COUNT |
error | §7.2 | an array has too few or too many items |
REG-VALUE-UNIQUE |
error | §7.2 | an array that must be unique has two equal items |
REG-VALUE-LENGTH |
error | §7.2 | a string is too short or too long |
REG-VALUE-PATTERN |
error | §7.2 | a string does not match its pattern |
REG-VALUE-RANGE |
error | §7.2 | a number is outside its bounds |
REG-VALUE-ANY-OF |
error | §7.2 | no branch of an anyOf holds |
REG-VALUE-NOT |
error | §7.2 | the schema of a not holds |
REG-VALUE-DEPRECATED |
warning | §7.2 | a value is at a position marked deprecated |
REG-BOUND-ENTRIES |
error | §7.1 | a kind has more entries than its maxEntries |
REG-BOUND-ENTRY-BYTES |
error | §7.1 | a resolved value is larger than its kind's maxEntryBytes |
REG-BOUND-VALIDATION-WORK |
error | §7.2 | value validation passed the reader's work bound, and this value and later ones were not checked |
REG-REPORT-TRUNCATED |
warning | §7.4 | the report holds its first 1000 diagnostics and more were found |
REF-ENTRY-FORM |
error | §6.2 | a value at a reference position is not an entry reference |
REF-ENTRY-KIND |
error | §6.2 | a reference names a kind its position does not allow |
REF-ENTRY-MISSING |
error | §6.2 | a reference names no entry |
REF-ENTRY-ABSENT-IN-ENVIRONMENT |
error | §6.2 | a reference names an entry that does not apply in the environment |
REF-ENTRY-POINTER |
error | §6.2 | a reference's pointer addresses nothing in the target's resolved value |
REF-SECRET-FORM |
error | §6.3 | a value at a secret position is not a secret reference |
REF-SECRET-STORE |
error | §6.3 | a secret reference names a store this version does not define |
REF-SECRET-PIN |
error | §6.3 | a secret reference floats, or names its project by number |
REF-SECRET-SCOPE-FORM |
error | §6.4 | secretScopes is not of its form |
REF-SECRET-SCOPE |
error | §6.4 | a secret reference names a project not listed for its environment |
REF-SECRET-SCOPE-SHARED |
error | §6.4 | a project is listed for two environments |
REF-SECRET-UNSCOPED |
warning | §6.4 | a secret reference is in a registry without secretScopes |
REG-YAML-ENCODING |
error | §9 | the file is not UTF-8 without a byte-order mark |
REG-YAML-DOCUMENTS |
error | §9 | the file holds other than one document |
REG-YAML-DIRECTIVE |
error | §9 | the file has a directive |
REG-YAML-TAG |
error | §9 | a node has a tag |
REG-YAML-ANCHOR |
error | §9 | a node has an anchor, or is an alias |
REG-YAML-MERGE |
error | §9 | a key is a merge key |
REG-YAML-SCALAR |
error | §9 | a plain scalar has another reading |
REG-YAML-EMPTY |
error | §9 | a node is empty |
REG-YAML-KEY |
error | §9 | a key is not a plain or quoted single-line string of at most 1024 characters |
REG-YAML-SYNTAX |
error | §9 | the file is not YAML |
REG-YAML-TRUNCATED |
error | §9 | the import stopped after 1000 refusals |
FACTS-DOCUMENT-LIMIT |
error | §10.1 | an entry's facts document is over a facts bound |
FACTS-ID-LIMIT |
error | §10.2 | a selected item's batch line id is not 1 to 256 bytes |
FACTS-CONTRACT-FORM |
error | §10.3 | a contract is not of its form |
FACTS-CONTRACT-ORDER |
error | §10.3 | a contract's facts are not in order |
FACTS-CONTRACT-LIMIT |
error | §10.3 | a contract is over a contract bound, or its generation is |
FACTS-POINTER-UNKNOWN |
warning | §10.5 | a pack reads a pointer the contract does not list |
FACTS-TYPE-ORDERED |
warning | §10.5 | a pack orders a pointer that is not decimal |
FACTS-VALUE-UNREACHABLE |
warning | §10.5 | a pack compares a pointer with a value the contract does not admit |
FACTS-CHECK-LIMIT |
error | §10.5 | the pack check is over its work or depth bound |
EMIT-MANIFEST |
error | §11.1 | the manifest is not of its form |
EMIT-OWNS-OVERLAP |
error | §11.1 | an owns glob and one of another manifest can match one path |
EMIT-REQUEST-VERSION |
error | §11.2 | the host writes no request version the manifest lists, or none that carries the registry |
EMIT-KIND-RANGE |
error | §11.2 | a pinned kind's version is outside the manifest's range |
EMIT-KIND-ID |
error | §11.2 | a pinned kind of a name the manifest reads has another kind id |
EMIT-OPTIONS |
error | §11.2 | the options are not admissible JSON, or fail the manifest's options schema |
EMIT-REQUEST |
error | §11.2 | the request is over its bound, or its pins and declarations do not match |
EMIT-PROCESS |
error | §11.3 | the emitter exited non-zero, or did not finish in time |
EMIT-RESPONSE |
error | §11.3 | the emitter's output is not one valid response |
EMIT-LINK |
error | §11.4 | a symbolic link or other reparse point is at or above an owned path |
EMIT-PATH-UNREADABLE |
error | §11.4 | an input, or an owned path, could not be read |
EMIT-WRITE |
error | §11.4 | a file could not be written or deleted, or a response path is held by a directory or an unowned file |
EMIT-INTERRUPTED |
error | §11.4 | an interrupt or a termination signal stopped the run |
EMIT-STRAY-WRITE |
error | §11.5 | the emitter created or changed a file itself |
EMIT-VECTOR |
error | §11.5 | the vectors are not of the harness's layout, or are past a bound on the vectors |
EMIT-HARNESS-BOUND |
error | §11.5 | a harness check could not be completed, past a bound, for want of a fresh HOME, or for a link out of the repository in its copy |
EMIT-DEPRECATED |
warning | §11.1 | the emitter's manifest is deprecated |
EMIT-ENV-UNSET |
warning | §11.4 | a variable the manifest's env lists is not set in the host's environment |
EMIT-REPORT-TRUNCATED |
warning | §11.4 | the host's report lists the first 1000 diagnostics of a list, and more were found |
EMIT-STAGING-LEFTOVER |
warning | §11.4 | an unowned temporary file of an earlier run is in a directory the host writes to |
EMIT-LINK-OMITTED |
warning | §11.5 | a link that leads out of the repository was left out of the harness's copy |
13. Versioning and stability
The companion is released on the scoped tag registry-v<major>.<minor>.<patch>, the Policy
companion's route without its draft-only restriction (VERSIONING.md). A first
release publishes this text, the closed schemas of its documents under schema/registry/1.0.0/,
the code list and the rows.
The first release is registry-v1.0.0, at status released: it is released, and not stable, and
the stability promise below starts at the first stable release. Its bundle is its own, and no Core
bundle carries the schemas, the code list or the rows. Its release record, releases/<tag>.json,
names the format, the $id of each schema, and the SHA-256 of this text, of every schema, of the
code list and of every row file, and the release builder holds the tagged tree to it. The commit a
registry tag names says released in this text's status sentence, in the code list and in the
rows' manifest, and no schema's title, description or comment in it calls the format draft or
unreleased; the builder refuses the tag otherwise. A schema keeps the bytes its first release
publishes at its $id: a later release of format 1.0.0 names the same schemas with the same
digests.
From the first stable release, within major version 1:
- no selector, member, diagnostic code, validation rule or harness check is removed or changes meaning;
- new optional members and new warning codes are added only under a new minor selector, and a check that can fail a vector only at a new harness level;
- a deprecated selector, member, code, rule or kind keeps working, with a warning, until 2.0, and
the code list gives each code its status,
activeordeprecated; - a reader claims conformance to an exact release and its complete rows.
Selectors across 1.x. Every selector of §2.1 is "1.0.0" in this version. A reader lists the
exact selectors it supports, and a writer writes the lowest selector whose format expresses the
document, so a reader of 1.0.0 keeps reading every document that needs no later member, and
refuses, rather than misreads, one that does. Consumers of resolved registries declare the
selectors they accept, and a producer writes one of them or refuses. A change to the facts
document's bytes is a new resolvedFormatVersion (§2.1).
14. Machine-readable form and rows
The code list and the rows are under
conformance/registry/1.0.0/,
with a README that says how each row is compared, and are published with the companion's first
release (§13). Every input is synthetic. Where a file and this text differ, this text governs. The
rows exercise admission, kind declarations, the registry's shape, pins, entries, overlays, both
kinds of reference, bounds and warnings, resolution in two
environments, facts batches, two generated contracts, two pack checks; the emitter host's manifest
and response rules (whole-tree and unportable owns globs, response paths, **, diagnostics
required and emitter codes) and its request, with a kind it does not read; and the harness's
references check and the expected/ marker. They do not yet exercise REG-ENTRY-ID,
REG-ENTRY-DUPLICATE and REG-ENTRY-ENVIRONMENT; value validation (§7.2) beyond REG-VALUE-RANGE
and REG-VALUE-DEPRECATED; YAML import, the report bound, the facts and contract limits, contract
reading, authored contracts, wildcard reference patterns, the facts-form request, overlapping
owns, a pin's kind id and the options schema, the emitter host's process and write rules, the
harness's other checks, its report and its own codes (the layout rows compare only that a run is
refused), or builders, and the boundary and adversarial sets RFC 0034 lists.
The schemas are under schema/registry/1.0.0/, published with the same release and
served at their $id from then on (§13): one JSON Schema 2020-12 schema for each document of
§2.1, which requires its selector at "1.0.0", and common.schema.json, the definitions they
share, which is the schema of no document. Each is closed wherever this text gives a document's
members, and states the forms, bounds, patterns, codes and severities this text gives. A rule no
schema can state, such as canonical form and order, a digest, a match between two documents, a
bound in bytes, or the limits of §§3.3 and 3.4, is left to the reader, and a $comment names its
section. A schema states only rules of this text, so a document it refuses is not of this text's
form, and one it admits may still fail a rule it cannot state. The harness report's schema holds
only its selector, since §11.5 names none of its other members. The facts document (§10.1) has
none here: it is a facts document of Core. Every row document a reader admits or writes validates
against its schema.
15. Conformance classes
| Class | Sections | Rows |
|---|---|---|
| Registry reader | §§2–8, §12 | class registry-reader |
| Importer | §9 | none yet |
| Facts writer | §§10.1–10.4 | class facts-writer |
| Emitter host | §§11.1–11.4 | class emitter-host |
| Emitter harness | §11.5 | class emitter-harness |
A claim names its class, the exact release, and its complete rows, which that release's record identifies by the digest of their manifest and of every row file (§13); a class without rows is defined, and not claimable. The pack check (§10.5) is in no class. The stable bar is two independently written readers agreeing on every row of a class.
16. Security and privacy
- Secrets. No component fetches or holds a secret's value. A resolved registry carries references as written; facts carry only a store and a scope. Pins close the "same registry, different secret" gap, and scopes the cross-environment leak.
- Disclosure. Reports, locations, check output and harness output carry codes, identifiers and
pointers, never values, references or file contents. An emitter's standard error is discarded by
default, and no
envvalue is printed. - Resources. Every document, schema, pattern, report, facts document, contract and emitter response is bounded, and patterns match in linear time.
- Authority. Owners are identifiers, not permissions: a valid registry authorizes nothing.
- Residual risk. Pinning cannot stop a store administrator replacing a version, and an emitter is code the repository chose to run; the host is not a sandbox. An emitter's diagnostic code of §11.3's form can still spell a value, such as a run of hexadecimal digits, and no host can tell.
17. What this text settles, and what is open
Settled here, where the records left it open or the reference runtime differs:
- the
kindlocation member on every step-2 diagnostic of a declaration whosekindis well formed (§7.3); - the cycle check covers every
$refthat names a definition, whatever else the schema has (§3.3); - an entry reference's
#pointeris at most 512 code points (§6.2), as RFC 0035 says, while a pointer pattern is at most 512 bytes (§3.5); - the
idof a kind and a registry is an RFC 3986 absolute URI (§3.1); - equal declarations are located at the least
kindDocument(§7.1); - the diagnostic codes RFCs 0034 to 0037 did not name are adopted as §12 lists them;
- an open position is listed at
pandp/*, and a pointer belowp/*is listed (§10.4); factsCheckFormatVersionis the check report's own selector, and the facts document has none (§2.1).- a resolved-form emit request carries the read kinds'
declarations, bound to their pins by digest, as part of request1.0.0(§11.2); RFC 0036 §2 names only the pins, and an emitter opens no file, so the reference emitters of §11.6 could not otherwise see a schema or a secret position; - the emitter host's stricter readings, which the reference runtime's host (
v0.48.0) applies and RFC 0036 left open: an emitter code's grammar and 64-byte bound, with the limit of what they can keep out stated (§§11.3, 16); a path or glob refuses:, a segment ending in.or a space, a Windows device name and a name git reads as.git, and the host never walks into.git(§§11.3, 11.4); anownsglob's first segment holds no*, and**matches zero or more segments between two others and one or more at the end, as in gitignore (§11.1);diagnosticsis required (§11.3); andEMIT-MANIFEST, the reference runtime's code for a manifest not of its form, is adopted, with the locations of it and ofEMIT-RESPONSE(§§7.3, 11.1, 11.3); - the codes of the emitter host's and harness's own refusals and warnings, which RFC 0036 left
without a code and the reference runtime (
v0.50.0) reports as provisional codes of its own, are adopted under those names and severities:EMIT-OWNS-OVERLAP(§11.1);EMIT-KIND-IDandEMIT-OPTIONS(§11.2);EMIT-LINK,EMIT-PATH-UNREADABLE,EMIT-WRITE,EMIT-INTERRUPTEDand the warningsEMIT-ENV-UNSET,EMIT-REPORT-TRUNCATEDandEMIT-STAGING-LEFTOVER(§11.4); andEMIT-VECTOR,EMIT-HARNESS-BOUNDand the warningEMIT-LINK-OMITTED(§11.5). So isFACTS-ID-LIMIT, the code of a batch line's id bound, which the reference runtime's batch of the dialect'sterraform-filesource reports (§10.2); - the harness's kind-filtering check compares requests, with every registry digest restored, before it compares responses (§11.5): RFC 0036 §5 compares responses alone, and the synthetic entry changes the registry's digest, which an emitter may write into a file, so an emitter that does would fail;
- a run passes the references check when it lies inside a complete occurrence of any string at a secret position, not only of its own (§11.5): RFC 0036 §5's "of R" fails two whole references of one project, which share a prefix of more than 32 characters;
- a vector that gives its request whole skips the references check as well as kind filtering, as the reference harness does (§11.5);
- the vector layout and its marker
expected/~emptyof a run that writes no files (§11.5), which the reference harness (v0.48.0) reads; RFC 0036 §5 names the files and gives no marker, and git keeps no emptyexpected/.
Open:
- Reference widening. A contract's
/references/<p>/valueis the union of every target kind's shapes (§10.4). Whether it should be narrowed to the kinds a position allows, per target, is not decided; this version writes the widening. - Pattern size, as written. §3.4 counts a pattern's size on the pattern as written. The
reference runtime
v0.47.0counts it on its engine's parse, which factors alternations and merges classes, and so admits(ab|ac){1000}, which is 5 000 as written. The text governs, and the rowpattern-boundsexpects the refusal. The runtime follows in a later release. - Reader bounds. A reader's own limits are not pinned: a pattern within the subset that its engine cannot compile (§3.4), and value validation past its work bound (§7.2). A conformance row stays well within the reference runtime's limits.
- Importer stops. Which refusals stop an import, beyond those §9 names, is fixed by the first import rows.
- Further host readings. The reference host is stricter than §11.3 in ways this text does not state yet: it resolves each emitter diagnostic's location against the request, so a location names only what the request holds; and it compares paths once case is folded and they are normalized (NFD), and refuses a path that is a directory of another. A host that follows the text alone accepts those responses.
- Pattern refusal. Whether patterns that are catastrophic for backtracking engines should also be refused (RFC 0034, Unresolved question 2).
- Review regime. The different-vendor review was waived for the records.