From a857158d582d2c9d8f4dcb795be27764f2b1ab64 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 17 Apr 2026 21:55:51 -0400 Subject: [PATCH 1/4] docs(spec): fold fog family into root README index --- README.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 4d1ed7c..44c42cd 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # SourceOS/SociOS Typed Contracts -**SourceOS/SociOS Typed Contracts** is the canonical, machine-readable specification for the SourceOS metadata governance platform and the SociOS agent plane. It defines the full set of JSON Schemas, an OpenAPI REST surface, an AsyncAPI event spine, and a JSON-LD / Hydra semantic overlay that together make up the "contract layer" every implementation component must satisfy. +**SourceOS/SociOS Typed Contracts** is the canonical, machine-readable specification for the SourceOS metadata governance platform and the SociOS agent plane. It defines the full set of JSON Schemas, additive OpenAPI / AsyncAPI patch fragments, and a JSON-LD / Hydra semantic overlay that together make up the "contract layer" every implementation component must satisfy. > **Spec version:** `2.0.0`  |  **License:** see [LICENSE](LICENSE) @@ -8,19 +8,19 @@ ## Why this repository exists -A metadata governance platform can only unify data meaning, policy, provenance, and agent execution if every component agrees on the *shape* of the objects it exchanges. This repository is that shared agreement. Downstream consumers include: +A metadata governance platform can only unify data meaning, policy, provenance, and agent execution if every component agrees on the *shape* of the objects it exchanges. This repository is that shared agreement. Downstream consumers include: -- **API services** — scaffolded from `openapi.yaml` (metadata plane) and `openapi.agent-plane.patch.yaml` (agent plane). -- **Event consumers** — Kafka topics declared in `asyncapi.yaml` + `asyncapi.agent-plane.patch.yaml`. +- **API services** — scaffolded from `openapi.yaml` plus additive patch fragments such as `openapi.agent-plane.patch.yaml` and `openapi.fog.patch.yaml`. +- **Event consumers** — Kafka topics declared in `asyncapi.yaml` plus additive channel fragments such as `asyncapi.agent-plane.patch.yaml` and `asyncapi.fog.patch.yaml`. - **Validators** — AJV (Node.js) or `jsonschema` (Python) loaded from `schemas/`. - **Code generators** — TypeScript types via [quicktype](https://quicktype.io); Python models via [datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator). -- **Semantic tooling** — JSON-LD context + Hydra API documentation in `semantic/`. +- **Semantic tooling** — JSON-LD context + Hydra API documentation in `semantic/`, including additive vocabulary seeds such as `semantic/fog-vocabulary.jsonld`. --- ## Repository layout -``` +```text sourceos-spec/ ├── README.md # This file ├── ARCHITECTURE.md # Two-plane architecture, schema families, lifecycle @@ -30,27 +30,31 @@ sourceos-spec/ │ ├── openapi.yaml # Metadata-plane REST API (v2) ├── openapi.agent-plane.patch.yaml # Additive agent-plane REST endpoints +├── openapi.fog.patch.yaml # Additive fog-layer REST endpoints ├── asyncapi.yaml # Metadata-plane event channels ├── asyncapi.agent-plane.patch.yaml # Agent-plane event channels +├── asyncapi.fog.patch.yaml # Fog-layer event channels │ -├── schemas/ # 54 JSON Schema (draft 2020-12) files +├── schemas/ # Top-level JSON Schema files (draft 2020-12) │ └── README.md # Schema catalog and URN patterns │ ├── examples/ # Conforming example payloads (one per type) │ └── README.md │ ├── semantic/ # JSON-LD context + Hydra API documentation -│ └── README.md +│ ├── README.md +│ └── fog-vocabulary.jsonld # Additive fog vocabulary seed │ └── docs/ - └── adr/ # Architecture Decision Records + ├── adr/ # Architecture Decision Records + └── contract-additions/ # Discoverability notes for additive families ``` --- ## Schema families -The 54 schemas are organised into six families that map directly to the Open Metadata Types taxonomy areas: +The schemas are organised into domain-oriented families that map to the SourceOS / SociOS contract surface: | # | Family | Key schemas | |---|--------|-------------| @@ -63,6 +67,7 @@ The 54 schemas are organised into six families that map directly to the Open Met | + | **Execution / Provenance** | `Dataset`, `RunRecord`, `WorkflowSpec`, `WorkflowNode`, `WorkflowEdge`, `WorkloadSpec`, `DataSphere`, `ProvenanceRecord`, `EventEnvelope`, `MappingSpec` | | + | **Agent Plane** | `AgentSession`, `ExecutionDecision`, `ExecutionSurface`, `SkillManifest`, `MemoryEntry`, `SessionReceipt`, `SessionReview`, `TelemetryEvent`, `FrustrationSignal` | | + | **Release / Experiments** | `ExperimentFlag`, `RolloutPolicy`, `ReleaseReceipt` | +| + | **Fog Layer** | `Topic`, `TopicEnvelope`, `ReplicationPolicy`, `ContentRef`, `Offer`, `WorkOrder`, `UsageReceipt`, `SettlementEvent` | --- @@ -128,4 +133,3 @@ fastapi-codegen --input openapi.yaml --output app/ ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for schema authoring conventions, the URN naming guide, and the pull-request checklist. - From a832028184101141ed198cd53efe3fdefb998a53 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 17 Apr 2026 22:00:26 -0400 Subject: [PATCH 2/4] docs(spec): fold fog family into schema catalog --- schemas/README.md | 48 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/schemas/README.md b/schemas/README.md index 5a98037..1b4efd8 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -1,6 +1,29 @@ # Schema Catalog -This directory contains all 54 JSON Schema (draft 2020-12) files that make up the SourceOS/SociOS Typed Contracts specification. +This directory contains the JSON Schema (draft 2020-12) files that make up the SourceOS/SociOS Typed Contracts specification. + +--- + +## Recent additions — Fog Layer + +The FogVault / FogCompute contract family adds the following top-level schemas: + +| File | Type | URN prefix | +|------|------|-----------| +| `ContentRef.json` | ContentRef | _(digest-based content reference)_ | +| `Offer.json` | Offer | `urn:srcos:offer:` | +| `ReplicationPolicy.json` | ReplicationPolicy | _(top-level policy object)_ | +| `SettlementEvent.json` | SettlementEvent | `urn:srcos:settlement:` | +| `Topic.json` | Topic | `urn:srcos:topic:` | +| `TopicEnvelope.json` | TopicEnvelope | `urn:srcos:topic-entry:` | +| `UsageReceipt.json` | UsageReceipt | `urn:srcos:receipt:usage:` | +| `WorkOrder.json` | WorkOrder | `urn:srcos:workorder:` | + +These types support: +- append-only Merkle-log topics +- explicit replication/retention policy +- content-addressed storage references +- compute offers, work orders, receipts, and optional settlement mappings --- @@ -15,6 +38,7 @@ This directory contains all 54 JSON Schema (draft 2020-12) files that make up th | `Comment.json` | Comment | `urn:srcos:comment:` | | `Community.json` | Community | `urn:srcos:community:` | | `Connector.json` | Connector | `urn:srcos:connector:` | +| `ContentRef.json` | ContentRef | _(digest-based content reference)_ | | `DataRef.json` | DataRef | _(sub-object, no top-level id)_ | | `DataSphere.json` | DataSphere | `urn:srcos:sphere:` | | `Dataset.json` | Dataset | `urn:srcos:dataset:` | @@ -34,6 +58,7 @@ This directory contains all 54 JSON Schema (draft 2020-12) files that make up th | `ObjectContext.json` | ObjectContext | _(sub-object, no id)_ | | `ObjectSelector.json` | ObjectSelector | _(sub-object inside Policy scope)_ | | `Obligation.json` | Obligation | _(sub-object, no id)_ | +| `Offer.json` | Offer | `urn:srcos:offer:` | | `Party.json` | Party | `urn:srcos:party:` | | `PhysicalAsset.json` | PhysicalAsset | `urn:srcos:asset:` | | `Policy.json` | Policy | `urn:srcos:policy:` | @@ -45,23 +70,29 @@ This directory contains all 54 JSON Schema (draft 2020-12) files that make up th | `QualityMetric.json` | QualityMetric | _(sub-object inside Field.quality)_ | | `Rating.json` | Rating | `urn:srcos:rating:` | | `ReleaseReceipt.json` | ReleaseReceipt | `urn:srcos:release-receipt:` | +| `ReplicationPolicy.json` | ReplicationPolicy | _(top-level policy object)_ | | `RolloutPolicy.json` | RolloutPolicy | `urn:srcos:rollout:` | | `Rule.json` | Rule | _(sub-object inside Policy)_ | | `RunRecord.json` | RunRecord | `urn:srcos:run:` | | `SchemaDefinition.json` | SchemaDefinition | `urn:srcos:schema:` | | `SessionReceipt.json` | SessionReceipt | `urn:srcos:receipt:session:` | | `SessionReview.json` | SessionReview | `urn:srcos:session-review:` | +| `SettlementEvent.json` | SettlementEvent | `urn:srcos:settlement:` | | `SkillManifest.json` | SkillManifest | `urn:srcos:skill:` | | `SubjectContext.json` | SubjectContext | _(sub-object, no id)_ | | `SubjectSelector.json` | SubjectSelector | _(sub-object inside Policy scope)_ | | `TagAssignment.json` | TagAssignment | _(sub-object inside Field/GlossaryTerm)_ | | `TelemetryEvent.json` | TelemetryEvent | `urn:srcos:telemetry:` | +| `Topic.json` | Topic | `urn:srcos:topic:` | +| `TopicEnvelope.json` | TopicEnvelope | `urn:srcos:topic-entry:` | | `Trigger.json` | Trigger | _(sub-object inside WorkflowSpec)_ | +| `UsageReceipt.json` | UsageReceipt | `urn:srcos:receipt:usage:` | | `ValidValues.json` | ValidValues | _(sub-object inside EntityField)_ | | `WorkflowEdge.json` | WorkflowEdge | _(sub-object inside WorkflowSpec)_ | | `WorkflowNode.json` | WorkflowNode | _(sub-object inside WorkflowSpec)_ | | `WorkflowSpec.json` | WorkflowSpec | `urn:srcos:workflow:` | | `WorkloadSpec.json` | WorkloadSpec | `urn:srcos:workload:` | +| `WorkOrder.json` | WorkOrder | `urn:srcos:workorder:` | --- @@ -163,6 +194,19 @@ This directory contains all 54 JSON Schema (draft 2020-12) files that make up th | `RolloutPolicy` | Audience-based percentage rollout rules for an `ExperimentFlag` | | `ReleaseReceipt` | A verified release record with artifact hashes and gate check results | +### Fog Layer + +| Schema | Description | +|--------|-------------| +| `Topic` | An append-only topic contract for FogVault channels | +| `TopicEnvelope` | A typed append-only entry envelope for topic events and payloads | +| `ReplicationPolicy` | Replication, retention, and compaction policy for a fog topic | +| `ContentRef` | A content-addressed reference to blobs, chunks, or manifests | +| `Offer` | A FogCompute provider offer advertising resources and constraints | +| `WorkOrder` | A FogCompute request describing workload, inputs, outputs, and verification mode | +| `UsageReceipt` | A worker-emitted usage and output receipt for a completed work order | +| `SettlementEvent` | An optional settlement mapping from receipt to credits/tokens/backend | + --- ## Validation @@ -183,4 +227,4 @@ done ## Versioning -Schema evolution follows [Semantic Versioning](https://semver.org/). See [CONTRIBUTING.md](../CONTRIBUTING.md#breaking-vs-additive-changes) for the full policy and [CHANGELOG.md](../CHANGELOG.md) for the history. +Schema evolution follows [Semantic Versioning](https://semver.org/). See [CONTRIBUTING.md](../CONTRIBUTING.md#breaking-vs-additive-changes) for the full policy and [CHANGELOG.md](../CHANGELOG.md) for the history. From 241c5fd8a0591c1b053c0b1f3629e12799f1c845 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 17 Apr 2026 22:05:01 -0400 Subject: [PATCH 3/4] docs(spec): fold fog examples into examples index --- examples/README.md | 46 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 34 insertions(+), 12 deletions(-) diff --git a/examples/README.md b/examples/README.md index 90ef4ef..404934c 100644 --- a/examples/README.md +++ b/examples/README.md @@ -6,9 +6,9 @@ This directory contains one conforming JSON example payload for each top-level s ## What the examples show -The examples are designed to tell a coherent end-to-end story: a personal health dataset is catalogued, governed, transformed by an obfuscation workload, and released — all within an agent session. They share cross-reference URNs so you can trace the full lifecycle: +The examples are designed to tell a coherent end-to-end story: a personal health dataset is catalogued, governed, transformed by an obfuscation workload, and released — all within an agent session. They share cross-reference URNs so you can trace the full lifecycle: -``` +```text connector.json ──► asset.json │ ▼ @@ -41,6 +41,23 @@ agent_session.json ──► execution_decision.json ──► session_recei --- +## Recent additions — Fog Layer examples + +The fog example set illustrates the new FogVault / FogCompute contract family: + +| File | Schema type | Description | +|------|------------|-------------| +| `content_ref.json` | ContentRef | Content-addressed reference for fog blobs / manifests | +| `topic.json` | Topic | FogVault topic definition with replication and encryption metadata | +| `topic_envelope.json` | TopicEnvelope | Append-only topic entry envelope with integrity and encryption metadata | +| `replication_policy.json` | ReplicationPolicy | Replica / ack / retention / compaction policy example | +| `offer.json` | Offer | FogCompute provider offer advertising local resources | +| `workorder.json` | WorkOrder | FogCompute request with image, inputs, outputs, and verification mode | +| `usage_receipt.json` | UsageReceipt | Worker-emitted execution receipt with metered resource usage | +| `settlement_event.json` | SettlementEvent | Optional mapping from receipt to settlement backend / credits | + +--- + ## File index | File | Schema type | Description | @@ -52,30 +69,37 @@ agent_session.json ──► execution_decision.json ──► session_recei | `comment.json` | Comment | A review note on a field mapping | | `community.json` | Community | The data-governance team community | | `connector.json` | Connector | A local S3 connector | +| `content_ref.json` | ContentRef | Content-addressed reference for fog blobs / manifests | | `dataset.json` | Dataset | Personal health observations dataset | | `data_sphere.json` | DataSphere | The personal-curated execution environment | -| `policy_decision.json` | PolicyDecision | An `export` permit decision with an obfuscation obligation | | `execution_decision.json` | ExecutionDecision | Agent allow-decision for a tool invocation | -| `experiment_flag.json` | ExperimentFlag | A feature flag for the new obfuscation algorithm | | `event_envelope.json` | EventEnvelope | Event published when the run completes | +| `experiment_flag.json` | ExperimentFlag | A feature flag for the new obfuscation algorithm | | `field.json` | Field | The `patient.dateOfBirth` field with PII tags and quality metrics | | `frustration_signal.json` | FrustrationSignal | A frustration signal from a repeated-failure condition | | `glossary.json` | GlossaryTerm | Glossary term for "Date of Birth" | | `mapping.json` | MappingSpec | A field mapping between two dataset fields | | `memory_entry.json` | MemoryEntry | A learned memory entry from an agent session | +| `offer.json` | Offer | FogCompute provider offer | | `policy.json` | Policy | Health export must be obfuscated | +| `policy_decision.json` | PolicyDecision | An `export` permit decision with an obfuscation obligation | | `provenance.json` | ProvenanceRecord | Provenance record for the obfuscation run | | `rating.json` | Rating | A 5-star rating on the health observations dataset | | `release_receipt.json` | ReleaseReceipt | Release receipt for spec version 2.0.0 | +| `replication_policy.json` | ReplicationPolicy | Fog topic replication/retention policy example | | `rollout_policy.json` | RolloutPolicy | Rollout rules for the obfuscation experiment flag | | `run.json` | RunRecord | The obfuscation workload run record | | `schema.json` | SchemaDefinition | The schema for health observations | | `session_receipt.json` | SessionReceipt | Receipt for the completed agent session | | `session_review.json` | SessionReview | Post-session learning review | +| `settlement_event.json` | SettlementEvent | Optional receipt-to-settlement mapping | | `skill_manifest.json` | SkillManifest | The obfuscation skill manifest | | `telemetry_event.json` | TelemetryEvent | An informational telemetry event from the agent session | -| `capability_token.json` | CapabilityToken | Capability token for the export operation | +| `topic.json` | Topic | FogVault topic definition | +| `topic_envelope.json` | TopicEnvelope | FogVault append-only entry envelope | | `workflow_spec.json` | WorkflowSpec | The health-data obfuscation workflow | +| `workorder.json` | WorkOrder | FogCompute work order | +| `usage_receipt.json` | UsageReceipt | FogCompute execution receipt | --- @@ -92,14 +116,12 @@ ajv validate -s ../schemas/Dataset.json -d dataset.json cd .. for example in examples/*.json; do name=$(basename "$example" .json) - # Find matching schema (PascalCase title) python3 - < Date: Fri, 17 Apr 2026 22:06:36 -0400 Subject: [PATCH 4/4] docs(spec): fold fog vocabulary into semantic index --- semantic/README.md | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/semantic/README.md b/semantic/README.md index 37642c9..8f4946e 100644 --- a/semantic/README.md +++ b/semantic/README.md @@ -1,6 +1,6 @@ # Semantic Overlay -This directory provides the JSON-LD and Hydra semantic overlay for the SourceOS/SociOS specification. These files make the schema types and REST API self-describing to Linked Data tooling. +This directory provides the JSON-LD and Hydra semantic overlay for the SourceOS/SociOS specification. These files make the schema types and REST API self-describing to Linked Data tooling. --- @@ -8,8 +8,25 @@ This directory provides the JSON-LD and Hydra semantic overlay for the SourceOS/ | File | Purpose | |------|---------| -| `context.jsonld` | JSON-LD `@context` mapping all 54 schema type names to stable IRIs under `https://schemas.srcos.ai/v2/` | +| `context.jsonld` | JSON-LD `@context` mapping schema type names to stable IRIs under `https://schemas.srcos.ai/v2/` | | `hydra.jsonld` | A `hydra:ApiDocumentation` document describing the REST API's supported classes and operations | +| `fog-vocabulary.jsonld` | Additive fog vocabulary seed for FogVault / FogCompute types and key predicates | + +--- + +## Recent additions — Fog vocabulary + +The fog layer currently contributes a seed semantic vocabulary in `fog-vocabulary.jsonld` covering: +- `Topic` +- `TopicEnvelope` +- `ReplicationPolicy` +- `ContentRef` +- `Offer` +- `WorkOrder` +- `UsageReceipt` +- `SettlementEvent` + +This vocabulary is intentionally lightweight and is expected to be folded into the broader semantic overlay as the fog contract family stabilizes. --- @@ -21,8 +38,7 @@ Include the context in any JSON document to make it a JSON-LD document: { "@context": "https://schemas.srcos.ai/v2/context.jsonld", "@type": "Dataset", - "id": "urn:srcos:dataset:health_obs", - ... + "id": "urn:srcos:dataset:health_obs" } ``` @@ -40,14 +56,14 @@ Or embed the context inline: The context maps: - `id` → `@id` (every `id` field becomes the node's IRI) - `type` → `@type` (every `type` field becomes the node's RDF type) -- All 54 schema type names to `srcos:` IRIs -- Selected cross-vocabulary terms: `prov:wasGeneratedBy`, `prov:used`, `prov:wasAssociatedWith` +- schema type names to `srcos:` IRIs +- selected cross-vocabulary terms such as `prov:wasGeneratedBy`, `prov:used`, `prov:wasAssociatedWith` --- ## `hydra.jsonld` — Hydra API documentation -The Hydra document is a machine-readable API description that extends the JSON-LD context. It can be served at `/.well-known/hydra` to make the API self-describing. +The Hydra document is a machine-readable API description that extends the JSON-LD context. It can be served at `/.well-known/hydra` to make the API self-describing. The document lists every resource class supported by the API with its supported operations (HTTP methods), expected inputs, and returned types. @@ -82,7 +98,7 @@ When adding a new first-class schema type: 1. Add a mapping to `context.jsonld`: `"NewType": "srcos:NewType"` 2. Add a `hydra:supportedClass` entry to `hydra.jsonld` with at minimum `hydra:title`, `hydra:description`, and the applicable `hydra:supportedOperation` entries. -3. Update this README's file table. +3. Update this README's file table and any additive vocabulary seeds if the new type is being staged incrementally. See [CONTRIBUTING.md](../CONTRIBUTING.md#6-update-the-semantic-context-if-needed) for the full guide.