OO-LD Schema

The Object-Oriented Linked Data Schema, based on JSON-LD and JSON Schema - work in progress.

OO-LD connects the structural modelling of objects and subobjects with the modelling of their semantic relations, without reinventing the wheel: a single OO-LD document is at once a valid JSON Schema and a reference-able JSON-LD context. You define the structure of your data and its meaning in one source, then reuse that schema for validation, RDF generation, code generation, user interfaces, and API definitions - using the JSON Schema and JSON-LD tooling you already have.

A minimal example

{
  "@context": {
    "schema": "http://schema.org/",
    "name": "schema:name"
  },
  "title": "Person",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "First and Last name"
    }
  }
}

The JSON Schema part (type, properties) describes the structure; the @context maps name to the semantic term schema:name. Try it in the interactive playground.

Documentation

📖 Full documentation: https://oo-ld.org/

The site covers the concepts and specification in an orientation-style guide with worked examples:

• Introduction - what OO-LD is and why.
• Get Started - a first hands-on example.
• Guide - basic concepts, composition, schema instances, identification & versioning, extensions, and the meta-schema.
• Use Cases, Mappings, Tooling, and Reference.

The normative, W3C-style Specification (rendered with ReSpec) accompanies the guide: the guide is for learning, the specification is for conformance and citation.

Repository contents

• examples/ - example OO-LD schemas (Person, Organization, Address, Researcher, Thing).
• meta/oold-meta-schema.json - the OO-LD dialect meta-schema, defining the x-oold-* keywords.
• docs/ - the documentation site source (built with zensical).
• spec/ - the specification source, written in plain Markdown.
• macros.py - shared macros that pull reused content (examples, the keyword table) into both the guide and the spec.
• scripts/ - the schema validator and the spec renderer.

How the docs and spec are published

Everything is written once and reused. The guide pages and the specification pull their example schemas from examples/ and the keyword vocabulary from meta/ via small macros, so those never drift apart. The specification itself is plain Markdown in spec/sections/; make spec renders it into a W3C-style page (ReSpec) at docs/spec/index.html, which is committed and served as part of the site. On every push, CI validates the example schemas, re-renders the spec, and fails if the committed copy is stale; on main the site is then deployed to GitHub Pages (see .github/workflows/main.yml).

Common tasks are wrapped in a Makefile (run make or make help to list them):

make validate   # validate the example schemas against the meta-schema
make spec       # re-render the specification from spec/ and meta/
make docs       # serve the documentation site locally with live reload
make preview    # re-render the spec, then serve the site
make check      # validate + spec lint + site build (what CI runs)

The docs and the spec renderer run on Python via uv - no local Python setup required; the schema validator runs on Node (make install once).

Getting involved

Questions, ideas and design discussion are welcome - for now all in the issue tracker (one searchable place while the community is small):

• Question (usage, tooling, spec interpretation) - open an issue with the question label.
• Open-ended discussion / proposal - open an issue with the discussion label.
• Bug or feature - open a regular issue.
• Contributions - pull requests are welcome; for larger changes, open a discussion issue first.

We'll consider GitHub Discussions or a chat once demand grows.

License

Released under CC0 1.0 Universal.