RFC-0044 — A declared value set
- Status: Draft
- Track: G12
- Relates to:
- RFC-0040 (the numeric type, whose
unit:is the precedent for a fact about the column declared besidetype:and carried through unchanged on every other type) - RFC-0016 (the ontology contract, whose
property-typecheck gains a second predicate and whose compiled class schema gains one constraint) - RFC-0038 and RFC-0039 (the rules/evidence split and the occasion-scoped read —
GRAPH.mdgains one sentence and the ceilings move by that sentence)
- RFC-0040 (the numeric type, whose
- Versioning layers touched: SDK parity 0.14.0 → 0.15.0 (
OntologyProperty.values, theenumarm in all three compilers).yidam-core0.9.0 → 0.10.0, becausevaluesis a new public field on a struct a caller can construct exhaustively, whichcargo semver-checksreads as breaking. MCP contract unchanged: no operator, rejection code or message moves. CLI surface:property-typereports astringoutside its declared set;migrate retypeintostringis held to the set. No migration. - Downstream reference case:
allen-county-ohio'ssite.status, whose description reads "extant | demolished | ruin | repurposed | in operation" and whose instances hold"demolished in 1971", andmatt-huffman'stenure.how_ended, declaredresigned | term-limited | lost | ...in prose and holdingresigned to enter Congress.
Summary
A class cannot declare a closed set of values, so 40 properties across seven corpora spell one
in their description, where nothing reads it, and 33 instances hold a value outside the set
their own class documents (#1052). This RFC adds one field, values:, beside type: on
a string property, and states the three rules that make it usable: declaring the set
closes it; the match is exact, as written; and the field binds string alone. The gate
property-type reports a value outside the set, and the compiled schema carries the set as
enum, so the two cannot disagree about what a value may be.
Problem
A closed set is the most common shape a string property takes in the derived corpora — a
status, a kind, a mode, a how-it-ended — and the ontology has no word for one. So a class
writes it where it can, in the description:
- name: status
type: string
description: extant | demolished | ruin | repurposed | in operation
The description is prose. lint does not read it, the compiled schema does not carry it,
and an editor completing the field has nothing to offer. What the corpora show is the
consequence: measured across seven of them, 40 properties document a set this way and 33
instances have drifted off it. The drift is of two kinds, and both are the finding this RFC
is for. One is a widening nobody recorded — abandoned where the set says demolished
or ruin — which the author may well have meant, and the class should now say. The other is
prose in a token field — "demolished in 1971", resigned to enter Congress — where the
year and the reason belong in another property or the detail, and the token has stopped
being a token. Neither is reported today, and a query for site[status=demolished] silently
misses both.
RFC-0040 already put a fact about a column beside type:. A value set is the same kind of
fact, and the description is where it was living because the declaration had no room for it.
Proposal
One field, values:, beside type:
- name: status
type: string
values: [extant, demolished, ruin, repurposed, in operation]
description: Whether the site still stands.
A list of strings, on the declaration. The instances carry the token, as before. The description goes back to being a description.
Spelled as a sibling of type: rather than as a type of its own — type: [extant, ...] or
type: enum with the set elsewhere — because it is a fact about a string, and every reader
that already dispatches on type keeps working. unit: is the precedent, and so is
edge_policy: a fact about a declaration is declared on it, in its own key.
Declaring the set closes it
There is no closed: true beside it, and no open: marker. A class that writes the set has
asked for the gate, as a class writing edge_policy: exhaustive has. The alternative, an
open list that documents the common values without binding them, was rejected because it is
the description again: a list nothing enforces is what the 40 properties already have.
A class that wants an unbounded string declares no values:, which is every class today,
so nothing changes for a corpus that does not ask.
An empty list is absent. values: [] binds nothing rather than refusing everything, because
a closed set of nothing is not a set any class means.
The match is exact, as written
in operation matches in operation and nothing else — not In operation, not
in-operation, not a trimmed or folded spelling. JSON Schema's enum is exact, and the
gate's rule is no stricter than the schema, which cuts both ways: a gate that admitted
In operation would be looser than the schema it exists to be no stricter than, and a
corpus would learn the difference from a validator instead of from lint. A class that
wants both spellings declares both.
The set is published in declaration order, unsorted and untrimmed, so the three compilers produce one document.
The field binds string alone
text is prose and has no set. ref is a path. date and number are values, not tokens.
claim has its own set, the six evidence tokens. A coined type has said the gate does not
know its shape, and a set on it would be the gate half-knowing. On every one of these
values: is carried and ignored, as unit: is off number — carried, so a class-file
schema of this CLI does not refuse it; ignored, so a retype away from string does not
silently keep binding.
That last clause is what migrate retype reads. A retype into string on a property that
declares a set is the moment the set starts to bind, and an instance outside it would be a
migration into a failing build — the refusal retype already makes for a value the new type
cannot hold. It reports each instance, names the two repairs, and writes nothing.
The gate and the schema say one thing
property-type gains the predicate rather than a check of its own, because it is the same
finding: a value the declaration does not admit. The type is tested first, then the set. A
bare 7 under a string is reported once, for its shape, and not a second time for not
being one of extant, demolished and ruin. The message names the set, so the repair is
in the finding.
The compiled class schema emits {"type": "string", "minLength": 1, "enum": [...]} for a
string that declares a set — a constraint, unlike x-yidam-unit, because the gate refuses
an off-set value and a schema that admitted one would be looser than the gate. universal.yml
declares types and no sets, so the universal arm of the check is unchanged.
What this does not touch
- The query checker.
site[status=abandoned]against a class whose set lacksabandonedis a predicate no row can satisfy, andunsatisfiable-predicateis the rejection for it. It is not added here because it would move the MCP contract, and the contract stays where it is until a client asks. See the open questions. - Non-
stringtypes. No set on anumber, no set on a coined type. - A rename across the set.
creek→streamon the declaration and every instance isproperty-rename's shape one level down, and it is a migration of its own (migrate value, #1120), not a consequence of declaring the set. - The index and
retrieve. Astringwith a set is the same column it was.
Migration & compatibility
No corpus declares values:, so no corpus changes. A class file carrying it is refused by
the class-file schema of every CLI before this one (additionalProperties: false), which is
the right refusal: an older CLI would compile the set to nothing and validate abandoned as
fine, and a corpus should learn that from a schema error rather than from a green build that
means less than it says.
A corpus that adopts the field on a property with drifted instances will see each one reported, which is the point. The 33 are the reason the field exists, and every one of them is either a value to add to the set or a token to restore.
Alternatives considered
- An
enumtype. Rejected above: it forks every reader that dispatches ontype, and the set is a fact about astring, not a different kind of value. - An open list, or a
closed:flag. Rejected above: an open list is the description again, and a flag is a second declaration to forget. - A case-folded or trimmed match. Rejected above: the schema's
enumis exact, and the gate is no stricter and no looser than the schema. - Reading the set out of the description. The
a | b | cshape is regular enough to parse, and parsing it would have reported the 33 without a new field. Rejected because a description is prose, and a gate that reads prose as a declaration has invented one on the author's behalf — the failureclaim-tag-malformedexists to report.
Open questions
- Whether the query checker should refuse an off-set literal.
status=abandonedwhere the set lacks it is unsatisfiable, and saying so is cheap. Lean: yes, when the contract next moves for another reason. It is one arm incheck_predand one line in the contract. - Whether a set should be declarable on a coined type. A corpus that coined
site-statusand wants it closed has to retype tostringtoday. Lean: no. A coined type is the corpus saying the gate does not know the shape, and a set is the gate knowing it.