Watch

Transaction Science 25b5a522f5 jouleclaw vocab v1: stable IRIs + JSON-LD context + Turtle ontology

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.

2026-06-02 11:10:11 -04:00

4.3 KiB

Raw Permalink Blame History

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`	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`	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:

{
  "@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).

4.3 KiB Raw Permalink Blame History