The contract a semantic pod implements. A pod is a data space you host, addressed over HTTP, holding structured linked data: apps and agents come to your data instead of keeping copies of it, and you decide who may read or write what.
This repository holds the specification of that model. It is written to be implementable by somebody who has never read the reference implementation — in any language, on any store.
Its leverage comes from composition rather than novelty at the bottom of the stack. sempods names and profiles existing standards — HTTP, RDF datasets, JSON-LD, SPARQL, OAuth/OIDC and MCP — then specifies the contract that makes them behave as one pod: contexts as the permission boundary, server-resolved grants, sandboxed query and write surfaces, and conformance that another implementation can test.
| sempods-spec (here) | the contract: what an implementation MUST do |
| sempods-kotlin | the reference implementation for the JVM — pod server, identity service, hosted MCP, client libraries |
| www.sempods.org | the project website |
This is the only text duplicated across the three repositories. Everything else lives in exactly one of them and is linked from the others.
Development: 0.1-dev; no specification release has been published yet. The normative chapters
already bind under governance. A development label changes over time; cite the exact
Git commit when recording what a client or implementation was checked against.
- Development website — the rendered
mainsnapshot, with its source revision - Published versions and release notes — immutable tags and matching artifacts when published
- Selecting a revision — obtain and use a consistent snapshot
- Proposals — non-normative designs with explicit adoption status
- Repository checks — what validation establishes and what it does not
- Issues and 0.1 milestone — work and agreed release conditions
Core and module chapters, OpenAPI and vocabulary are present. A product conformance suite remains unfinished; passing repository checks is not a product conformance claim.
Three artefacts, one anchor:
- Normative text under
spec/— Markdown, RFC 2119 keywords, one stable requirement ID per normative statement. This is the specification. - OpenAPI 3.1 descriptions for core and each module with an HTTP surface, hand-written and part of the contract. They carry the shapes, parameters and status codes; they cannot carry grant resolution or the context and SPARQL sandboxes, which is why OpenAPI is not the specification on its own.
- A conformance suite, later, which is what turns a requirement ID from a claim into a check.
The requirement IDs are the load-bearing part: a conformance test, a note in the reference
implementation and an OpenAPI operation all point at SPS-CRUD-011 rather than at a file and a
heading. Chapters may then be split, renamed or moved without breaking anything that cites them.
spec/README.md has the scheme and the chapter map.
The vision explains requirement selection. Proposals record substantial designs with explicit adoption status; the ACP fixture guide explains the illustrative examples and their limits. These are informative sources alongside the current contract.
Project brand assets live under docs/brand/. They are not part of the normative
specification, but this repository is their source of truth so the website, organisation profile
and applications all copy the same files.
Core is what every sempods implementation must provide: contexts, grants, authorization, LOD CRUD, SPARQL, find. There is no opt-out and no partial core.
Modules are optional, versioned separately, and named: context management, OIDC, media, MCP. Optional only means something if a client can find out, so an implementation advertises what it implements at a discovery endpoint rather than in a README. The mechanism is part of the core chapter.
LICENSE— CC BY 4.0, for the specification text and the RDF vocabulary. Using the terms in your own data requires no licence, no attribution and no permission.LICENSE-CODE— Apache 2.0, for the conformance suite and tooling once they exist.NOTICE— the summary, and the trademark position: Apache-2.0 §6 grants no rights in the name, and what you may call your own work is set out in the reference implementation'sTRADEMARKS.md.
Two terms are reserved and mean nothing yet: "sempods conformant" and "sempods certified" require a written licence granted on passing the conformance suite, which does not exist. Write "implements the sempods specification" and document your deviations.
A specification change moves slower than an implementation change and needs a written rationale,
because other implementations depend on it. GOVERNANCE.md says how one is
proposed, who decides, and how versions work.
Everything that holds across the whole project — the Developer Certificate of Origin (git commit -s, and deliberately no CLA), the licensing of contributions, the AI-assistance policy, the code of
conduct — lives once in the organisation's
shared contributing guide and is
inherited here rather than copied.
A vulnerability in the specification is a rule that cannot be implemented safely — a flow that leaks context topology, an authorization check that is underspecified. Report it privately through the repository's Security tab, or to hello@sempods.org, never in a public issue.
A vulnerability in the reference implementation belongs in
sempods-kotlin instead. The policy
itself is the organisation-wide
SECURITY.md.