Use cases¶

Because an OO-LD schema is a plain JSON Schema carrying a JSON-LD context, it can drive a wide range of tooling from a single source. This page collects the main use cases.

Code Generation¶

In general, we want to keep keywords in 'instance' JSON-documents (=> property names in schemas) strict ^[A-z_]+ [A-z0-9_]*$ to avoid escaping or replacing when mapping to other languages. This works well with aliasing, e.g.

{
  "@context": {
    "ex": "https://example.org/",
    "schema": "http://schema.org/",
    "name": "schema:name",
    "type": "@type"
  },
  "x-oold-iri": "ex:RawData",
  "title": "Person",
  "type": "object",
  "properties": {
    "type": {
      "type": "array",
      "items": { "type": "string"},
      "default": ["schema:Person"]
    },
    "name": {
      "type": "string",
      "description": "First and Last name"
    }
  }
}

Python¶

The Person schema above translates smoothly to python (pydantic) via https://github.com/koxudaxi/datamodel-code-generator:

class Person(BaseModel):
    model_config = ConfigDict(
        json_schema_extra={
            "@context": {
                "ex": "https://example.org/",
                "schema": "https://schema.org/",
                "name": "schema:name",
                "type": "@type"
            },
            "x-oold-iri": "ex:RawData",  # the IRI of the class
        }
    )
    type: Optional[str] = "schema:Person"
    name: Optional[str] = None
    """First and Last name"""

what would not be the case if we use @type or schema:name as property names (See also python playground). From pydantic it's also straight forward to (re)generate OO-LD and OpenAPI-Schemas, especially via FastAPI.

Workflows and Code Analysis¶

A common ground for workflow definitions are decorated dataclass-typed functions that are managed by a workflow-environment like prefect.

@flow
def my_node(param: MyInputClass) -> MyOutputClass:
  ...
  return MyOutputClass(...)

If these dataclasses are following OO-LD annotations as described above the semantics of the workflow (node) is inherently contained.

In this regard, OO-LD can be combined with standard code compiler/interpreter tooling, especially Abstract Syntax Trees and tracing provide a semantic description of software-defined workflows. More information see AWL

Integration with Large Language Models¶

Recent support of Large Language Models (LLMs) for structured output is based on JSON Schema. This allows the direct application of OO-LD schemas with LLMs in order to generate, complete or validate structured data. Example use cases see osw-chatbot

Delivery to OpenAPI, MCP and LLM tooling¶

An OO-LD schema carries its semantics in the top-level @context. When the schema is handed to OpenAPI tooling, an MCP client or an LLM, the goal is to keep those semantics available to the model (as grounding) and to downstream RDF - not to make the consumer emit @context in its output. With additionalProperties: false an instance stays limited to its declared properties, so @context remains schema-level metadata and is never produced as data.

MCP and tool-use / structured output. An MCP tool's inputSchema (and the outputSchema added in the 2025-06-18 revision) is an ordinary JSON Schema object whose keywords MCP does not restrict, so a top-level @context is carried through unchanged over tools/list. Tool-use and structured-output APIs accept such a schema, and the model uses the context as grounding: in a roundtrip where an MCP server advertised a tool with two opaque properties a and b mapped through @context to schema:familyName and schema:givenName, the client received the @context intact and the model filled the fields by the IRIs (a = "Mustermann", b = "Max") rather than by surface order. An OO-LD schema can therefore be used directly as an MCP tool schema or a structured-output schema, with no relocation. The exception is a strict provider subset that rejects unknown keywords; there, fold the IRIs into the title / description annotations the model also reads.

OpenAPI. OpenAPI 3.1 Schema Objects are JSON Schema 2020-12 and accept arbitrary keywords, so the native @context is used as-is. OpenAPI 3.0 Schema Objects reject unregistered keywords unless prefixed with x-, and a single OpenAPI document usually bundles several classes under components/schemas, where there is no document root to host one @context. Both are addressed by the IETF draft REST API Linked Data Keywords, which places a JSON-LD context and type on each Schema Object via x-jsonld-context and x-jsonld-type (valid for all OpenAPI versions >= 3.0). An OO-LD schema maps to them per class, mechanically and losslessly: @context -> x-jsonld-context (whose value is any valid JSON-LD context - object, array, or URL string, draft Section 2.2), and x-oold-instance-rdf-type -> x-jsonld-type (whose value is whatever the JSON-LD @type keyword accepts - a single IRI or an array of IRIs, JSON-LD 1.1 Section 3.5). The mapping is reversible, so an OpenAPI 3.0 export can be read back into an OO-LD schema.

For example, this OO-LD schema:

{
  "$id": "https://example.org/Person.schema.json",
  "@context": { "schema": "http://schema.org/", "name": "schema:name" },
  "x-oold-instance-rdf-type": ["schema:Person"],
  "type": "object",
  "properties": { "name": { "type": "string" } },
  "required": ["name"]
}

maps to the following OpenAPI 3.0 document, one Schema Object per class (the $id becomes the components/schemas key, and a cross-class $ref is rewritten to #/components/schemas/<Class>):

{
  "components": {
    "schemas": {
      "Person": {
        "x-jsonld-context": { "schema": "http://schema.org/", "name": "schema:name" },
        "x-jsonld-type": ["schema:Person"],
        "type": "object",
        "properties": { "name": { "type": "string" } },
        "required": ["name"]
      }
    }
  }
}