Notation

The normative data model of OO-LD is the JSON data model shared by [[JSONSCHEMA]] and [[JSON-LD11]]. JSON ([[RFC8259]]) is the canonical serialization: a conforming OO-LD schema or instance MUST be interchangeable as JSON, and the canonical form used for identity and integrity (for example content-hashing a versioned schema) is its JSON Canonicalization Scheme ([[RFC8785]]) serialization.

A document MAY additionally be authored or served as YAML, provided it stays within the JSON-compatible subset of YAML 1.2: no tags, anchors, aliases, or merge keys; a single document; and no implicit typing beyond what JSON expresses. Within this subset - the same profile adopted by YAML-LD - a YAML document maps one-to-one onto the JSON data model and converts to the canonical JSON without loss. YAML outside this subset is NOT a conforming OO-LD serialization.

Authors using YAML should be aware that YAML comments and implicit type coercions (for example the strings NO or 1.10 read as a boolean or a truncated number by some parsers) do not survive conversion to the canonical JSON; the JSON form is authoritative. Examples in this specification are shown as JSON, with an equivalent YAML rendering available under "View as YAML".

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 ([[JSONLD11-API]], Context Processing Algorithm). 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.

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.

A materialized @type is an ordinary JSON-LD @type: its IRIs resolve through the @context like any term, so a class name declared as a context term ("QuantityValue": "qudt:QuantityValue") is aliased on export, carries term synonyms, and drives frame construction. x-oold-instance-rdf-type and an inline type are thus two ways to reach the same @type: the former lets an application keep the type in the schema alone (no @type duplicated on every instance) and inject it on export, the latter carries it in self-describing data. Whether a type is subject to profile aliasing follows ordinary JSON-LD @type semantics: a value written as a term (a plain string such as "QuantityValue") resolves through the @context and so is aliased per profile if that term carries synonyms, exactly as an inline type term is, whereas a value written as a full IRI or CURIE ("qudt:QuantityValue", "http://qudt.org/...") is emitted verbatim and not aliased. This holds for a materialized x-oold-instance-rdf-type and an inline type alike - the author selects term form for a profile-aliasable type, IRI form for a fixed one. Multiplicity and aliasing are orthogonal: x-oold-instance-rdf-type co-types - it lists every rdf:type an instance asserts at once (e.g. qudt:QuantityValue and schema:QuantitativeValue together) - while x-oold-context on a type term supplies the synonyms of a single type, one chosen per profile; a co-typed type may itself carry synonyms, so the two compose.

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.

An embedded object is mapped by a scoped @context on its property (referencing the embedded type's own context). These scoped contexts form an embed graph between schemas, and that graph SHOULD be acyclic: model a property whose value is an independent entity, or whose type would close an embed cycle (a type embedding itself, or two types embedding each other), as a reference - @type: "@id" plus x-oold-range, with no scoped @context - rather than an embed. This is the linked-data analog of using a pointer instead of inlining a recursive data structure. A self-reference through the top-level @context (a property that nests the same type but carries no scoped context, so the global context maps the nested keys - e.g. a Process with sub-Processes) is not part of this graph and round-trips normally, bounded by the instance's actual depth.

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 correspondence (schema-level x-sssom)

A schema states which external ontology resources it corresponds to with a top-level x-sssom block - the term-synonym mapping row lifted to the schema level. Its subject is the schema itself, identified by its $id: in OO-LD the schema document at that URL is the class definition, so $id serves as the mapping's subject_id. It is an object keyed by the object IRI of a resolvable resource (an RDF/OWL class, a controlled-vocabulary term, another schema), each value carrying the SSSOM slots: predicate_id (default skos:exactMatch; skos:closeMatch for a looser correspondence), mapping_set_id, and the rest of the open bag. Because these are SKOS mapping predicates the correspondence is non-logical and reasoner-safe: skos:exactMatch asserts interchangeability, not the logical owl:equivalentClass (a schema that wants the reasoner-affecting claim uses owl:equivalentClass explicitly as the predicate_id). It is an annotation about the schema itself and is not stamped onto instances - distinct from x-oold-instance-rdf-type, the rdf:types instances carry on export (see ), which are stamped onto instance data.

Here the schema document is fetched from the $id URL, it is declared an exact match for schema:Person, and instances exported to RDF carry @type: schema:Person. Commonly a schema's exact match and the entries in x-oold-instance-rdf-type resolve to the same IRI, but they may differ - a schema may model a more specific subclass inline while emitting a broader rdf:type, or exact-match one class while close-matching a related one in another vocabulary. Because this is the same mapping machinery as term synonyms, the schema-level mappings carry the same predicate_id semantics, mapping_set_id selection and SSSOM round-trip (see ).

OO-LD-aware tooling uses these correspondences 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.org/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.org/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-sssom": { "schema:Person": { "predicate_id": "skos:exactMatch" } },
  "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
    }
  }
}

$schema: https://oo-ld.org/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-sssom:
  schema:Person:
    predicate_id: skos:exactMatch
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" }
    }
  ]
}

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. Such a subset typically also constrains the JSON Schema itself (closed objects, all-required properties, limited composition), so the delivery step may apply a small structural transform - for example flattening an allOf inheritance chain - in addition to folding the IRIs; the semantics still originate in the single OO-LD source.

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.