RFC-0050 — A list property type
- Status: Draft
- Track: G14
- Relates to:
- RFC-0040 and RFC-0046 (the precedent for a new declared type: one arm in
property_type_violation, one in each SDK's schema compiler, one parity fixture) - RFC-0044 (the declared value set, which this RFC applies to each item of a list)
- RFC-0018 (the query surface, which refuses an operator it cannot answer on a list)
- RFC-0049 (the warehouse contract, which today refuses a
listproperty outright)
- RFC-0040 and RFC-0046 (the precedent for a new declared type: one arm in
- Versioning layers touched: SDK parity 0.18.0 → 0.19.0 (
OntologyProperty.itemsand.fields, thelistarm in all three class schema compilers).yidam-core0.11.0 → 0.12.0, because two public fields on a struct a caller can construct exhaustively read as breaking tocargo semver-checks. Tooling: one arm inproperty-type, a narrowed node-standing read, two new lint checks, a warehouse skip in place of a refusal. No MCP contract bump: a list has no order, and both refusals below use codes the contract already freezes. No migration. - Downstream reference cases:
- #1391,
travel-demand'spathway.effect: several effect sizes on one node, each with its own source and its own standing, declared with a coinedtype: effectthat nothing reads. - #1382, civic-infrastructure's
model.parametersandfailure-mode.effects: an untyped list whose entries carryclaim_tag: open, read as the standing of the node that holds them.
- #1391,
Summary
A corpus cannot say that a property holds several values, or that each value is a record with
its own fields. This RFC adds one type, list. A list declares what its items are in one
of two ways: items: names a scalar type that every item has, and fields: declares the
fields of a record that every item is. A claim field inside a record is the standing of that
entry and not of the node. A source field beside it resolves the way a link's source: does.
Problem
The two corpora that asked
Both derived repositories hold values that carry their own evidence. One pathway in
travel-demand carries a short-run and a long-run fare elasticity. One rests on a
meta-analysis of 33 studies and the other on 3, so a single node-level standing cannot hold
both. civic-infrastructure keeps a model's parameters the same way.
Neither corpus has a sanctioned form to write this in, so each wrote what it could:
travel-demandcoinedtype: effect. The gate leaves a coined type alone, so a nonexistentsource, aclaim_tagofdefinitely-trueand a textvalueall passed bothgraph-checkandlint(#1391).- civic-infrastructure left the list untyped. The claim reader walks the whole node at any
depth, skipping only
links. It foundparameters[].claim_tag: openand reported that the node declares[open], while the node's own declared standing wasinference(#1382).claim-property-undeclaredthen told the corpus to declareclaim_tagas a top-level property, which misdescribes the node.
What is on this machine
Measured 2026-10-29 over the tracked corpora under /Users/cparent/Code (20 repositories,
4,603 instance nodes). The two reference corpora are not among them.
- 5 property values are lists, all in one repository.
demi-moorealready coinedtype: list, onobservation.extractsandpriority.extracts. It declares neitheritems:norfields:. Every value is a non-empty list of mappings with the keysfile,produced_by,key,grain,reconcileandseries.- No other property value is a list, outside
claimandquotation, which already accept one.
The population is small, and that makes the change cheap. It also puts one constraint on the
design: type: list written bare must stay valid, because one corpus has already written
it.
Proposal
One type, three forms
properties:
- name: aliases # a list of one scalar type
type: list
items: string
- name: effects # a list of records
type: list
fields:
- { name: label, type: string, required: true }
- { name: value, type: number, unit: elasticity }
- { name: claim_tag, type: claim }
- { name: source, type: ref }
- name: extracts # a list of anything
type: list
A value is a non-empty YAML sequence. A single item that is not wrapped in a list is
reported by property-type. The one-or-a-list tolerance that claim and quotation have
exists because claim_tag: [open] becomes a list without the author meaning it to. A
property declared list was meant to be a list. An empty list is reported as well, because it
says nothing that leaving the property out does not. This is the same reading RFC-0044 gives
values: []: an empty list is absent.
items: and fields: are mutually exclusive. A declaration with both is malformed, and
so is one naming a refused type. A malformed declaration is reported on the class, by
list-declaration-invalid (Error), and its values are checked only as a bare list. Neither
is required. A bare list checks only that the value is a non-empty sequence, which
is what demi-moore relies on.
items: — a list of one scalar type
items: names one of string, text, ref, date, number or claim. Each item is
checked by the same arm of property_type_violation that checks a top-level property of that
type. values: and unit: on the list apply to every item, as they would to one scalar.
items: list and items: quotation are refused. A nested list has no reference case. A
quotation already accepts a list of itself.
fields: — a list of records
fields: is a list of property declarations, in the grammar class properties already use:
name, type, required, values, unit and description. Each item must be a mapping:
- each declared field is checked by the arm for its type
- a field declared
required: truemust be present in every item - a key the declaration does not name is reported, by
property-type. A record follows the rule a class follows.undeclared-propertygates a key the class did not name, once the class names any. Silence still constrains nothing: a barelistdeclares no fields and closes nothing.
A field may be any scalar type or claim. A field typed list or quotation is refused in
this RFC. The quotation reader matches top-level keys only, so a nested quotation would go
unchecked and uncounted. See Open questions.
A record's standing is the record's
This is the #1382 fix.
A node's standing is read only from the claim-typed properties at the top level of
properties:, or of the document itself. One reader, declared_values, now serves
node_standing, structural_claims and the counts, and it never descends into the value of
any property. named_values, the walk it replaced, is gone. The document root stays a level
because the edge-claim fixtures write status: there. That covers both cases:
- a property declared
list - an undeclared property whose value is a list or mapping
GRAPH.md already says that "a node's standing here is a property its class declared type: claim", and agent-conduct.md calls it "the declared claim-typed field". A tag inside an
undeclared list is neither. The walk is what departed from that rule.
A claim field in a record is one claim per entry. status, open-questions,
corpus-index and the MCP claims tool count it, with the same parser that grades a node's
type: claim. Each entry is served as a statement-scoped claim, labelled by its list and item number,
and node_standing reads node-scoped claims only, so it does not count toward the node's own
standing. An entry tagged [open] is an open entry of a node that may itself be
[verified].
claim-property-undeclared stops reporting a tag that a fields: declaration names. A
nested claim_tag under a property that is not declared list is still reported, and
the suggestion changes: declare the property type: list with a claim field, instead of
declaring the tag at the top level.
A record's source resolves like a link's
This is the #1391 ask. When a fields: declaration includes a claim field, the record is
an evidenced entry. A source key in an evidenced entry resolves exactly as an edge
source: does, by stem or by path through source_targets. One new check:
| Check | Severity | Reported when |
|---|---|---|
entry-source-unresolved | Error | an evidenced entry's source: names no catalog entry or node |
list-declaration-invalid | Error | a list declaration names both items: and fields:, an items: type outside the six, or a field typed list or quotation |
The population is empty until a corpus declares fields: with a claim field, so no
existing corpus fails the day this ships. A resolved source: counts as a citation of its
entry, the way an edge source: counts (#1174). It is rewritten by yidam rename, which
already rewrites source: by key name, in block style only. A flow-style entry, { source: x },
is not rewritten, as a flow-style edge is not today.
The rule is keyed on the name source and not on a type. A link already uses that name for
the same meaning, and a ref field is not resolved anywhere today. Both #1391 and #1382 spell
the field source.
The compiled schema
property_schema takes the whole declaration, not (type, values), in all three SDKs:
| Declared | Compiled |
|---|---|
list | {"type":"array","minItems":1} |
list, items: T | {"type":"array","minItems":1,"items":<schema of T with the list's values/unit>} |
list, fields: […] | {"type":"array","minItems":1,"items":{"type":"object","properties":{…},"required":[…],"additionalProperties":false}} |
The record object is closed, as the class's property bag is, because the gate reports an
undeclared key. required is omitted when it is empty, as at class level. An empty fields: []
declares nothing and compiles as a bare list, the way values: [] declares no set. items: and fields: declared together, or
either one set to a type that is refused, compile to true. This matches the gate, which
reports the declaration and constrains nothing.
every-declared-type.toml gains all three forms. A new fixture holds a malformed fields:.
Rust's parse_class deserialises with serde, and one wrongly shaped field would empty the
whole class, while Python and TypeScript tolerate a bad field one at a time. The fixture
holds all three to the tolerant behaviour.
What the other readers do
yidam schemaaddslistto both type enums and declaresitemsandfieldson the property item. The property item'sadditionalProperties: falsewould otherwise refuse them. A field's schema is not recursive: it has noitemsorfieldsof its own, because a field cannot be alist.- Query.
prop?works. Orderings are refusedunordered-property, as on every type exceptdateandnumber.=and~are refusedunsatisfiable-predicate. Membership (aliases=foomeaning that any item equalsfoo) is a new semantics for the contract, and is deferred. - Warehouse. A
listproperty gets no column, asclaimandquotationget none, and textql lists it in the Stated in prose section. Today the contract refuses it, so this loosens the contract. Emitting a child table is RFC-0049's business. migrate. A retype intolistis accepted only when every value already satisfies the declaration. That is the rule every retype follows, throughproperty_type_violation.graph.json, the editors anduniversal.ymlcarry the bare type string and nothing else in this RFC.items:andfields:are read from class files only.
Prose
- GRAPH.md gains one paragraph beside
numberandquotation, and the standing sentence names the top level. The word budget inprelude_rules_and_evidence.rsmoves by that paragraph. - GRAPH.evidence.md gains a
#listanchor with the reference cases. docs/configuration.md,bootstrap.md,yidam/sdks/README.mdand thetypedescription inreport.schema.jsongain the word. Three of these already omitnumberorquotation, so this edit corrects them as well.docs/upgrading.mdgains an entry.
Migration & compatibility
-
A corpus that coined
list. The gate now reads the type.demi-moore's five values satisfy the bare form as they stand (measured above). -
The warehouse contract stops refusing that corpus.
-
A corpus whose node standing came from a nested tag. Its standing changes. That standing was the #1382 defect, but a corpus could have come to depend on it.
watermark-directoryprojects its corpus and puts typed fields wherever its exporter writes them. Its projection is untracked, so it was not measured.Measured 2026-10-29 over the 20 corpora on hand, 5,132 nodes. Every one of the 1,921 declared claim values sits at the top of
properties:. None is nested and none is at the document root. The narrowing moves no count on any of them. The unit test that pinned the old nested read,a_nested_declared_field_is_found, is replaced bya_nested_declared_field_is_not_the_nodes.
Alternatives considered
type: [string]orlist<string>. These are shorter, but they put a grammar inside a string. Every reader that matchestypeas a bare word would mistake the string for a coined type and pass it silently.- A
multiple: trueflag on any type. This handles scalar lists and has no place to declare a record's fields, which is the case both issues are about. - A
recordtype, so that a list of records isitems: record. That adds two types where one will do. No corpus holds a single record that is not in a list. - Leaving a record open to undeclared keys. This would be looser than the class level,
where
undeclared-propertygates. A misspelledclaim_tgwould then pass as an undeclared key, and the entry would read as having no standing. That is the silent loss #1391 reports. - Splitting each entry into its own node with a graded link. This is #1391's fallback. It works today. It costs the corpus the engine-facing shape it was asked for, and it costs one node per elasticity.
Open questions
- Nested quotations. A
quotationfield in a record needsquotations::Declaredto walk record fields. The three quotation checks and the citation count read that walk. This is deferred until a corpus asks. - Query membership. Should
=on anitems:list mean "any item equals"? Answering yes changes the contract and bumps the MCP version. - A
property-typefinding for an unknown type. #1391 also asks for this. It is a separate change, because it reddens every corpus that coined a type, not only the ones that coinedlist. Settled as a warning,property-type-unknown: over 23 tracked corpora on this machine (1,173 declared properties, 2026-11-11) none coins a type, so only a corpus off it, such astravel-demand, sees the finding, and it does not gate. - The node-standing narrowing. Settled by the measurement in Migration: no corpus on hand puts a declared claim field anywhere but the top level, so the walk "a projected corpus may put its typed fields anywhere" served no corpus measured. An unmeasured projection could still depend on it.