# 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).