JSON and XML Serialization ========================== The JSON and XML representations are two serializations of one semantic item container. A conforming round trip preserves values, concrete runtime types, list order, and logical reference identity. Textual byte-for-byte equality is not required. JSON contract ------------- The root is an object with required ``items`` and optional ``topLevelReferences`` arrays. No other root properties are allowed. Every full item contains: * ``$type`` with its concrete, non-abstract COGS item type name; * every identification property; and * its modeled properties, using exact COGS names. An item-valued property and every top-level reference are flat references that contain only ``$type`` and all identification properties. With ``AllowSubtypes=false``, a property's reference type must equal its declared concrete item type. With ``AllowSubtypes=true``, it may be any concrete type assignable to the declared item type. Abstract declarations are treated as subtype-enabled. Top-level references may name any concrete item type. Full definitions may occur after references. Repeated references to the same compound key resolve to the same object within one ``ItemContainer``. A reference whose definition is outside the fragment remains an unresolved reference object with its identity intact. Composite values are embedded. They contain ``$type`` only when a property has ``AllowSubtypes=true`` and the concrete reusable type differs from, or must be disambiguated from, the declared type. The discriminator must name a concrete, assignable subtype permitted at that property. Unknown or duplicate object members, missing or empty identity members, duplicate full item definitions, abstract/incompatible discriminators, malformed primitive values, and non-finite JSON numbers are errors. JSON numbers obey the safe-integer and bounded exact-decimal interchange profile. Writers must not silently round an exact value into that domain. The generated schema prunes internal ``$defs`` while preserving this contract. All concrete item definitions, their required inheritance ancestors, and all built-in primitive definitions remain present. Model composites and the ancestors needed by their ``allOf`` chains are emitted only when recursively reachable from concrete-item effective properties. Each structural model definition declares only local properties; final item and composite value schemas use Draft 2020-12 ``unevaluatedProperties: false`` to close the object after inherited and local constraints have been evaluated. The global ``Reference`` definition remains available for ``topLevelReferences``. Property-local reference and tagged-composite restrictions are inline, so the schema inventory contains only model types, built-in primitives, and the global reference shape. ``duration``, ``dateTime``, ``time``, and ``date`` are strings annotated with the standard Draft 2020-12 formats ``duration``, ``date-time``, ``time``, and ``date``. Format assertion is deliberately disabled: the RFC format domains are not identical to the lossless XSD value spaces used by COGS. The authoritative COGS validator therefore applies the XSD lexical rules after structural schema evaluation. ``anyURI`` is a string annotated with the standard ``uri`` format and no generated regex pattern. The authoritative COGS primitive domain remains an RFC 3986 URI reference, which may be relative or absolute. A third-party validator with optional format assertion enabled can therefore reject a valid relative COGS ``anyURI`` value. The five Gregorian partial-date types are closed component objects. Members use exact PascalCase names: ``gYear`` has ``Year`` and optional ``Timezone``; ``gYearMonth`` also has ``Month``; ``gMonthDay`` has ``Month``, ``Day``, and optional ``Timezone``; and ``gDay``/``gMonth`` contain their component plus optional ``Timezone``. Calendar years are nonzero signed 32-bit integers. XML contract ------------ The root ``ItemContainer`` and all model elements are qualified by the model's ``NamespaceUrl``. The root sequence is all ``TopLevelReference`` elements followed by full item elements. Property elements follow the exact order of the effective model/XSD declaration; repeated elements remain in source order. An XML item reference contains every identification element in declaration order followed by ``TypeOfObject``. In the generated XSD, the identification sequence is the public global ``IdentificationGroup`` and every reference type reuses it before declaring its property-local ``TypeOfObject`` restriction. This schema refactoring does not change reference child order. Every newly written item reference carries the optional unqualified attribute ``isReference="true"``. It is declared as ``xs:boolean`` with fixed value ``true`` so XPath and other XML tooling can find references without inferring them from their children. Readers accept an absent marker for compatibility with older XML and accept the equivalent true lexical form ``1``. They reject ``false``, ``0``, a qualified marker, unknown reference attributes, or a marker on a full item. The marker is serialization metadata and is not a COGS property. A reusable subtype is represented with a namespace-qualified ``xsi:type`` QName and is allowed only where the property has ``AllowSubtypes=true``. ``langString`` is element text with a required ``xml:lang`` attribute. Readers reject a wrong root name or namespace, an unqualified model element, unknown attributes or elements, duplicate singleton elements, empty identity elements, invalid order, mixed text in element-only content, an unqualified or incompatible ``xsi:type``, malformed primitive lexical values, DTDs, and external entities. Prefixes are aliases only; namespace URIs and local names determine identity. Schema and runtime responsibilities ----------------------------------- Generated JSON Schema and XSD are both authoritative and must express the same cardinalities, facets, abstract restrictions, assignability, property-local substitution, and primitive domain. Generated runtimes reject structural and lexical errors and preserve lossless values; they may delegate a model-specific cardinality or facet violation to schema validation. Draft 2020-12 validators enforce standard JSON Schema keywords but treat ``format`` as an annotation by default and are allowed to ignore unknown vocabularies. Enabling optional format assertion can reject valid COGS values such as expanded XSD years, timezone-bearing XSD dates, or negative XSD durations, as well as relative COGS ``anyURI`` references, and does not replace COGS instance validation. Temporal and duration bounds that require the XSD partial order are carried in ``x-cogs-minInclusive``, ``x-cogs-minExclusive``, ``x-cogs-maxInclusive``, and ``x-cogs-maxExclusive`` metadata. ``CogsInstanceValidator`` (exposed by ``validate-instance``) is authoritative for those extensions, temporal lexical values and year limits, duplicate JSON member names, exact decimal lexemes, and duplicate full definitions. XML validation uses the generated XSD plus the same primitive and duplicate-definition checks. See `JSON Schema Draft 2020-12 validation `_ for the format-annotation vocabulary and `RFC 3339 `_ for the narrower Internet date/time profile used by those standard format names. A conformance test validates every intermediate JSON document against JSON Schema and every XML document against XSD. It then compares a canonical semantic tree and asserts that repeated/forward references resolve to the same in-memory object. Testing only that a runtime can read its own output is not a cross-publisher conformance test.