A domain neutral semantic framework for representing governing instruments (contracts, protocols, agreements, etc) and the obligations, eligibility conditions, and lifecycle behaviours they define, as structured, queryable, versioned graphs.
As a project, Lattice has been organised to allow users to pick and choose the parts they want without depending on everything. Lattice provides ontologies, libraries, deployable services, and control-plane infrastructure the way a framework does, and is not a standalone application.
An adopter is free to take some of it, all of it, or build around it entirely, and the parts they do take, they configure for their own domain and their own operational constraints.
| Part | Purpose |
|---|---|
| Ontology Substrates | The ontologies in the substrate layers can be used together or standalone, to develop domain ontologies with consistent semantics inherited from these upper ontologies. |
| Applied Ontology Layers | Pre-built domain ontologies with a focus on a specifc subject area, industry, or goal/usage |
| Tools | Tools that operate on both the internal substrates (upper ontologies), applied ontologies, and a user's own domain ontologies |
| Platform (design time) | Capabilities that offer design support and administrative tooling for users of Lattice |
| Platform (runtime) | Software infrastructure, services, and applications that support building complex ontology-based solutions on top of Lattice |
MORK (Mapping Ontological & Representational Knowledge) used to map source material — structured data (schemas, records, API specifications, etc) and unstructured wordings (documents, clauses, free text) — onto a target domain ontology's T-box & R-Box, using Formal Concept Analysis over the co-occurrence structure of previously mapped source material to propose alignment. MORK as a general-purpose mapping vocabulary, based on SKOS.
The layers described below are one family of mapping target, but not the only possible one. MORK's semantic vocabulary and target declarations live under ontology/mork/, while its Python implementation lives under tools/mork/. LATTICE uses MORK as the reference way of populating its own layers.
LATTICE (Concept Lattice of Domain Ontology Layers) provides the semantic substrate MORK's output lands in - designed to be extended by particular subject domains in order to be used in industry-specific ways.
SPC (Subject-oriented Process Calculus) provides a formal mechanism for describing orchestration between agents (human, AI, or computational), whose data has been mapped in by MORK and whose roles, obligations, and eligibility are modelled in LATTICE. Where LATTICE's Behaviour layer models what state something is in and what can cause it to change, SPC is concerned with the live, session-typed exchange between agents that drives those changes — giving that exchange a formal contract to align to, grounded in the same ontology, rather than an ad hoc protocol. SPC has a substantial standalone ontology under ontology/spc/, with Python and Erlang implementations under tools/spc/. It is not yet integrated with the layers below: it uses a placeholder namespace and declares no projection/ contract to any of them. Treat it as a separate, pre-integration body of work rather than part of the dependency graph described below.
Persistence (the Data Access Layer, dal:) lets an adopter select, per class or per deployment of their own applied ontology, which of the portable RDF/SPARQL patterns in docs/architecture/rdf-sparql-patterns-guide.md apply: aggregate boundary, concurrency, ordering grain, receipt model, meta topology, and uniqueness. The framework-neutral IRI and Identity Patterns guide defines a future identity-profile dimension for the same configuration model. It is a cross-cutting substrate, not a layer — it targets classes, graphs, and shapes by IRI reference only, and no layer imports it or is imported by it. The vocabulary and SHACL shapes live under ontology/persistence/; a design-time-only compiler (no store SPI, no live backend) that turns a selection into generated SPARQL lives under tools/persistence/. See ADR-A78, ADR-A79, and ADR-A82.
LATTICE is organised as seven layers, each an independent OWL/SHACL/SKOS module:
| Layer | Kind | What it models |
|---|---|---|
| Foundation | Substrate | Identity, versioning, provenance and evidence, governance state, temporal scoping, and a derived-artefact contract aligned with PROV-O (ADR-A92). |
| Vocabulary | Substrate | The governed mechanism by which external, domain-specific concept schemes get bound into the other layers without touching their core specifications, including scoped and time-bounded bindings. The vocabulary and SHACL shapes live under ontology/vocabulary/; a reference resolver for the scoped/temporal binding precedence law lives under tools/vocabulary/. See ADR-A85. |
| Quantification | Substrate | Declared value spaces, quantities, ordered values, bounds, ranges, conversion, granularity, and recurrence — the mechanism behind any magnitude, interval, or ordinal comparison the other layers need. |
| Party | Substrate | Actors, the roles they occupy, and the direction and composition of obligation between them (e.g., modelling independently capped shares, joint obligation with a right of recourse, delegated accountability, or contingent role occupancy). |
| Eligibility | Substrate | Admissibility criteria (conditions, unresolved questions, and decisions), including concept inclusion and exclusion and evidence bindings that evaluate an applied ontology's own properties. tools/mork_compilers compiles conditions and profiles to SPARQL, SHACL, and SWRL through one IR. See ADR-A87, ADR-A89 and ADR-A91. |
| Behaviour | Substrate | State, transition, trigger, and effect, including a usable Sequential allowance profile. Proportional allowance semantics and reset edge cases remain explicitly deferred. |
| Instrument | Applied domain ontology | A primary domain ontology built on the substrates, giving the generic shape of a governing document, e.g., Provision → Obligation → Qualifier. |
Instrument is a first layer building on the substrates. A different applied domain ontology (e.g., a device's operational lifecycle, access-control entitlement system, asset maintenance schedule, etc) could sit atop Instrument or even replace it, composing with the same Party, Eligibility, and Behaviour mechanisms through its own projection/ contracts, without touching any of the core specifications.
Every mechanism in a layer's specification should be usable without knowing what industry or domain is consuming it. See ontology/examples/ for the worked instances.
Each layer directory follows the same internal template, present in whole or in the parts that layer actually needs:
<layer>/
├── README.md
├── spec/ # normative T-box
├── shapes/
│ ├── structural.ttl # SHACL property shapes — local, per-instance
│ ├── constraints.ttl # SHACL-SPARQL — whole-graph conditions
│ └── rules.ttl # SHACL-SPARQL rules that materialise derived facts
├── vocab/ # mechanism-intrinsic enumerations only, never including business vocabulary
├── projection/ # the layer's declared contracts to/from other layers
├── execution/ # generated runtime artefacts, where a layer needs one,
│ # plus the docs governing how they're regenerated
├── examples/ # single-layer worked examples
└── test/ # the layer's own shape and rule tests
Governance is deliberately separate from every layer it checks — ontology/governance/ runs over the union graph rather than living inside any one module, enforcing scheme-contract compliance, deprecation posture, and cross-layer parity in CI.
Compiled artefacts live under execution/, being generated from spec/, shapes/, vocab/, and projection/ by deterministic, reproducible processes or code (to be regenerated on source change per that layer's invalidation-policy.md).
The tools/ folder holds reference implementations handling compilation. It's licensed separately from everything else in the tree — see Licensing.
lattice/
├── README.md
├── LICENSE # MPL 2.0 — ontology artefacts, tools/
├── LICENSE-DOCS.md # CC BY-SA 4.0 — documentation, specifications
├── CONTRIBUTING.md
│
├── ontology/catalog-v001.xml # Generated import catalog, every ontology and version IRI (ADR-A88)
├── ontology/foundation/ # Foundation Layers (provenance, versioning)
├── ontology/vocabulary/ # Inclusion of Domain-specific Vocabularies
├── ontology/quantification/ # Value Spaces, Quantities, Ranges, Recurrence
├── ontology/party/ # Parties, Roles, & Participation Modelling
├── ontology/instrument/ # Governing Instrument (Upper Domain Ontology)
├── ontology/eligibility/ # Eligibility Criteria Modelling
├── ontology/behaviour/ # Behaviour Modelling
│ ├── mork/ # Mapping vocabulary and semantic fixtures
│ ├── spc/ # Orchestration ontology, standalone and unintegrated
│ ├── persistence/ # Data Access Layer (dal:), cross-cutting, no layer dependency
│
├── ontology/governance/ # Cross-layer governance
│ ├── scheme-contracts/
│ ├── parity/
│ └── shapes/
│
├── docs/
│ ├── architecture/
│ └── decisions/
│
├── ontology/examples/ # Cross-layer composition scenarios
│ ├── employment.ttl
│ ├── lending-covenant.ttl
│ ├── saas-subscription.ttl
│ ├── clinical-trial.ttl
│ └── insure-o/ # Applied validation package for insurance-style substrate checks
│
├── contracts/
│ └── identity/ # Minting recipe and vector schemas, anchor vectors, independent verifier
│
├── platform/
│ └── reasoning-testkit/ # Test-only OWL reasoner harness, never a runtime dependency (ADR-A83)
│
├── packages/
│ └── minting/ # Standalone identity minting libraries (Python, Java), no LATTICE dependency
│
├── test/ # Whole-graph CI
│
└── tools/ # Reference implementation
foundation
└── vocabulary
└── quantification
└── party
├── eligibility
│ └── instrument
└── behaviour (imports instrument, eligibility, party, quantification)
mork — targets any layer
spc — standalone today; not yet imported by, or importing, any layer above
spc — leverages domain ontology axioms to form session types once a separate integration effort defines the needed contracts
A few commmon compositions are worth noting:
- Guard calls Eligibility. A Behaviour transition's guard condition is, in the general case, an Eligibility decision: conditions, unresolved questions, and results.
- Effects write into Instrument or Party. A transition firing can create or modify an Obligation, or populate a Role Occupancy that was contingent until that moment.
- Role Occupancy is itself stateful. The same State/Trigger/Effect apparatus that governs an Obligation's status governs whether a Role is currently occupied at all — this is what allows a party who is not connected to an instrument be bound in later, by the instrument's own design.
mise --version
mise doctor
mise install
mise ls
mise exec -- python --version
mise exec -- node --version
mise exec -- java -version
mise exec -- mvn --version
mise exec -- elixir --version
mise exec -- erl -eval 'io:format("~p~n", [erlang:system_info(otp_release)]), halt().'mise run topology:preflight
test -d ontology
test -d tools
test -d tools/mork
test -d tools/mork_compilers
test -d tools/surface
test -d tools/persistence
test -d tools/spc/python
test -d tools/spc/erlang
test -d workers
test -d platform
test -d apps
test -d contractsmise run bootstrapThis installs the root Python dependencies, worker dependencies, Yarn workspace, etc.
mise run checkThis runs:
mise run check:python-root
mise run check:workers
mise run check:java
mise run check:frontend
mise run check:spc
mise run check:persistence
mise run check:minting
mise run build:mtp
mise run check:mtpmise exec -- yarn check
mise exec -- yarn build
mise exec -- yarn testIf Playwright reports missing browsers:
mise exec -- yarn workspace @lattice/mork-review-workbench exec playwright install
mise exec -- yarn workspace @lattice/surface-contract-studio exec playwright install
mise exec -- yarn testmise exec -- python -m pip install -e tools/mork -e tools/mork_compilers -e tools/surface
mise exec -- python -m pytest tools/mork/src -q
mise exec -- python -m compileall -q tools/mork/src tools/mork_compilers/src tools/surface/srcmise run bootstrap:persistence
mise run check:persistenceCompiles ontology/persistence's own worked examples, runs the resolver/validator/capability/boundary unit tests, the injection corpus, the determinism checks, and the Python architecture-policy checks, and validates every example fixture against ontology/persistence/shapes/constraints.ttl. See tools/persistence/README.md.
mise run bootstrap:reasoning-testkit
mise run check:reasoning-testkit
mise run check:reasoning-isolationBuilds and tests the test-only HermiT harness, and checks that no other module declares a reasoner. With the jar built, mise run check:mork-compilers also checks generated SWRL and OWL under HermiT. See platform/reasoning-testkit/README.md.
mise run bootstrap:minting-python
mise run check:minting
mise run check:minting-tablesVerifies the hand-authored anchor vectors with openssl, runs the Python and Java minting libraries against the anchors and the vectors generated from the compiler's recipes, and checks the pinned Unicode 16.0.0 tables against the Unicode Character Database. See packages/minting/README.md and the identity minting specification.
Not part of the default mise run bootstrap — Ruby/Jekyll are only needed when editing GitHub Pages content under docs/:
mise run bootstrap:jekyll
mise run serve:jekyllbootstrap:jekyll installs an isolated Ruby (via mise, scoped to this task only) and the exact gem set Gemfile.lock pins, into docs/vendor/bundle (gitignored, never committed). mise run clean (or mise run clean:docs alone) removes docs/vendor/, docs/.bundle/, and any local Jekyll build output (docs/_site/, .jekyll-cache/) without touching docs/Gemfile/docs/Gemfile.lock.
mise exec -- python -m pip install -e 'tools/spc/python[dev]'
mise exec -- python -m compileall -q tools/spc/python/srccd tools/spc/erlang
mise exec -- mix deps.get
mise exec -- mix test
cd ../..mise run testmise exec -- mvn -f platform/pom.xml clean verifyFocused Surface regression gate:
mise exec -- mvn -f platform/pom.xml -pl surface-workflow -am testdocker --version
docker compose version
docker compose -f deployment/compose/docker-compose.yml config
mise run services:up
docker compose -f deployment/compose/docker-compose.yml ps
mise run services:downThe service checks confirm container startup and reachability. They do not replace end-to-end integration tests.
The canonical active documentation locations are plans, status, and review.
Two licences govern the artefacts in the repository:
- Ontology artefacts (
.ttl), code (tools/,platform/,packages/,workers/) and machine-readable contracts (contracts/) — Mozilla Public License 2.0. Derivative works, commercial or otherwise, are permitted with no obligation to share what you build. If you modify one of these files and redistribute the modified version, that modification carries the same licence forward. JSON files cannot carry a licence header, soREUSE.tomldeclares theirs. - Documentation and specifications (
.md) — CC BY-SA 4.0. Use freely, share modifications to the text itself under the same terms.
See CONTRIBUTING.md for the licensing mechanics, the SPDX header convention, and where new content belongs within a layer.
Use mise for repository toolchain setup and task orchestration. See the toolchain guide, Windows and WSL guidance, and the Phase 0 and 1 validation handoff.
For the current implementation boundaries and reading order, see the platform implementation map. Architecture decisions are indexed in docs/architecture/decisions.