25b5a522f5
Stands up the JouleClaw vocabulary namespace at https://jouleclaw.transaction.science/vocab/v1# . Every field of every JouleClaw wire form (Receipt, PolicyReceipt, WorkspaceManifest, AgentIdentity, Action, Decision, ToolTouch, ClaimProvenance, Citation, IntentVerdict, …) now has a stable IRI under that namespace. Every enum (Cascade L0–L4, Provenance, FsMode, NetMethod, DenyReason, EntryKind, SensitivityLevel) is a typed RDF class. Why this matters: the JouleClaw wire forms are stable, signed, and byte-equal across three reference implementations — but they were still snowflake-schemas in the third-generation-interop sense. Without stable IRIs a third-party JSON-LD parser or SPARQL store can't disambiguate "tier", "joules_uj", "agent", "decision" without bespoke integration. This vocabulary fixes that. The change is purely additive: - Existing JouleClaw consumers ignore @context and read receipts exactly as before. No wire-form change. No signed-bytes change. - JSON-LD-aware consumers add @context (pointing at this URL) to a receipt and gain typed RDF semantics for every field. Verified end-to-end: tier:"L3" expands to jc:Model, energy_provenance: "ModelBased" expands to jc:ModelBased, … - SPARQL consumers shred receipts into a triple store using v1.ttl as the schema and query across cascade + policy + workspace + identity in one query. Aligns with W3C PROV-O where the alignment is exact: jc:ClaimProvenance ⊑ prov:Entity jc:AuditEvent ⊑ prov:Activity jc:AgentIdentity ⊑ prov:Agent PROV-O consumers reason about a JouleClaw deployment as a provenance graph using this one mapping — no JouleClaw-specific code beyond standard PROV-O semantics. Files: jouleclaw/vocab/v1.jsonld — JSON-LD @context (term → IRI mapping) jouleclaw/vocab/v1.ttl — Turtle ontology (classes, enums, properties, ranges) jouleclaw/vocab/README.md — human-readable vocabulary doc jouleclaw/SPEC.md §13 — normative "Vocabulary" section; renumbers prior §§13-15 to §§14-16 (Adjacent / References / Does-not-say) The vocabulary is canonical CC-BY-4.0 and served at the stable namespace IRI; the website at /vocab/v1 carries the human-readable index. The canonical signed core of a JCR-1 envelope deliberately does NOT include @context — it's metadata, not payload. This implements proposal #1 of the third-generation-agentic-AI adoption plan (per Michael Kerduchi's "What is Third Generation Agentic AI?" framing, drawing on Marcus Lanthaler's 2014 work that solved the interoperability problem the semantic-web community shipped). Subsequent proposals — Hydra ApiDocumentation on the MCP tool surface, SHACL shapes for actions and tool inputs, a generic Hydra client crate — compose cleanly on top of this vocabulary.
114 lines
4.3 KiB
Markdown
114 lines
4.3 KiB
Markdown
# JouleClaw vocabulary (v1)
|
|
|
|
Stable IRIs for the JouleClaw open-standard data model. Adopting the
|
|
**third-generation interoperability** stance: every JouleClaw field
|
|
gets a globally unambiguous IRI, every JouleClaw enum gets a typed
|
|
class, and JSON-LD / SPARQL / OWL consumers can reason about a
|
|
JouleClaw deployment without bespoke integration code.
|
|
|
|
## Namespace
|
|
|
|
```
|
|
https://jouleclaw.transaction.science/vocab/v1#
|
|
```
|
|
|
|
By convention prefix: `jc:`.
|
|
|
|
## Files
|
|
|
|
| File | Format | What |
|
|
|------|--------|------|
|
|
| [`v1.jsonld`](v1.jsonld) | JSON-LD `@context` | The term-to-IRI mapping that lets a JouleClaw receipt JSON document be read as RDF without changing its wire form. |
|
|
| [`v1.ttl`](v1.ttl) | Turtle (RDF) | The full vocabulary — classes, enumerations, properties, ranges. The canonical semantic definition. |
|
|
| `README.md` | Markdown | This file. |
|
|
|
|
The website at <https://jouleclaw.transaction.science/vocab/v1>
|
|
serves the human-readable index of the same terms.
|
|
|
|
## Why this exists
|
|
|
|
The JouleClaw wire forms (cascade `Receipt`, `PolicyReceipt`,
|
|
`WorkspaceManifest`, the policy `Action` / `Decision`, the energy
|
|
`Provenance` enum, etc.) are already stable, signed, and
|
|
conformance-verified across three independent implementations
|
|
(Rust + Python + Go). What was missing: a *machine-readable
|
|
contract* a consumer outside the JouleClaw ecosystem could ground
|
|
on. Without one, every integration is bespoke — the
|
|
"snowflake-schemas-everywhere" pathology Marcus Lanthaler's 2014
|
|
dissertation identified as the load-bearing failure mode of
|
|
generation-2 web APIs.
|
|
|
|
This vocabulary fixes that. It is **purely additive**:
|
|
|
|
- Existing JouleClaw consumers ignore `@context` and read receipts
|
|
exactly as they did before. No wire-form change. No
|
|
signed-bytes change.
|
|
- JSON-LD-aware consumers add `@context:
|
|
"https://jouleclaw.transaction.science/vocab/v1.jsonld"` to a
|
|
receipt (or fetch the context out-of-band) and gain typed RDF
|
|
semantics for every field.
|
|
- SPARQL consumers shred receipts into a triple store using `v1.ttl`
|
|
as the schema and query across cascade + policy + workspace +
|
|
identity in one query.
|
|
|
|
## What it covers
|
|
|
|
The vocabulary defines IRIs for every term in the JouleClaw
|
|
open-standards data model:
|
|
|
|
- **Classes:** `Receipt`, `PolicyReceipt`, `WorkspaceManifest`,
|
|
`WorkspaceEntry`, `AgentIdentity`, `ToolTouch`, `ToolReceipt`,
|
|
`ClaimProvenance`, `Citation`, `TextSpan`, `TokenAttribution`,
|
|
`IntentVerdict`, `Action` (with `FsAction` / `NetAction` /
|
|
`ProcAction` subclasses), `Decision` (with `Allow` / `Deny`
|
|
subclasses), `AuditEvent`.
|
|
- **Enumerations:** `Cascade` (`L0:Cache` … `L4:Wire`),
|
|
`Provenance` (`HwShunt` / `ModelBased` / `Estimator`), `FsMode`,
|
|
`NetMethod`, `DenyReason`, `EntryKind`, `SensitivityLevel`.
|
|
- **Properties:** every public field of every JouleClaw wire type
|
|
(`jc:closedAt`, `jc:joulesMicrojoules`, `jc:tier`,
|
|
`jc:policyVersion`, `jc:contentHash`, …).
|
|
|
|
The vocabulary subclasses W3C PROV-O where the alignment is exact:
|
|
`jc:ClaimProvenance` is a `prov:Entity`, `jc:AuditEvent` is a
|
|
`prov:Activity`, `jc:AgentIdentity` is a `prov:Agent`. PROV-O
|
|
consumers can therefore reason about a JouleClaw deployment as a
|
|
provenance graph without any JouleClaw-specific knowledge beyond
|
|
this one IRI mapping.
|
|
|
|
## Conformance with existing wire forms
|
|
|
|
The vocabulary is designed so that **a v1 JouleClaw receipt is a
|
|
valid JSON-LD document by adding a single `@context` field**:
|
|
|
|
```jsonld
|
|
{
|
|
"@context": "https://jouleclaw.transaction.science/vocab/v1.jsonld",
|
|
"jc_receipt": "1",
|
|
"id": "rcpt-0001",
|
|
"closed_at": "2026-06-02T12:00:00Z",
|
|
"input_hash": "b1883b...",
|
|
"tier": "L3",
|
|
"joules_uj": 3500000,
|
|
"energy_provenance": "ModelBased",
|
|
"steward": "did:key:zAlpha"
|
|
}
|
|
```
|
|
|
|
A JSON-LD parser expands the above into typed RDF triples
|
|
referencing this vocabulary. The `tier: "L3"` becomes
|
|
`<rcpt-0001> jc:tier jc:Model .`, the `energy_provenance:
|
|
"ModelBased"` becomes `<rcpt-0001> jc:energyProvenance
|
|
jc:ModelBased .`, etc. Same bytes, same signature, but now the
|
|
output is queryable.
|
|
|
|
## Versioning
|
|
|
|
A future major version of the vocabulary publishes under
|
|
`https://jouleclaw.transaction.science/vocab/v2#`. v1 IRIs remain
|
|
resolvable forever — the open-standard's "names are final" rule
|
|
(per `[[feedback-open-standards-framing]]`) applies here too.
|
|
|
|
## Licence
|
|
|
|
CC-BY-4.0 (consistent with the JouleClaw specification text).
|