Merging remote contexts

Multiple $ref (e.g. in allOf) each correspond to a remote context. By the reflection rule above, the schema's own @context MUST list those remote contexts as an array, in the same order as the allOf members, so the schema stays usable as a context without further processing. A JSON-LD processor then resolves that array in order, later entries overriding earlier ones - duplicate context terms are overridden using a most-recently-defined-wins mechanism ([[JSON-LD11]] §4.1.5). The schema MAY append its own context object as the last array entry to override an inherited term. The single-context @import keyword is an alternative only when exactly one remote context is wrapped and locally modified (it cannot contain a nested @import), so the array form is used for the multi-$ref case.

oneOf / anyOf. The remote contexts of oneOf / anyOf branches MAY also be reflected into the @context, but they MUST NOT conflict at the root - they MUST NOT map the same keyword to different IRIs there. A JSON-LD processor merges all listed contexts (most-recently-wins) and has no notion of which branch a given instance matched, so a root-level conflict would be decided by context order rather than by the branch the data conforms to.

Where branches genuinely need different mappings for the same keyword, do not place them at the root; scope them so each mapping applies only where its branch applies, using JSON-LD scoped contexts:

• Type-scoped contexts when the branches are distinguished by @type. The scoped @context is attached to the term used as the type value and is activated only for nodes carrying that @type:

  {
    "@context": {
      "Sensor": { "@id": "ex:Sensor", "@context": { "reading": "ex:temperature" } },
      "Gauge":  { "@id": "ex:Gauge",  "@context": { "reading": "ex:pressure" } }
    }
  }
  

Here { "@type": "Sensor", "reading": 21 } maps reading to ex:temperature, while { "@type": "Gauge", "reading": 3 } maps the same keyword to ex:pressure.

• Property-scoped contexts when the conflicting keyword appears under different parent properties. The mapping is attached to the parent property's term (its @context) and applies only within that property's value, so the same keyword can resolve differently under different parents.

Propagation (@propagate). A $ref inside a type: object property is reflected as a property-scoped context, which by default propagates into the whole subtree rooted at that property ("By default ... contexts propagate across node objects, other than for type-scoped contexts, which default to false"). Where a referenced context should apply only to the immediate node, the schema MUST set "@propagate": false on that scoped context. Contexts combined in a single array MUST share the same @propagate value.

Protected terms (@protected). A schema MAY mark terms @protected to prevent later contexts from silently redefining them. When contexts are combined via allOf, redefining a protected term to a different IRI is an error unless the new definition is identical; property-scoped contexts are exempt and may override protected terms within their subtree. Relying on @protected therefore constrains which schemas a schema can be combined with.

Independent references and base URIs. A JSON Schema $ref and a JSON-LD @context entry are independent references: they MAY point to the same document (the typical OO-LD case, where one document is both a schema and a context) or to different documents - for example a plain JSON Schema referenced via $ref together with a separate remote @context that supplies the semantics. Relative references resolve against the schema's $id (the JSON Schema base URI) and, on the JSON-LD side, against @base / the retrieval URL; these base URIs SHOULD be aligned so a relative reference resolves to the same absolute URL under both. $id MUST NOT contain a non-empty fragment ([[JSONSCHEMA]] §8.2.1).

Merge and override model

JSON Schema's validation algebra is purely conjunctive: allOf requires an instance to satisfy every subschema, and the specification defines no merge of the subschemas' keyword values ([[JSONSCHEMA]] §10.2.1.1). Several consumers nonetheless require a single [=resolved schema=] view rather than a conjunction: a UI generator needs exactly one title per field, a code generator flattens an inheritance chain into one class, and an OO-LD preprocessor must produce one @context.

When such a merge is required, OO-LD resolves the allOf chain by applying JSON Merge Patch ([[RFC7396]]) semantics: keyed by object member, most-recently-defined (most-derived) wins, and a null value removes a key. For the @context this coincides with JSON-LD's own override rule. For assertion-bearing keywords the resolved view additionally honors narrow-only composition: a derived schema MAY restrict a constraint but MUST NOT relax it, matching how code generators let a subclass tighten - never loosen - a superclass property's validation.

This single model governs every place OO-LD collapses composition into a resolved value: single-valued annotations such as title and x-oold-multilang-title resolve most-derived-wins, constraints resolve narrow-only, and additive maps merge by key. A preprocessor applying it produces exactly the view that UI and code generators already compute, so no separate "resolved schema" format is needed.

Referencing the schema with $schema

In standard JSON Schema, $schema identifies the dialect (meta-schema), not the schema an instance validates against ([[JSONSCHEMA]] §8.1.1); JSON Schema does not define an in-band way for an instance to point at its own schema. OO-LD therefore uses $schema on instances as a convention: standard JSON Schema validators treat it as ordinary data, while editors (VS Code, JetBrains, JSON Schema Store) and CI checks (e.g. check-json-schema-meta) honor it. Where the instance is served over HTTP, the standards-conformant alternative is the describedby link relation ([[JSONSCHEMA]] §9.5.1.1), optionally with the profile media-type parameter ([[RFC6906]]):

An OO-LD-aware tool determines an instance's schema in the following order:

1. the $schema value, if present;
2. otherwise, the URL given under @context, if the referenced document declares itself to be an OO-LD schema;
3. otherwise, an inline @type (see below) - but only when at least one of the type IRIs resolves to an OO-LD schema.

An implementation MAY additionally maintain a registry mapping rdf:type IRIs to OO-LD schemas to resolve case 3, but such a registry MUST NOT be assumed to exist on the consuming side - so exports must be self-sufficient (see below).

Because an instance carries $schema and @context as ordinary members, an OO-LD schema that closes its objects with additionalProperties: false or unevaluatedProperties: false MUST permit these two members, or conforming instances would fail validation.

@context already provides a JSON-LD-native link to the schema (resolution case 2 above), so $schema is kept primarily for compatibility with the widespread editor and CI convention, not as a second authoritative mechanism. JSON Schema deliberately does not standardize $schema on instances, partly over a self-validation concern: a consumer SHOULD NOT blindly trust the schema an instance declares for itself (a crafted instance could point at a permissive schema) and remains responsible for validating against a schema it trusts.

Identity (@id)

An instance that represents an identifiable entity is identified by an @id - the IRI of that entity. This is the JSON-LD node identifier, distinct from $schema / @context (which identify the schema) and from the schema's own $id / x-oold-uuid. Without an @id the entity is an anonymous blank node and cannot be referenced (for example as the target of an x-oold-range or @reverse relation).

To keep instance keys variable-name-friendly, schemas SHOULD expose @id through an aliased id property (as with type -> @type):

An implementation MAY use a non-IRI identifier internally, but when it exports an identifiable entity (to JSON-LD / RDF) it MUST assign an @id (or the aliased id). The @id SHOULD be resolvable, and it is RECOMMENDED to mint it from an autogenerated UUID - mirroring the schema's x-oold-uuid - e.g. https://example.org/a1b2c3d4-1234-....

Embedded value objects that have no independent identity (for example an Address embedded in an Organization) MAY omit @id and remain blank nodes.

Carrying the semantic type

The type and semantics of an instance are owned by the OO-LD schema it references; an instance is therefore not required to carry an inline type, and a schema version may remap to different ontology terms without rewriting existing data.

A schema declares the rdf:type(s) of its instances with the x-oold-instance-rdf-type keyword (always a list of IRIs, e.g. ["schema:Person"]):

These types live in the schema, not in the instance data, so a JSON-LD-only processor - which sees only the instance and its @context - cannot derive them. Therefore, when OO-LD tooling exports an instance (to JSON-LD / RDF), it MUST materialize the declared rdf:type(s) as an @type on the instance, so that the type reaches RDF without access to the schema or to a type registry.

Alternatively, an instance MAY carry the type inline as a type property (self-describing data). The schema maps the type term to the JSON-LD keyword @type with a simple alias and gives it a default; the value MAY be a single IRI or a list of IRIs, and this property named type is distinct from the JSON Schema type keyword. No @type: @id coercion is needed because JSON-LD already interprets @type values as IRIs:

If an inline type is present it MUST be consistent with the schema's x-oold-instance-rdf-type. Note that @type alone lets a consumer locate the schema (case 3 above) only when one of the type IRIs resolves to an OO-LD schema.

Under composition, x-oold-instance-rdf-type follows the same most-derived-wins rule as the rest of the schema (see ): the nearest declaration in the allOf chain is authoritative and REPLACES - it does not append to - a base class's value. Superclass types are recoverable by ontology inference (rdfs:subClassOf) and so need not be materialized; a schema that wants a supertype carried in the data lists it explicitly (e.g. ["schema:Researcher", "schema:Person"]).

Property value forms

A property whose value denotes another resource takes one of three forms in an instance, distinguished by the shape of the JSON value, and each projects to RDF differently:

• a literal - a bare scalar (string, number, boolean), e.g. "Mainstreet 1";
• a reference - an object carrying an @id (or its id alias), e.g. { "id": "https://example.org/PlaceA" }, denoting an independent entity by IRI;
• an embedded object - a nested object with its own properties and no independent identity, e.g. { "type": "PostalAddress", "streetAddress": "..." }, which becomes a blank node.

A single @context term cannot interpret a bare string as both a literal and an IRI: @type: "@id" coerces every string value to an IRI (so free text becomes an - often invalid, then dropped - IRI), while a plain term keeps every string a literal. A property whose range is references only therefore uses @type: "@id" and MAY be written as a bare IRI string; a property whose range includes free text MUST NOT use @type: "@id".

For a property whose range mixes free text with references and/or embedded objects (for example Text | PostalAddress | Place), two patterns keep the instance round-trippable (see ); a model ecosystem SHOULD adopt one of them consistently:

1. Value-form - a single plain term (no @type: "@id"); the value shape alone disambiguates: a bare scalar is a literal, { "id": ... } is a reference, a typed object is embedded. References are written as objects, and the term MUST NOT carry @type.
2. Separate keys - a canonical term p with @type: "@id" (a bare IRI string reference, plus embedded objects via a scoped @context) and a companion p_text that is a plain term for the literal.

Whichever pattern is chosen, x-oold-range records the permitted target type(s) on the reference and embedded branches (see ).

Projection to RDF and round-trip

An OO-LD instance projects to RDF through its @context and can be reconstructed from RDF. Because RDF is an unordered set of triples over a flat graph, faithful reconstruction follows a fixed contract:

• Literals and references reconstruct by JSON-LD compaction against the schema's @context alone.
• Embedded objects are flattened in RDF, and compaction does not re-nest a flat graph, so reconstructing the tree requires Framing - the frame can be as small as { "<property>": {} }. The embedded object needs an explicit type only when the property's scoped @context is type-scoped - keyed by the value's @type to distinguish several embedded types (or to stamp the node's rdf:type); a flat scoped context for a single embedded type needs none. Where required, tooling materializes the type on export (see ).
• Multi-valued properties are set-valued in RDF: order is not preserved, duplicates are removed, and a single value compacts to a scalar. Because the reconstruction MUST re-validate, a property that is strictly an array (JSON Schema type: "array") MUST declare @container: "@set" (or "@list"): without it a single-element array returns as a scalar and violates the array type. A property that also permits a scalar (an anyOf/oneOf of a literal and an array) MAY declare it for a stable array shape, but need not - the scalar form still validates, and a single value and a one-element array are JSON-LD-equivalent. Round-trip equality is set equality; use @list only where order is significant, at the cost of merge and query ergonomics.
• Language-tagged text uses @language (or @container: "@language") so multilingual instance values round-trip - distinct from x-oold-multilang-title / x-oold-multilang-description, which localize the schema's own annotations, not instance data.

Identification

OO-LD schemas MUST have a $id ([[JSONSCHEMA]] §8.2.1) which works as a global and unique identifier of the schema. The value of $id MAY be an absolute URI (details below). The schema SHOULD be resolvable via this URI. The schema SHOULD have an annotation x-oold-uuid with a UUID value.

Ontology class IRI (x-oold-iri)

x-oold-iri declares the IRI of the ontology class that this schema realizes - the RDF/OWL class from an external vocabulary that gives the schema its semantic grounding. It is distinct from two related IRIs:

• $id - the URL of the schema document (where to fetch it). A schema document is a retrievable artifact, not an OWL class.
• x-oold-instance-rdf-type - the rdf:types that instances carry on export (see ). These are stamped onto instance data; x-oold-iri describes the schema itself.

In this example, the schema document is fetched from the $id URL, it realizes the ontology class schema:Person, and instances exported to RDF carry @type: schema:Person. The most common case is that x-oold-iri and the entries in x-oold-instance-rdf-type resolve to the same IRI, but they may differ - for example when a schema models a more specific subclass inline while still emitting a broader rdf:type on instances.

OO-LD-aware tooling uses x-oold-iri to anchor the schema in an ontology graph, independently of where the schema document is hosted - for example to resolve super-classes, look up ontology annotations, or generate SHACL shapes.

Versioning

The schema version SHOULD be indicated by x-oold-version; a prior version MAY be indicated with x-oold-prior-version:

The version SHOULD be part of the schema's location:

• For single-schema versioning, the version SHOULD be appended after the schema name, e.g. https://example.org/b5203131-7321-46bb-8a11-acb3d1015840.schema.json/1.1.0.
• For schema-package versioning (recommended), the version of the package SHOULD be prepended before the schema's ID, e.g. https://example.org/my-package/2.0.0/b5203131-7321-46bb-8a11-acb3d1015840.schema.json.
• or using release tags on GitHub, e.g. https://raw.githubusercontent.com/MyOrg/my-package/refs/heads/2.0.0/b5203131-7321-46bb-8a11-acb3d1015840.schema.json.

Since a package combines multiple schemas, the package version does in general not match the individual schema version.

Schemas MAY indicate explicit backward-compatibility with x-oold-backward-compatible-with and x-oold-incompatible-with:

Schemas within a package or package repository MAY use relative URIs ([[RFC3986]] §5.1). For example, A.schema.json referenced from https://raw.githubusercontent.com/MyOrg/my-package/refs/heads/2.0.0/:

Instance documents SHOULD always use a versioned schema URL to make clear which schema version they comply with:

Upgrade APIs MAY provide automated data migration between schema (package) versions, e.g. https://example.org/upgrade/my-package/1.0.0...2.0.0.

JSON-LD

OO-LD targets [[JSON-LD11]].

JSON Schema

OO-LD targets [[JSONSCHEMA]] (2020-12) as its normative dialect. An OO-LD schema SHOULD declare the OO-LD dialect meta-schema (which extends 2020-12) as its $schema, e.g. "$schema": "https://oo-ld.github.io/oold-schema/latest/meta/oold-meta-schema.json" - pinning a specific version (e.g. .../0.4.0/meta/oold-meta-schema.json) for reproducibility. Declaring the plain 2020-12 meta-schema (https://json-schema.org/draft/2020-12/schema) remains valid for tools that only understand standard JSON Schema.

2020-12 is REQUIRED, not merely preferred: OO-LD's composition places $ref alongside sibling keywords (e.g. a property carrying type, x-oold-range and @context, or allOf: [{$ref: ...}] next to properties). Keywords adjacent to $ref are only evaluated from JSON Schema 2019-09 onward; in Draft 4 and Draft 7 they are ignored ([[JSONSCHEMA]] §8.2.3.1). Keywords such as const (used throughout this document) are likewise only available from draft-06 onward. Migration from the earlier Draft-4-style notation: rename definitions to $defs, id to $id, and use the numeric form of exclusiveMinimum/exclusiveMaximum instead of the boolean form.

{
  "$schema": "https://oo-ld.github.io/oold-schema/latest/meta/oold-meta-schema.json",
  "$id": "UiAnnotations.schema.json",
  "@context": [
    {
      "@version": 1.1,
      "schema": "https://schema.org/",
      "name": "schema:name",
      "role": "schema:jobTitle",
      "homepage": { "@id": "schema:url", "@type": "@id" },
      "notes": "schema:comment",
      "internal_id": "schema:identifier"
    }
  ],
  "x-oold-uuid": "b1e7a0c2-2d4f-4a1e-9c3a-7f0e5d2b6a11",
  "title": "Researcher",
  "x-oold-multilang-title": { "en": "Researcher", "de": "Forschende Person" },
  "x-oold-iri": "schema:Person",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "title": "Name",
      "x-oold-ui-default-property": true,
      "x-oold-ui-property-order": 1,
      "x-oold-ui-property-group": "General",
      "x-oold-ui-hint": "Full name",
      "x-oold-multilang-ui-hint": { "en": "Full name", "de": "Vollständiger Name" }
    },
    "role": {
      "type": "string",
      "title": "Role",
      "enum": ["pi", "postdoc", "phd"],
      "x-enum-varnames": ["PrincipalInvestigator", "PostDoc", "PhDStudent"],
      "x-enum-descriptions": ["Leads the project", "Holds a doctorate", "Doctoral candidate"],
      "x-oold-ui-enum-titles": ["Principal investigator", "Postdoc", "PhD student"],
      "x-oold-multilang-ui-enum-titles": { "en": ["Principal investigator", "Postdoc", "PhD student"], "de": ["Projektleitung", "Postdoc", "Doktorand"] },
      "x-oold-ui-property-order": 2,
      "x-oold-ui-property-group": "General"
    },
    "homepage": {
      "type": "string",
      "title": "Homepage",
      "format": "uri",
      "x-oold-ui-property-group": "Contact"
    },
    "notes": {
      "type": "string",
      "title": "Notes",
      "x-oold-ui-widget": "markdown",
      "x-oold-ui-property-group": "Contact"
    },
    "internal_id": {
      "type": "string",
      "title": "Internal id",
      "x-oold-ui-form-hidden": true
    }
  }
}

{
  "overlay": "1.0.0",
  "info": {
    "title": "Researcher admin overlay",
    "version": "1.0.0",
    "description": "Applies presentation-only x-oold-ui-* keywords to Researcher without editing the schema. An overlay is a general schema-patching mechanism (OpenAPI Overlay 1.1.0); UI annotation is one use case."
  },
  "extends": "./UiAnnotations.schema.json",
  "actions": [
    {
      "target": "$.properties.internal_id",
      "description": "Show the internal id for admins.",
      "update": { "x-oold-ui-form-hidden": false }
    },
    {
      "target": "$.properties.notes",
      "description": "Render notes as a plain textarea instead of markdown.",
      "update": { "x-oold-ui-widget": "textarea" }
    },
    {
      "target": "$.properties.role",
      "description": "Drop the render-time grouping for a flat admin form.",
      "remove": false,
      "update": { "x-oold-ui-property-group": "Identity" }
    }
  ]
}

Semantic delivery

An OO-LD schema carries its semantics in the top-level @context and, for the RDF type of instances, in x-oold-instance-rdf-type. How those reach a consumer depends only on which keywords the consumer tolerates. The native form is preferred; the alternatives below are mechanically generated from it, so the OO-LD document remains the single source and every form yields the same RDF.

• A consumer that accepts arbitrary JSON Schema keywords SHOULD receive the native form unchanged. This covers plain JSON Schema 2020-12 validators, OpenAPI 3.1, and - because they place no restriction on @context - Model Context Protocol tool schemas (inputSchema / outputSchema) as well as LLM tool-use and structured-output APIs, which carry the context through and can use it as grounding.
• For OpenAPI 3.0, which rejects unprefixed keywords in a Schema Object (and typically bundles several classes with no document root to host one @context), the context and type SHOULD be delivered per class as x-jsonld-context and x-jsonld-type following REST API Linked Data Keywords: @context maps to x-jsonld-context and x-oold-instance-rdf-type to x-jsonld-type. That draft requires references inside these keywords not to be dereferenced automatically, consistent with the x-oold-ref rule (see ). The mapping is reversible, so such an export can be read back into an OO-LD schema.
• For a strict structured-output subset that rejects unknown keywords entirely, the relevant IRIs MAY instead be folded into the title / description annotations the model also reads.

Worked examples of each tier, including the per-class OpenAPI 3.0 mapping, are given in the guide (see Delivery to OpenAPI, MCP and LLM tooling).

Security Considerations

Both the security considerations of [[JSON-LD11]] (§C) and of [[JSONSCHEMA]] (§13) apply. In particular, a consumer SHOULD NOT blindly trust the schema an instance declares for itself (a crafted instance could point at a permissive schema) and remains responsible for validating against a schema it trusts.