JSON Schema Generation#

The publish-json command generates a JSON Schema that describes the JSON serialization contract shared by the generated C#, Python, and TypeScript models.

Container shape#

The schema describes a flat ItemContainer with two top-level properties:

topLevelReferences

An array of item references.

items

An array containing every serialized item instance.

References#

References are simple JSON objects. They contain:

  • $type

  • the configured identification properties

Identification from both Identification.csv and Identification.Mixin.csv is reflected in the generated reference shape.

Discriminators#

The schema declares an item hierarchy’s $type property once on its root definition. Concrete item alternatives narrow that inherited property to the exact item type. Reusable datatype substitution adds a property-local $type restriction for each permitted concrete alternative. Discriminator values are constrained with enum.

  • derived item and composite definitions use allOf to reference their parent and declare only their local properties

  • concrete alternatives in the items union combine the structural item definition with its exact discriminator

  • reusable datatype substitution uses $type only for concrete assignable types permitted by that property’s AllowSubtypes setting

Structural definitions remain open so descendants can extend them. At each actual item or composite value boundary, Draft 2020-12 unevaluatedProperties: false closes the successfully composed definition. This accepts properties evaluated through $ref/allOf while continuing to reject unknown instance members. Consumers must use a Draft 2020-12 processor that implements the required unevaluated vocabulary; an older processor cannot enforce this closed inheritance boundary.

Definition inventory#

The publisher emits a minimal set of model-defined $defs without changing the JSON wire contract:

  • every concrete item retains a structural definition because it is a possible member of the root items array, together with each ancestor required by its allOf inheritance chain;

  • every built-in COGS primitive definition remains available, even when the model does not use that primitive;

  • a model composite definition is emitted only when it is reachable, recursively, from an effective property of a concrete item, together with the ancestors needed by an emitted composite;

  • the global Reference definition is always retained for topLevelReferences.

Tagged composite alternatives and property-specific item-reference constraints are expressed inline rather than as additional schema types. An item-valued property uses allOf to reference the one global Reference shape and restricts only its inherited $type enumeration when the property permits fewer than all concrete item types.

The schema closes unknown content, encodes model cardinalities and representable facets, and uses the primitive value spaces in Model Format. duration, dateTime, time, and date are strings carrying the standard Draft 2020-12 duration, date-time, time, and date format annotations. anyURI is a string carrying the standard uri format annotation and has no generated regex pattern. The five Gregorian partial-date types are closed objects using the applicable PascalCase Year, Month, Day, and optional Timezone members. Integers and decimals remain JSON numbers under the shared native profile. cogsDate requires exactly one existing PascalCase arm and uses the component objects for its Gregorian arms.

Formatting#

The generated JSON Schema file is written in pretty-printed form.

Custom instance validation#

Standard Draft 2020-12 treats format as an annotation by default. COGS does not enable the optional format-assertion vocabulary because the RFC format domains differ from COGS: for example, COGS permits negative durations, local times and end-of-day time spelling. COGS anyURI also accepts RFC 3986 relative URI references, while the standard uri format describes absolute URIs. COGS emits companion metadata for temporal and floating-point bounds and enumeration. Use validate-instance when those extensions, the COGS primitive domains and nonzero signed-32-bit calendar-year rule, duplicate JSON member rejection, exact decimal interchange checks, and duplicate definition checks must be authoritative. Enabling format assertion in a third-party validator may reject valid COGS temporal values or relative anyURI references.