OO-LD/oold-schema: v1.0.0-rc.3

Third release candidate for v1.0. Mostly a normativity pass: several requirements turned out to be stated in places the specification disclaims, so nothing could cite them.

Requirements rescued from non-normative prose

Four requirements existed only inside a :::example, a :::note, or a section marked .informative. A reader could follow them, but they bound nobody and the rule catalogue could not see them.

• OOLD-SCH-2d05 (MUST NOT) - an implementation must not treat an unmapped term as a conformance failure, though it may report one or reject it under an opt-in strict mode. The permission behind this was in the introduction, which is informative.
• OOLD-SCH-21d7 (SHOULD) - a schema should offer at least one complete mapping, a target profile under which every declared property carries a term. Pairs with the above: leaving a term unmapped is a deferral, not a destination.
• OOLD-VER-46b9 (SHOULD) - a schema carrying x-oold-uuid should also use that UUID in its $id. Previously only "It is recommended to..." inside an example.
• OOLD-CMP-... (MUST) - a composed object is closed with unevaluatedProperties: false, not additionalProperties: false. #closing-composed-objects was marked informative despite being the only place the mechanism is stated.

#ui-generation is now normative. Its keywords live in oold-ui-meta-schema.json, which the dialect base $refs, so every OO-LD schema is already validated against them - a schema writing "x-oold-ui-widget": 42 is rejected today. Disclaiming the section defining them meant the specification disowned a constraint it enforces. The subtree carried no RFC 2119 keyword, so nothing became binding by accident; #validator-vs-widget keeps its own .informative.

Enum names and descriptions

x-enum-varnames and x-enum-descriptions were emitted by tooling and present in the meta-schemas, but described only in informative prose. Now specified in a normative #enum-names section, and moved into oold-meta-schema-base.json beside the other keywords.

• OOLD-EXT-b249 (SHOULD) - declare x-enum-varnames where any enum value is not a valid identifier, since each generator otherwise applies its own mangling.
• OOLD-EXT-b23b (SHOULD) - a form generator labels an option with x-oold-ui-enum-titles where given, and may present x-enum-descriptions as further explanation.
• OOLD-EXT-1e3c (MUST) - a widget hint that is not a registered format is carried in x-oold-ui-widget, not format.

Both keep their unprefixed names deliberately: the OpenAPI Specification defines no enum-naming keyword, so these are conventions of generator tooling, and an x-oold--prefixed spelling would be read by nothing.

Catalogue integrity

• A :rule[...] inside a .informative section is now rejected at extraction. Only :::note / :::example were guarded, so a rule written in an informative section was rendered without RFC 2119 markup and catalogued as normative anyway.
• NOT RECOMMENDED is admitted as a level, and check_spec fails when the extractor's vocabulary and the catalogue schema's enum disagree in either direction. A rule stated with it previously wrote a catalogue that failed its own schema.
• OOLD-CMP-a05a reclassified machine_checkable=no: its trigger is authorial intent, which no validator can see.

73 rules, up from 66.

Documentation

The site is restructured into five tabs - Introduction, Guide, Use Cases, Rule Catalogue, Specification - with Get Started folded into the Introduction, the mappings split one page per format, and reference renamed related-work. Content moved verbatim.

/get-started/ and /reference/ no longer resolve. Versioned URLs are unaffected: https://oo-ld.org/1.0.0-rc.2/ keeps both.

Feedback

Comments welcome in https://github.com/OO-LD/oold-schema/issues/116.