JSON Structure: OpenAPI Binding

4.1. Binding Parameters

A dialect binding MUST declare the following. These declarations are the only dialect-specific inputs the rest of this part requires.¶

A binding MUST NOT redefine the OAS meaning of $schema, jsonSchemaDialect, or the Reference Object, and MUST NOT introduce new fields into any OAS Object.¶

4.2. Reference Object Classification

Before dialect selection can apply, tooling MUST determine whether a JSON object occupying a Schema Object position is an OAS Reference Object ([OAS], "Reference Object") or a Schema Object. The two are distinct object types accepted at the same positions. Only a Schema Object is subject to dialect selection (Section 4.3). A Reference Object is never dialect-selected, whatever jsonSchemaDialect default is in scope.¶

A JSON object at a Schema Object position is a Reference Object if and only if it is limited to the fixed fields of the OAS Reference Object ($ref, summary, description) and carries no other properties. An object that contains $ref together with any other property outside that fixed set is not a valid Reference Object. Tooling MUST reject that object as invalid at the OAS layer before dialect selection. It MUST NOT reinterpret the extra properties as dialect Schema Object content. An object without $ref is classified as a Schema Object and is then subject to dialect selection, including when it carries $schema.¶

A components.schemas entry that is a bare Reference Object (for example { "$ref": "#/components/schemas/Pet" }) MUST NOT be treated as a schema in the selected dialect when the document default jsonSchemaDialect names that dialect. It remains an OAS Reference Object and is resolved on the OpenAPI reference layer (Section 4.7). It has no schema content of its own, and dialect selection therefore does not apply to it.¶

Tooling MUST classify a Schema Object position by this rule before performing dialect selection. Tooling MUST re-classify at every Schema Object position independently. Classification is not inherited from a containing resource.¶

4.3. Dialect Selection

A Schema Object belongs to a bound dialect when its effective dialect is one of that binding's declared dialect URIs (Section 4.1). The effective dialect is determined exactly as in the OAS dialect-selection rules (Section 4.24.7, "Specifying Schema Dialects", of [OAS]):¶

1. If the Schema Object is a schema-resource root and carries $schema, that value is the dialect.¶

2. Otherwise, the OpenAPI Object's jsonSchemaDialect value, if present, is the dialect.¶

3. Otherwise, the OAS dialect applies and no binding governs the Schema Object.¶

A dialect whose schemas natively carry $schema yields self-describing Schema Objects. Pasting such a schema into a Schema Object position, with its $schema intact, is sufficient to select the dialect.¶

A Schema Object position accepts a JSON object, and in the OAS dialect also a boolean ([OAS]). It accepts neither a JSON array nor a JSON string. A dialect whose schema forms include such values is bound only for the forms that position accepts. A binding MUST declare which of its dialect's forms are usable there (Section 4.1). Tooling MUST reject a Description that places any other form of a bound dialect at a Schema Object position. The restriction applies to that position alone. Inside a Schema Object, the dialect's remaining forms are unrestricted.¶

A schema-resource root is a Schema Object that is independently addressable by the OpenAPI Description or that tooling extracts as an independent schema document. This includes every entry in components.schemas. It also includes an inline Schema Object at a request body, response, parameter, callback, webhook, or other OAS Schema Object position, once tooling extracts it for standalone processing.¶

Schema Objects nested inside an already-selected resource are part of that resource. They do not establish a second dialect selection context. A nested $schema value MUST NOT override the resource-root dialect. Tooling MUST reject a nested $schema that would make the nested object ambiguous.¶

Dialect selection is per schema-resource root, not global to the Description. An OpenAPI Description MAY contain ordinary OAS Schema Objects and Schema Objects in one or more bound dialects. Tooling MUST apply the effective dialect independently at each resource root.¶

4.4. Recognizing and Rejecting Dialects

• Tooling that supports a binding MUST recognize the dialect URIs that binding declares and MUST process a Schema Object bearing one of them as a schema in that dialect.¶

• Matching a $schema or jsonSchemaDialect value against a declared dialect URI MUST be exact, byte-for-byte string comparison unless the binding declares a normalization. Tooling MUST NOT apply URI normalization, trailing-slash equivalence, or version-range matching on its own initiative. A future version of a dialect that defines new URIs is a new or updated binding.¶

• Tooling that does not recognize a dialect URI MUST treat the Schema Object as an unknown dialect. It MUST NOT process the Schema Object as an OAS-dialect (JSON Schema Draft 2020-12) schema. Unrelated dialects routinely assign different meaning to the same keyword spellings. A reader MUST preserve the raw Schema Object and its surrounding Description for pass-through or explicit diagnostic handling, and MUST NOT silently deserialize it as an OAS Schema Object. A tool MAY fail the operation when it cannot preserve or expose the unknown object, but MUST report the unknown dialect as the cause.¶

• Where a dialect permits deriving a custom meta-schema from a declared one, the derived URI does not satisfy exact-match recognition. Tooling MAY be separately configured to recognize specific derived URIs, and once so configured MUST process Schema Objects bearing them under the declared dialect they extend. Tooling that is not so configured MUST apply the unknown-dialect rule above.¶

• A resource-root Schema Object SHOULD carry $schema explicitly, even when the document default already selects the same dialect, so that the schema remains self-describing when extracted from the Description.¶

• Tooling MUST construct and materialize defaults per Section 4.5 and Section 4.6 whenever a Schema Object lacking them is extracted for standalone processing.¶

4.5. Default Resource Identity

This section applies when the binding declares an identity keyword (Section 4.1). "Identity keyword" below means that keyword.¶

A resource-root Schema Object SHOULD carry its own identity keyword. When it does not, tooling still needs a stable, unique identifier for it, for example to run the Schema Object through a standalone validator for its dialect. This section defines how tooling MUST construct that default. The construction combines the Description's base URI with the Schema Object's location inside the Description.¶

A default identity constructed this way is for standalone processing only. It is NOT registered as a target for the dialect's cross-document mechanism. Section 4.8 matches exclusively against explicitly declared identities. A Schema Object intended to be reachable by another entry in the Description MUST carry an explicit identity.¶

Find the Description's base URI. Tooling MUST try the following sources in order, using the first one that applies. This is the same precedence OAS itself uses for base URI determination (Appendix F, "Examples of Base URI Determination and Reference Resolution", of [OAS]):¶

1. the OpenAPI Object's $self field, if present (OAS Appendix F.1);¶

2. otherwise, the base URI of an encapsulating entity, if any, such as a multipart/related archive (OAS Appendix F.2);¶

3. otherwise, the Description's retrieval URI: the URI it was actually fetched from (OAS Appendix F.3);¶

4. otherwise, an application-specific default base URI, if the tooling defines one (OAS Appendix F.4).¶

None of these applies to a Description that was authored offline and never assigned a location or a $self value. In that case tooling MUST require an explicit identity on the Schema Object and MUST NOT proceed with extraction, cross-document resolution, or standalone validation until one is supplied.¶

Find the Schema Object's location. Tooling MUST determine the JSON Pointer [RFC6901] from the Description's document root to the Schema Object, for example /components/schemas/TelemetryMessage.¶

Combine the two. The default identity is the base URI with that JSON Pointer appended as an [RFC3986] fragment, constructed deterministically as follows, in order:¶

1. Take each JSON Pointer reference-token (for example components, schemas, TelemetryMessage) as a Unicode string and encode it as [RFC3629] UTF-8 octets.¶

2. Apply [RFC6901] reference-token escaping to the token before percent-encoding: a literal ~ becomes ~0 and a literal / becomes ~1. Join the escaped tokens with / to form the JSON Pointer string.¶

3. Percent-encode the resulting pointer string for use as a URI fragment. Every octet not permitted literally in an [RFC3986] fragment production MUST be percent-encoded. This includes any literal % character, which becomes %25, so that the result cannot be misread as a percent-encoded triple. Percent-encoding MUST use uppercase hexadecimal digits, for example %2F and not %2f.¶

4. The base URI MUST be resolved according to the OAS base-URI rules before the fragment is appended. Any existing fragment on the base URI MUST be removed first.¶

The result has the form base-URI + # + percent-encoded-JSON-Pointer.¶

This construction MUST be deterministic and idempotent. Re-deriving the default identity for the same Schema Object location in the same Description MUST always produce the same byte sequence. Identity comparison is byte-exact unless the binding declares otherwise (Section 4.1).¶

For example, if the Description's base URI is https://example.com/api/openapi.yaml and the Schema Object is at /components/schemas/TelemetryMessage, the default identity is https://example.com/api/openapi.yaml#/components/schemas/TelemetryMessage. An explicit identity on the Schema Object always takes precedence over this default.¶

A Schema Object outside components.schemas exercises the escaping rules. Consider an inline Schema Object at the JSON request body of POST /orders/{orderId}, in a Description with the same base URI. Two of its reference-tokens contain characters that the two escaping steps treat differently:¶

A / inside a path template or a media type is part of the reference-token, not a pointer separator. Step 2 therefore escapes it as ~1. That ~1 then passes through step 3 unchanged, since ~ and digits are permitted literally in an [RFC3986] fragment. The braces of the path template are not permitted there, so step 3 percent-encodes them with uppercase hexadecimal digits. The resulting default identity is:¶

https://example.com/api/openapi.yaml#/paths/~1orders~1%7BorderId%7D/post/requestBody/content/application~1json/schema

Tooling APIs that process an encapsulated or offline Description MUST expose the selected base URI as an explicit input when it is not available from $self or a retrieval URI. A filesystem path MUST NOT be concatenated directly into the default identity. It MUST first be converted to the URI used by the tool's retrieval and base-URI model.¶

4.6. Materializing Defaults for Standalone Processing

A Schema Object embedded in an OpenAPI Description commonly omits $schema and its identity keyword. $schema is supplied by jsonSchemaDialect (Section 4.3) and the identity by Section 4.5. Both are conveniences that depend on context. A standalone validator for the dialect has no notion of jsonSchemaDialect and no notion of the Schema Object's position within a larger document.¶

Tooling that extracts a Schema Object from its containing Description in order to validate it, incorporate it elsewhere, or otherwise process it outside OAS context MUST first materialize both defaults as literal properties on the extracted document:¶

• $schema, set to the effective dialect determined per Section 4.3;¶

• the identity keyword, set to the Schema Object's own value if present, or otherwise to the value constructed per Section 4.5.¶

The extracted document MUST be self-describing and independently valid in its dialect without reference to the originating Description. Tooling MUST NOT hand an extracted Schema Object to a standalone validator with $schema or the identity keyword left absent on the assumption that OAS-level context will supply them.¶

A binding MAY declare further values that the extracted document would otherwise take from context (Section 4.1). That context is not always the OpenAPI Description. Where a dialect's own nesting rules let an inner declaration inherit a value from an enclosing one, extraction destroys that value just as thoroughly as extraction from a Description destroys jsonSchemaDialect. Tooling performing an extraction MUST materialize every such value, whichever context supplied it. The materialized value MUST be the one in effect at the declaration's position in the originating document.¶

Any materialized value MUST be deterministic for the same Description and JSON Pointer. Where a materialized value could collide with a declaration already present in the extracted document, tooling MUST reject the extraction. Tooling MUST NOT rename either declaration.¶

4.7. Reference Layer Separation

A Schema Object in a bound dialect is a self-contained schema resource, once classified as a Schema Object rather than a Reference Object (Section 4.2). Two reference layers coexist and do not mix:¶

• The OpenAPI reference layer: an outer OpenAPI $ref that targets a Schema Object as a whole, for example #/components/schemas/TelemetryMessage. This resolves per OAS [OAS], unchanged, at any position in the Description. That includes positions inside a Schema Object that has not itself adopted a bound dialect, such as an array wrapper's items: { "$ref": "#/components/schemas/Pet" }.¶

• The dialect's own reference layer: whatever referencing keywords the dialect defines, used within a Schema Object that has adopted that dialect. These resolve as the dialect specifies. That resolution need not resemble OAS reference resolution and need not be able to reach OAS component addresses at all.¶

Dialect selection is per schema-resource-root (Section 4.3). These layers are therefore scoped, not global. The dialect's rules apply only once a reference node is already inside that resource's own body. An ordinary OAS $ref pointing at a resource from outside it stays on the OpenAPI reference layer and is untouched.¶

Tooling MUST determine the reference layer before resolving a reference. At an OAS Schema Object position, a sibling $ref is an OAS reference and is resolved against the containing Description. After a resource root has adopted a bound dialect, a reference encountered inside its body is valid only where that dialect permits it. A reader MUST NOT recursively reinterpret an OAS reference target as dialect content until that target Schema Object has independently undergone dialect selection.¶

4.8. Resolving Cross-Document References

This section applies when the binding declares a cross-document mechanism (Section 4.1).¶

A Description registers a set of schema resources. The set comprises every Schema Object in a bound dialect that carries an explicit identity (Section 4.5). Tooling MUST attempt to resolve a cross-document reference in the following order, using the first source that satisfies it:¶

1. a registered identity within the Description;¶

2. a caller-supplied registry or cache mapping the reference URI to a previously retrieved schema resource, without performing network access;¶

3. network retrieval of the URI, over a secure transport such as HTTPS.¶

Network retrieval is OPTIONAL for a conforming implementation and MUST be disabled by default. Tooling MUST NOT attempt network retrieval unless it has been explicitly configured to allow it. When retrieval is disabled, not supported, or not enabled for the target host, tooling MUST fail with a diagnostic identifying the unresolved reference. Tooling MUST NOT silently skip the reference or substitute an empty definition.¶

When network retrieval is enabled, tooling MUST provide controls for allowed schemes and hosts, maximum document size, retrieval timeouts, redirect policy, caching, and cycle detection. Tooling MUST prevent cross-document resolution from becoming an SSRF or unrestricted local-file access primitive.¶

Identity comparison uses two related but distinct notions. Both are derived from an explicitly declared identity:¶

• Resource identity is the identity value exactly as declared, including any fragment it carries. It is the value used as the base URI for references resolved within that resource.¶

• Lookup key is the fragment-free form of a resource identity: the same absolute URI with any fragment removed. It is used only for matching a cross-document reference against registered resources.¶

Matching compares lookup keys. Tooling MUST strip any fragment from the reference value and from each registered identity, then compare the two byte-for-byte.¶

This comparison discards fragments. Two registered identities that share a fragment-free prefix therefore reduce to the same lookup key, even though they remain distinct resource identities. Tooling MUST reject a Description in which more than one registered identity reduces to the same lookup key. Tooling MUST reject a Description that registers the same resource identity more than once.¶

A schema resource retrieved from outside the Description need not itself be an OpenAPI Description or a JSON Schema document. OAS requires every document in an OpenAPI Description to have an OpenAPI Object or a Schema Object at its root ([OAS], "OpenAPI Description Structure"), and treats other roots as implementation-defined. Such a retrieved resource is therefore not part of the OAD. It is an input to dialect processing, obtained and interpreted under this section and the dialect's own rules, and OAS document-structure requirements do not apply to it. Tooling MUST NOT attempt to parse it as an OpenAPI document, and MUST NOT expose its contents at OAS component addresses.¶

4.9. Type Identity and Scope

A Description can hold many schema resources. These are every components.schemas entry, and every inline Schema Object at a request body, response, parameter, or header position. Each is a separate resource with its own identity (Section 4.5) and its own scope for whatever names its dialect gives to types.¶

Type identity is outside the scope of OAS, which places "class hierarchies" in the application form of the data, "beyond the scope of this specification" ([OAS], "Parsing and Serializing"). A binding supplies it, as it supplies the other parameters of Section 4.1.¶

Scope becomes observable once a consumer treats the Description as a single type space. A code generator does this when it emits one module for the Description. Two resources can carry the same type name without either being wrong, where the binding's rules place them in different scopes. A consumer that flattens them produces a collision that exists nowhere in the Description.¶

A dialect binding MUST declare what names a type in its dialect and how a resource's scope for those names is determined (Section 4.1). A dialect MAY derive scope from the schema resource, and it MAY take scope from a declaration the author writes inside the schema. The binding states which.¶

Tooling that aggregates the Schema Objects of a Description into one type space MUST preserve the scopes the binding's rules assign. It MUST NOT introduce a name collision that those rules do not already produce. It MUST NOT resolve a collision by renaming a declaration or by synthesizing a scope. Where the binding's rules place two differing declarations in one scope, tooling MUST report a diagnostic and MUST NOT choose between them.¶

4.10. Schema Inspection for Non-JSON Serializations

Some media types are not self-describing as to type. These include application/x-www-form-urlencoded, multipart media types, and text/plain values in Parameter, Header, and Encoding Objects. For those, OAS requires implementations to inspect the schema to determine each value's type before parsing or serializing it ([OAS], "Parsing and Serializing"). OAS states that procedure in terms of the OAS dialect's own keywords, following $ref and allOf. That procedure does not apply to a Schema Object in another dialect, whose keywords need not exist or need not mean the same thing.¶

A binding MUST declare an equivalent type-determination procedure (Section 4.1) that, given a starting-point Schema Object in its dialect, yields for each named or positioned value either a determined JSON data type or an explicit "undetermined" result. The procedure MUST be deterministic and MUST NOT depend on instance data.¶

Tooling MUST use the binding's procedure, and MUST NOT fall back to the OAS procedure, whenever a Schema Object in a bound dialect appears in:¶

• a Media Type Object's schema or itemSchema for a non-JSON media type;¶

• a Parameter or Header Object using schema rather than content;¶

• a value correlated with an Encoding Object through encoding, prefixEncoding, or itemEncoding.¶

Where the procedure yields "undetermined", tooling MUST report a diagnostic identifying the value and MUST NOT guess a type. Where a binding declares no such procedure, its dialect MUST NOT be used at the positions listed above, and tooling MUST reject a Description that does so.¶

The itemSchema field applies its Schema Object to each item of a sequential media type independently ([OAS]). A Schema Object in a bound dialect is valid at an itemSchema position on the same terms as at a schema position. It is a schema-resource root (Section 4.3), and it describes one item, not the sequence.¶

4.11. Dialect-Defined Body Encodings

A dialect may define a wire encoding for the data it describes, and not only a vocabulary for describing that data. Where it does, a message body in that encoding is decoded from the schema by the dialect's own rules.¶

A binding MUST declare the media types whose bodies its dialect encodes (Section 4.1). A binding MAY declare none, in which case bodies are encoded per their media type independently of the dialect, and this section does not apply.¶

Section 4.10 does not apply to a body of a declared data media type. That procedure exists so that OAS can construct and parse form, multipart, and text values, which carry no type information of their own. A body the dialect encodes carries whatever the dialect's encoding provides, and the dialect decodes it as a whole. Tooling MUST NOT apply the type-determination procedure to such a body.¶

For each declared media type, a binding MUST state whether the encoding carries the schema needed to decode the body:¶

• Where the encoding carries that schema, tooling MUST decode the body using the schema the body carries. Tooling MUST NOT decode the body using the Schema Object in place of the schema on the wire. The Schema Object states what the Description expects, and tooling MUST report a diagnostic where the two disagree in a way the dialect does not reconcile.¶

• Where the encoding does not carry that schema, the Schema Object is the schema the body was encoded against. Tooling MUST NOT decode a body whose encoding schema it cannot establish, and MUST NOT substitute a different schema on the assumption that the two are compatible.¶

A Schema Object whose dialect encodes the body is part of the wire contract. Editing it changes what is on the wire. Where the dialect defines its own rule for reading data written against a different version of a schema, the binding MUST state how that rule relates to a change made in the Description.¶

A schema carried in a body is untrusted input. Tooling MUST validate it before use and MUST apply the limits of Section 8 to it.¶

4.12. Validating the Description Itself

The OpenAPI Initiative publishes two JSON Schemas per OAS minor version for validating OpenAPI documents. The schema iteration deliberately does not validate Schema Objects, since it makes no assumption about the dialect in use. The schema-base iteration does validate them, and constrains jsonSchemaDialect and $schema to the OAS dialect.¶

A Description that uses any bound dialect is therefore validatable against the schema iteration and is NOT validatable against the schema-base iteration. A schema-base failure caused solely by a bound dialect URI is expected and is not a defect in the Description. Tooling that validates Descriptions MUST NOT treat schema-base as the authoritative structural check for a Description containing bound-dialect Schema Objects. Such tooling SHOULD validate against the schema iteration together with the dialect's own meta-schema applied to each Schema Object.¶

5.1. JSON Structure Binding Parameters

5.2. JSON Structure Meta-Schema URIs

The following URIs identify the JSON Structure dialects:¶

The extended meta-schema is RECOMMENDED as the document default for API design. It makes $import available while keeping validation and composition opt-in.¶

JSON Structure Core permits a custom meta-schema to extend one of these by giving the derived meta-schema its own $id and using $import to pull in the foundational meta-schema's definitions ([JSTRUCT-CORE], "Meta-Schemas"). Such a URI is subject to the derived-URI rule of Section 4.4. Configuring tooling to recognize one typically means resolving the meta-schema document once, offline, and confirming that it imports one of the three canonical meta-schemas. A custom meta-schema MUST document which add-ins it activates by default and which it only offers.¶

5.3. Materializing name

Beyond the $schema and $id materialization required by Section 4.6, every JSON Structure schema resource root MUST carry a name [JSTRUCT-CORE]. This requirement is unconditional. It applies to a root that declares type at the top level, to a root that uses $root to designate a type defined under its own definitions, and to a root that only holds definitions and is never itself instantiated.¶

Within an OpenAPI Description the requirement applies to every components.schemas entry. It also applies to an anonymous inline Schema Object at a request body, response, or parameter position, once that object is extracted for standalone validation. Tooling performing such an extraction MUST materialize a name when the Schema Object does not supply one, for example by deriving it from the Schema Object's JSON Pointer location (Section 4.5).¶

The materialized name MUST be a valid JSON Structure identifier and MUST be stable for the same Description and JSON Pointer. If the derived name collides with a declared name in the extracted document, tooling MUST reject the extraction and MUST NOT rename either declaration. The OpenAPI component key remains the OAS address. It does not implicitly replace an explicit JSON Structure name. A further uniqueness requirement applies across the schema resources of one Description when they are aggregated (Section 5.7).¶

A JSON Pointer cannot be used as a name unchanged. JSON Structure restricts identifiers to [A-Za-z_][A-Za-z0-9_]* ([JSTRUCT-CORE]), which excludes the / and ~ a pointer is built from. Reproducing the whole pointer is also unnecessary. $id already records the exact location, so name only has to be a stable, readable identifier that is unique within the extracted document. Tooling SHOULD derive one in this order:¶

1. If the Schema Object is a components.schemas entry whose component key is already a valid JSON Structure identifier, use the component key. OAS constrains component keys to ^[a-zA-Z0-9\.\-_]+$ ([OAS]), so most keys in existing Descriptions qualify unchanged.¶

2. Otherwise, derive the name from the identifying parts of the position. For a request body or response, those are the path template, the HTTP method, and the role. Do not use every reference-token of the pointer.¶

3. If neither produces a valid identifier, reject the extraction and require an explicit name.¶

Consider a Description that selects the JSON Structure Core dialect for the whole document and carries an anonymous inline Schema Object at a request body position:¶

openapi: 3.2.0
$self: https://example.com/api/openapi.yaml
jsonSchemaDialect: https://json-structure.org/meta/core/v0/#
paths:
  /orders:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: uuid
                total:
                  type: decimal

The Schema Object declares no $schema, no $id, and no name. None of the three is needed while it is read in place. The dialect comes from jsonSchemaDialect, and the position within the Description supplies the address. Extraction for standalone validation removes both, so all three MUST be materialized:¶

$schema: https://json-structure.org/meta/core/v0/#
$id: https://example.com/api/openapi.yaml#/paths/~1orders/post/requestBody/content/application~1json/schema
name: OrdersPostRequestBody
type: object
properties:
  orderId:
    type: uuid
  total:
    type: decimal

$schema is the effective dialect inherited from jsonSchemaDialect, and $id is the default identity constructed per Section 4.5.¶

name comes from step 2. Three parts of the position identify it, and each contributes one segment:¶

Each segment drops the characters outside [A-Za-z0-9_] and capitalizes its first letter. The segments are then concatenated in that order, giving OrdersPostRequestBody. The remaining reference-tokens of the pointer, paths, content, application/json, and schema, contribute nothing. They are structural, not identifying.¶

Distinct positions can still derive the same name. Two media types under one operation, application/json and application/xml at POST /orders, occupy different pointers but share path, method, and role. So do the path templates /orders and /Orders, which differ in the Description but not after the leading character is capitalized. Tooling MAY append further distinguishing segments, such as the media type, provided the result stays deterministic. Where it cannot, it MUST reject the extraction and MUST NOT emit the same name twice. The author resolves the conflict by declaring an explicit name on one of the Schema Objects.¶

A components.schemas entry usually needs none of this. An entry stored under TelemetryMessage derives TelemetryMessage by step 1. The component key remains the OAS address and not the JSON Structure name. An explicit name on the Schema Object therefore still takes precedence, and the two need not be equal.¶

5.4. Type System

Within a JSON Structure Schema Object, keywords are interpreted per JSON Structure [JSTRUCT-CORE], which defines the full type system. That type system covers primitive and precise numeric types, the object/array/set/map/tuple/choice compound types and their member, item, and value declarations, nullability via type union, and inheritance via abstract and $extends. These JSON Structure constructs replace the correspondingly named OAS and JSON Schema constructs, which do not apply in this dialect.¶

5.5. JSON Structure Reference Layer

The two reference layers of Section 4.7 are instantiated for JSON Structure as follows. The OpenAPI layer is unchanged. The dialect layer is $ref, $extends, and $import used within a Schema Object that has adopted a JSON Structure dialect. $ref and $extends address named types under the schema's own #/definitions/.... Cross-document reuse uses the JSONStructureImport add-in [JSTRUCT-IMPORT] instead (Section 5.6). An inner $ref MUST NOT be used to reach a components.schemas entry.¶

After a resource root has adopted a JSON Structure dialect, a $ref encountered inside its body is valid only where JSON Structure Core permits it: as the value of type, or through the corresponding $extends and import forms.¶

An OAS or JSON Schema $ref is a general-purpose node-reference mechanism. It is a sibling property that can stand in for an entire Schema Object at any position, as in { "$ref": "#/components/schemas/Foo" }. JSON Structure has no equivalent. Its $ref exists only to name the type referenced by a type attribute. $ref MUST therefore appear only as the value of a type attribute, as in { "type": { "$ref": "#/definitions/Foo" } } ([JSTRUCT-CORE]). It MUST NOT be used as a sibling property standing in for a whole schema.¶

{
  "type": "array",
  "items": { "$ref": "#/components/schemas/Pet" }
}

{
  "type": "array",
  "items": { "type": { "$ref": "#/definitions/Pet" } },
  "definitions": {
    "Pet": {
      "type": "object",
      "name": "Pet",
      "properties": {
        "name": { "type": "string" }
      },
      "required": ["name"]
    }
  }
}

5.6. Cross-Schema Reuse with $import and $importdefs

$ref and $extends are document-local. A JSON Structure Schema Object cannot reach a type defined in another components.schemas entry through them. Reuse across entries, and across documents, uses the JSONStructureImport add-in [JSTRUCT-IMPORT]. That add-in is active by default under the extended and validation meta-schemas. It defines the $import and $importdefs keywords, their copy-not-link semantics, definition shadowing, import error handling, and cycle rejection.¶

$import and $importdefs are this binding's cross-document mechanism (Section 4.1), and their values MUST be absolute URIs per [JSTRUCT-IMPORT]. This binding does not relax that requirement and does not introduce relative import URIs for use inside an OpenAPI Description. A JSON Structure Schema Object with a relative $import or $importdefs value is non-conforming. Tooling MUST reject it and MUST NOT resolve it against the importing resource's base URI.¶

Resolution follows Section 4.8 unchanged: an in-Description $id match first, then a caller-supplied registry or cache, then optional and explicitly enabled network retrieval. Resource identity is the declared $id. The lookup key is that value with any fragment removed. A JSON Structure Schema Object that is to be importable therefore MUST declare an explicit $id (Section 4.5). A default-constructed $id is never used for import matching.¶

Once a resource is obtained, tooling validates that it is a JSON Structure schema and copies its definitions into the designated namespace. It does so identically whether the resource came from the Description, a cache, or the network. A resource obtained from outside the Description is not part of the OAD (Section 4.8). A single canonical type library can therefore be shared across many APIs without itself being an OpenAPI document. Import errors, deduplication, and cycle rejection follow [JSTRUCT-IMPORT] unchanged. An importing entry MUST additionally activate, through its meta-schema or its own $uses, any add-ins used by the definitions it imports.¶

5.7. Namespaces Across Schema Resources

This section supplies the type naming and scope declaration required by Section 4.9. A JSON Structure type is named by name, and a schema resource's scope is its root namespace ([JSTRUCT-CORE]).¶

Two entries of one Description can therefore each declare a type named Pet without either being wrong. Section 5.5.1 makes that a routine outcome. A type needed at a nested properties, items, or choices position has to be copied into the containing resource's own definitions, since that position cannot carry an OAS $ref.¶

The aggregate required by Section 4.9 is a JSON Structure document whose root definitions carries one namespace per schema resource, named by that resource's name (Section 5.3). The resource's root type and everything under its own definitions, nested namespaces included, are placed in that namespace unchanged except for pointer rewriting. A document-local $ref, $extends, or $root that addressed #/definitions/X within the resource MUST be rewritten to address X under the resource's namespace. Definitions that $import or $importdefs copied into a resource (Section 5.6) are already part of that resource's namespace hierarchy and move with it.¶

The namespaces are keyed on name. A name MUST therefore be unique across the schema resources of one Description for that Description to be aggregatable. OAS component keys are unique by construction, and step 1 of Section 5.3 carries that uniqueness into the derived names. A duplicate can only come from an explicit name that repeats another resource's. Tooling MUST reject such a Description when aggregating.¶

The aggregate is a type library, not an instance schema. It declares no type and no $root of its own. It does not replace the individual resources, each of which remains addressable by its own $id (Section 4.5).¶

Consider a Description with a Pet entry and a PetListResponse entry that needs a pet type at a nested items position:¶

components:
  schemas:
    Pet:
      name: Pet
      type: object
      properties:
        id: { type: uuid }
        name: { type: string }
      required: [id, name]
    PetListResponse:
      name: PetListResponse
      type: object
      properties:
        pets:
          type: array
          items:
            type: { $ref: "#/definitions/Pet" }
      required: [pets]
      definitions:
        Pet:
          name: Pet
          type: object
          properties:
            id: { type: uuid }
            name: { type: string }
            tags:
              type: set
              items: { type: string }
          required: [id, name]

The two Pet declarations are different types. The nested one carries tags and the component entry does not. Each resource validates on its own. Aggregated, they occupy separate namespaces, and the inner $ref is rewritten to match:¶

$schema: https://json-structure.org/meta/core/v0/#
$id: https://api.example.com/openapi.yaml#types
name: PetstoreTypes
definitions:
  Pet:
    Pet:
      name: Pet
      type: object
      properties:
        id: { type: uuid }
        name: { type: string }
      required: [id, name]
  PetListResponse:
    PetListResponse:
      name: PetListResponse
      type: object
      properties:
        pets:
          type: array
          items:
            type: { $ref: "#/definitions/PetListResponse/Pet" }
      required: [pets]
    Pet:
      name: Pet
      type: object
      properties:
        id: { type: uuid }
        name: { type: string }
        tags:
          type: set
          items: { type: string }
      required: [id, name]

The $id and name at the aggregate root are assigned by the aggregating tool. This document does not prescribe their form. How a namespace is then rendered in a target language is likewise outside the scope of this document, whether as a package, a module, a nested class, or a name prefix. What is required is that the two Pet declarations stay distinguishable at the schema level, so that the choice remains available.¶

An author who wants one Pet rather than two says so in the Description, by giving the shared type its own resource and pulling it in with $import or $importdefs (Section 5.6) instead of copying it. The import names the namespace the copy lands in, so the scoping is the author's rather than the aggregating tool's.¶

5.8. Activating Add-ins with $uses

Under the extended meta-schema, non-Core add-ins are offered but not active. A schema activates them through $uses, an array of add-in tokens declared at the schema root. Under the validation meta-schema, all add-ins are active by default.¶

Following the convention established by the add-in specifications themselves [JSTRUCT-UNITS] [JSTRUCT-VALIDATION] [JSTRUCT-COMPOSITION], $uses is placed at the root of the JSON Structure schema document to activate add-ins offered by that document's own $schema meta-schema. Tooling conforming to this binding MUST support $uses in that position.¶

This meta-schema-level usage is distinct from the document-instance $offers and $uses mechanism JSON Structure Core also defines. There, a schema document advertises its own custom add-in types through $offers, and a separate JSON instance document that conforms to that schema selects among them with its own top-level $uses [JSTRUCT-CORE]. The two share a keyword name but operate in different scopes. This section's $uses selects add-ins that the schema's own meta-schema offers to it. A JSON Structure Schema Object embedded in an OpenAPI Description MAY additionally use $offers to advertise custom add-in types to instance documents. Doing so has no effect on this section's meta-schema-level $uses.¶

A custom meta-schema recognized under Section 4.4 MUST explicitly document which add-ins it activates by default and which it only offers for opt-in through $uses. "All add-ins" is not a well-defined active set without a specific meta-schema to enumerate it against. Tooling MUST NOT assume that a custom meta-schema's active and offered sets mirror those of the canonical meta-schema it extends.¶

For example, JSONStructureUnits [JSTRUCT-UNITS] is offered, but not active, under the extended meta-schema. A schema that wants to annotate numeric properties with unit, ucumUnit, and symbol MUST list it in $uses:¶

components:
  schemas:
    Measurement:
      $schema: https://json-structure.org/meta/extended/v0/#
      $uses:
        - JSONStructureUnits
      $id: https://api.example.com/schemas/measurement
      name: Measurement
      type: object
      properties:
        temperature:
          type: double
          ucumUnit: "Cel"
          symbol: "°C"

Omitting JSONStructureUnits from $uses while still using unit, ucumUnit, or symbol leaves those keywords unrecognized under the extended meta-schema. Tooling MUST treat them as unknown properties in that case, and MUST NOT silently apply JSONStructureUnits semantics. Under the validation meta-schema, JSONStructureUnits is active by default and $uses is not required to enable it.¶

5.9. Code Generation and Runtime Validation

Processing a JSON Structure Schema Object separates memory layout from constraint checking:¶

Code generation:

The generated in-memory type SHOULD be derived only from the JSON Structure Core structural keywords: type, name, properties, items, values, tuple, choices, selector, abstract, $extends, required, additionalProperties, and the precision, scale, and maxLength storage constraints. Constraint keywords contributed by the JSONStructureValidation [JSTRUCT-VALIDATION] and JSONStructureConditionalComposition [JSTRUCT-COMPOSITION] add-ins are runtime validation rules and SHOULD NOT change the generated type.¶

Runtime validation:

The selected meta-schema determines whether those add-ins are active. They are opt-in through $uses under the extended meta-schema, and active by default under the validation meta-schema. Conditional-composition keywords are evaluated as boolean value validation (Section 5.4.3), never as structural composition.¶

This separation lets a generator produce a deterministic memory layout from Core keywords while a gateway or server enforces the full validation and composition rules against the same schema.¶

5.10. Data Media Types and JSON Representation

This section supplies the data media types declaration required by Section 4.11. The declaration is none.¶

JSON Structure defines no message framing. It has no container format, no schema fingerprint, and no media type of its own. A body described by a JSON Structure Schema Object is carried in whatever media type its Media Type Object names, and this binding does not change how that media type frames the body. No schema travels with the body, so the Schema Object is the only schema, and the schema-on-the-wire requirements of Section 4.11 do not apply.¶

JSON Structure does fix how several values appear inside a JSON body. These representations cannot be inferred from the value, and a consumer that reads a JSON Structure Schema Object as though it were an OAS-dialect schema gets them wrong ([JSTRUCT-CORE]):¶

• int64, uint64, int128, uint128, and decimal appear as JSON strings. Interoperable JSON numbers span -2^53 to 2^53-1, and these types exceed that range.¶

• binary appears as a string, Base64 by default. contentEncoding selects another alphabet, and contentCompression names a compression applied before the encoding.¶

• date, datetime, time, and duration appear as strings in the corresponding RFC 3339 productions.¶

Tooling MUST apply these representations when it reads or writes a body of application/json, or of any media type whose payload is JSON. Tooling MUST NOT emit an int64 as a JSON number. Tooling MUST NOT surface a quoted int64 to an application as a string-typed value.¶

JSON Structure encoding specifications that map the type system onto a non-JSON wire format are separate specifications. Each is a separate dialect binding and declares its own data media types under Section 4.1. This document does not cover them.¶

5.11. Type Determination for Non-JSON Serializations

This section supplies the type-determination procedure required by Section 4.10.¶

Given a starting-point JSON Structure Schema Object, tooling MUST determine the type of a value as follows. All steps operate on the schema alone.¶

1. Resolve the starting point to a type definition. Follow $root from a resource root, and follow a type whose value is a $ref to the named type it designates. Follow $extends to incorporate inherited members. Imported namespaces are resolved first (Section 5.6), so a $ref into an imported namespace is followed the same way.¶

2. Locate the value: a named member under properties, a positional element under tuple, the item type under items, or the value type under values.¶

3. The located declaration's type gives the JSON data type directly. JSON Structure requires type on every type declaration, so this step does not fail for a valid schema.¶

4. Map the JSON Structure type to a JSON data type. The types int64, uint64, int128, uint128, and decimal map to string. JSON Structure represents them as strings, since their ranges exceed the interoperable range of a JSON number ([JSTRUCT-CORE]). The remaining numeric types map to number: number, integer, int8, uint8, int16, uint16, int32, uint32, float8, float, and double. string, datetime, date, time, duration, uuid, uri, binary, and jsonpointer map to string. boolean maps to boolean. object, map, and choice map to object. array, set, and tuple map to array. null maps to null.¶

   Tooling MUST NOT map the large-integer and decimal types to number. Doing so produces an unquoted numeric literal in a form field, path segment, query parameter, or header value, which loses precision and does not match the JSON Structure representation of the same value.¶

5. A type union yields "undetermined" unless exactly one member of the union remains after removing null, in which case that member's mapping applies. A choice used at a position requiring a scalar serialization yields "undetermined".¶

JSON Structure requires an explicit type everywhere and has no keyword that makes a declaration apply conditionally to the data. This procedure therefore never needs to inspect instance data, and never has to reconcile competing type assertions the way the OAS-dialect procedure does.¶

Values that map to object or array are serialized as application/json by default in an Encoding Object, exactly as for the OAS dialect. A binary value carries no contentEncoding and is serialized as application/octet-stream unless an Encoding Object's contentType says otherwise.¶

6.1. A Single JSON Structure Schema Object

The following components.schemas entry is a JSON Structure Schema Object. Its $schema selects the JSON Structure Core dialect, so type, properties, and the primitive type names are interpreted per JSON Structure and not per the OAS dialect. It is referenced from elsewhere in the OpenAPI Description with an ordinary OpenAPI $ref to #/components/schemas/TelemetryMessage.¶

components:
  schemas:
    TelemetryMessage:
      $schema: https://json-structure.org/meta/core/v0/#
      $id: https://api.example.com/schemas/telemetry-message
      name: TelemetryMessage
      type: object
      properties:
        messageId:
          type: uuid
        timestamp:
          type: datetime
        sensorId:
          type: string
        reading:
          type: double

6.2. Using jsonSchemaDialect as the Document Default

An OpenAPI Object MAY set jsonSchemaDialect once, so that Schema Objects need not repeat $schema individually (Section 4.3). Here the same TelemetryMessage schema omits both its own $schema and its own $id. The document default supplies the dialect, and the default-construction rule (Section 4.5) supplies the identifier.¶

openapi: 3.1.0
jsonSchemaDialect: https://json-structure.org/meta/core/v0/#
info:
  title: Telemetry API
  version: "1.0.0"
components:
  schemas:
    TelemetryMessage:
      name: TelemetryMessage
      type: object
      properties:
        messageId:
          type: uuid
        reading:
          type: double

Assuming this Description is retrieved from https://api.example.com/openapi.yaml, tooling that extracts TelemetryMessage for standalone validation (Section 4.6) MUST produce:¶

$schema: https://json-structure.org/meta/core/v0/#
$id: "https://api.example.com/openapi.yaml\
  #/components/schemas/TelemetryMessage"
name: TelemetryMessage
type: object
properties:
  messageId:
    type: uuid
  reading:
    type: double

A Schema Object that carries its own $schema or $id, as in Section 6.1, overrides the corresponding default. The two defaults compose independently per keyword. They are not an all-or-nothing pair.¶

6.3. Cross-Schema Reuse with $import

Here TelemetryMessage imports the sibling CommonTypes library by its $id into the Common namespace, extends the imported BaseMessage, and references the imported GeoPoint. Both entries carry an $id, so the import resolves within the Description without any network access.¶

components:
  schemas:
    CommonTypes:
      $schema: https://json-structure.org/meta/core/v0/#
      $id: https://api.example.com/schemas/common
      name: CommonTypes
      definitions:
        BaseMessage:
          name: BaseMessage
          abstract: true
          type: object
          properties:
            messageId: { type: uuid }
            timestamp: { type: datetime }
        GeoPoint:
          name: GeoPoint
          type: object
          properties:
            lat: { type: double }
            long: { type: double }
    TelemetryMessage:
      $schema: https://json-structure.org/meta/extended/v0/#
      $id: https://api.example.com/schemas/telemetry
      name: TelemetryMessage
      $root: "#/definitions/TelemetryMessage"
      definitions:
        Common:
          $importdefs: https://api.example.com/schemas/common
        TelemetryMessage:
          name: TelemetryMessage
          type: object
          $extends: "#/definitions/Common/BaseMessage"
          properties:
            sensorId: { type: string }
            reading: { type: double }
            location:
              type: { $ref: "#/definitions/Common/GeoPoint" }

6.4. Importing an External Type Library

When the import URI matches no $id in the Description, it denotes an external schema resource. Here OrderEvent imports an external people.json type library by its absolute URI into the People namespace and uses the imported Person type. The external document is a self-contained JSON Structure schema and need not be an OpenAPI Description.¶

components:
  schemas:
    OrderEvent:
      $schema: https://json-structure.org/meta/extended/v0/#
      $id: https://api.example.com/schemas/order-event
      name: OrderEvent
      type: object
      properties:
        customer:
          type: { $ref: "#/definitions/People/Person" }
      definitions:
        People:
          $import: https://types.example.com/people.json