From bf88c3bb50be7101916ee06ad16d9299a8dec69f Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 22 Apr 2026 15:22:01 -0400 Subject: [PATCH 1/3] docs: update README for sourceos-shell contract families --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4d1ed7c..a415bcf 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ ## 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`. @@ -20,7 +20,7 @@ A metadata governance platform can only unify data meaning, policy, provenance, ## Repository layout -``` +```text sourceos-spec/ ├── README.md # This file ├── ARCHITECTURE.md # Two-plane architecture, schema families, lifecycle @@ -33,7 +33,7 @@ sourceos-spec/ ├── asyncapi.yaml # Metadata-plane event channels ├── asyncapi.agent-plane.patch.yaml # Agent-plane event channels │ -├── schemas/ # 54 JSON Schema (draft 2020-12) files +├── schemas/ # 64 JSON Schema (draft 2020-12) files │ └── README.md # Schema catalog and URN patterns │ ├── examples/ # Conforming example payloads (one per type) @@ -50,19 +50,20 @@ sourceos-spec/ ## Schema families -The 54 schemas are organised into six families that map directly to the Open Metadata Types taxonomy areas: +The current schema set is organised into families that map directly to the platform layers and exchange surfaces: | # | Family | Key schemas | |---|--------|-------------| | 1 | **Physical Assets** | `Connector`, `PhysicalAsset` | | 2 | **Glossary** | `GlossaryTerm`, `AuthorityLink` | | 3 | **Governance** | `Policy`, `Rule`, `PolicyCondition`, `PolicyDecision`, `CapabilityToken`, `Obligation`, `Exception` | -| 4 | **Collaboration** | `Comment`, `Rating`, `Community` | +| 4 | **Collaboration** | `Comment`, `Rating`, `Community`, `CommentSignal` | | 5 | **Models / Schemas** | `SchemaDefinition`, `EntityField`, `Field`, `ValidValues`, `TagAssignment`, `QualityMetric`, `ProfileStats` | | 6 | **Agreements** | `Agreement`, `Party` | | + | **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` | +| + | **Shell / Document / Publication** | `ArtifactManifest`, `SignedArtifact`, `PdfValidationReport`, `AnnotationExport`, `RunReport`, `NoetherDiagnostic`, `PublishDecision`, `MirrorReceipt`, `SearchRouteDecision` | --- @@ -128,4 +129,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 d4da79d3eda36c128948f4a20004085ac2d54ac0 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 22 Apr 2026 15:24:34 -0400 Subject: [PATCH 2/3] docs: update schema catalog for shell/document/publication contracts --- schemas/README.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/schemas/README.md b/schemas/README.md index 5a98037..3156594 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -1,6 +1,6 @@ # 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 all 64 JSON Schema (draft 2020-12) files that make up the SourceOS/SociOS Typed Contracts specification. --- @@ -10,9 +10,12 @@ This directory contains all 54 JSON Schema (draft 2020-12) files that make up th |------|------|-----------| | `AgentSession.json` | AgentSession | `urn:srcos:session:` | | `Agreement.json` | Agreement | `urn:srcos:agreement:` | +| `AnnotationExport.json` | AnnotationExport | `urn:srcos:schema:AnnotationExport` | +| `ArtifactManifest.json` | ArtifactManifest | `urn:srcos:schema:ArtifactManifest` | | `AuthorityLink.json` | AuthorityLink | _(sub-object, no top-level id)_ | | `CapabilityToken.json` | CapabilityToken | _(plain `tokenId` string)_ | | `Comment.json` | Comment | `urn:srcos:comment:` | +| `CommentSignal.json` | CommentSignal | `urn:srcos:schema:CommentSignal` | | `Community.json` | Community | `urn:srcos:community:` | | `Connector.json` | Connector | `urn:srcos:connector:` | | `DataRef.json` | DataRef | _(sub-object, no top-level id)_ | @@ -31,10 +34,13 @@ This directory contains all 54 JSON Schema (draft 2020-12) files that make up th | `MappingEvidence.json` | MappingEvidence | _(sub-object inside MappingSpec)_ | | `MappingSpec.json` | MappingSpec | `urn:srcos:mapping:` | | `MemoryEntry.json` | MemoryEntry | `urn:srcos:memory:` | +| `MirrorReceipt.json` | MirrorReceipt | `urn:srcos:schema:MirrorReceipt` | +| `NoetherDiagnostic.json` | NoetherDiagnostic | `urn:srcos:schema:NoetherDiagnostic` | | `ObjectContext.json` | ObjectContext | _(sub-object, no id)_ | | `ObjectSelector.json` | ObjectSelector | _(sub-object inside Policy scope)_ | | `Obligation.json` | Obligation | _(sub-object, no id)_ | | `Party.json` | Party | `urn:srcos:party:` | +| `PdfValidationReport.json` | PdfValidationReport | `urn:srcos:schema:PdfValidationReport` | | `PhysicalAsset.json` | PhysicalAsset | `urn:srcos:asset:` | | `Policy.json` | Policy | `urn:srcos:policy:` | | `PolicyBinding.json` | PolicyBinding | _(sub-object inside WorkflowSpec)_ | @@ -42,15 +48,19 @@ This directory contains all 54 JSON Schema (draft 2020-12) files that make up th | `PolicyDecision.json` | PolicyDecision | `urn:srcos:decision:` | | `ProfileStats.json` | ProfileStats | _(sub-object inside Field.quality)_ | | `ProvenanceRecord.json` | ProvenanceRecord | `urn:srcos:prov:` | +| `PublishDecision.json` | PublishDecision | `urn:srcos:schema:PublishDecision` | | `QualityMetric.json` | QualityMetric | _(sub-object inside Field.quality)_ | | `Rating.json` | Rating | `urn:srcos:rating:` | | `ReleaseReceipt.json` | ReleaseReceipt | `urn:srcos:release-receipt:` | | `RolloutPolicy.json` | RolloutPolicy | `urn:srcos:rollout:` | | `Rule.json` | Rule | _(sub-object inside Policy)_ | | `RunRecord.json` | RunRecord | `urn:srcos:run:` | +| `RunReport.json` | RunReport | `urn:srcos:schema:RunReport` | | `SchemaDefinition.json` | SchemaDefinition | `urn:srcos:schema:` | +| `SearchRouteDecision.json` | SearchRouteDecision | `urn:srcos:schema:SearchRouteDecision` | | `SessionReceipt.json` | SessionReceipt | `urn:srcos:receipt:session:` | | `SessionReview.json` | SessionReview | `urn:srcos:session-review:` | +| `SignedArtifact.json` | SignedArtifact | `urn:srcos:schema:SignedArtifact` | | `SkillManifest.json` | SkillManifest | `urn:srcos:skill:` | | `SubjectContext.json` | SubjectContext | _(sub-object, no id)_ | | `SubjectSelector.json` | SubjectSelector | _(sub-object inside Policy scope)_ | @@ -101,6 +111,7 @@ This directory contains all 54 JSON Schema (draft 2020-12) files that make up th | Schema | Description | |--------|-------------| | `Comment` | A free-text annotation on any addressable object | +| `CommentSignal` | A reviewer or author signal payload exposing genuine/sarcasm/experience state | | `Rating` | A 1–5 star rating on any addressable object | | `Community` | A named group of subject URNs | @@ -163,6 +174,20 @@ 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 | +### Shell / Document / Publication + +| Schema | Description | +|--------|-------------| +| `ArtifactManifest` | Canonical manifest for a derived shell/document artifact | +| `SignedArtifact` | Signature metadata associated with a signed artifact | +| `PdfValidationReport` | Validation report produced for a derived PDF artifact | +| `AnnotationExport` | Export bundle for PDF/HTML review annotations | +| `RunReport` | Publication-ready summary of a workflow or execution run | +| `NoetherDiagnostic` | Measured conservation or invariance reading for a declared model charge | +| `PublishDecision` | Publish-lane decision across knowledge/value/ecosystem openness | +| `MirrorReceipt` | Receipt showing artifact mirroring outcome for a downstream channel | +| `SearchRouteDecision` | Routing decision for scope-based shell search dispatch | + --- ## Validation @@ -183,4 +208,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 c2ca6eff4b1c0beba25bea9e98e65bc2c9325f0c Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 22 Apr 2026 15:26:13 -0400 Subject: [PATCH 3/3] docs: update examples catalog for shell/document/publication examples --- examples/README.md | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/examples/README.md b/examples/README.md index 90ef4ef..56f8acc 100644 --- a/examples/README.md +++ b/examples/README.md @@ -6,9 +6,11 @@ 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. -``` +The example set now also includes shell/document/publication objects so the same storyline can extend into artifact derivation, signing, validation, annotation export, run reporting, publish decisions, and mirror receipts. + +```text connector.json ──► asset.json │ ▼ @@ -37,6 +39,15 @@ agent_session.json ──► execution_decision.json ──► session_recei │ ▼ session_review.json + +artifact-manifest.json ──► signed-artifact.json + │ │ + ▼ ▼ +pdf-validation-report.json publish-decision.json + │ │ + └──────────────► mirror-receipt.json + +annotation-export.json ──► run-report.json ──► noether-diagnostic.json ``` --- @@ -47,8 +58,11 @@ agent_session.json ──► execution_decision.json ──► session_recei |------|------------|-------------| | `agreement.json` | Agreement | Default personal-data agreement | | `agent_session.json` | AgentSession | An executor session running the obfuscation workflow | +| `annotation-export.json` | AnnotationExport | Export bundle for annotations captured from review surfaces | +| `artifact-manifest.json` | ArtifactManifest | Manifest describing a derived shell/document artifact | | `asset.json` | PhysicalAsset | Lakehouse asset for curated health observations | | `capability_token.json` | CapabilityToken | Access token scoped to the health dataset export operation | +| `comment-signal.json` | CommentSignal | Example author/reviewer signal payload | | `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 | @@ -63,18 +77,24 @@ agent_session.json ──► execution_decision.json ──► session_recei | `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 | +| `mirror-receipt.json` | MirrorReceipt | Receipt for a mirrored artifact publication | +| `noether-diagnostic.json` | NoetherDiagnostic | Example conservation/invariance diagnostic reading | +| `pdf-validation-report.json` | PdfValidationReport | Validation results for a derived PDF artifact | | `policy.json` | Policy | Health export must be obfuscated | | `provenance.json` | ProvenanceRecord | Provenance record for the obfuscation run | +| `publish-decision.json` | PublishDecision | Publish-lane decision across openness dimensions | | `rating.json` | Rating | A 5-star rating on the health observations dataset | | `release_receipt.json` | ReleaseReceipt | Release receipt for spec version 2.0.0 | | `rollout_policy.json` | RolloutPolicy | Rollout rules for the obfuscation experiment flag | +| `run-report.json` | RunReport | Publication-oriented summary of a completed run | | `run.json` | RunRecord | The obfuscation workload run record | | `schema.json` | SchemaDefinition | The schema for health observations | +| `search-route-decision.json` | SearchRouteDecision | Scope-based shell routing decision | | `session_receipt.json` | SessionReceipt | Receipt for the completed agent session | | `session_review.json` | SessionReview | Post-session learning review | +| `signed-artifact.json` | SignedArtifact | Signature metadata for a signed artifact | | `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 | | `workflow_spec.json` | WorkflowSpec | The health-data obfuscation workflow | --- @@ -108,8 +128,8 @@ done ## Adding a new example -See [CONTRIBUTING.md](../CONTRIBUTING.md#writing-examples) for the full guide. Key rules: -1. The filename must be the schema `title` lowercased, e.g. `AgentSession` → `agent_session.json`. +See [CONTRIBUTING.md](../CONTRIBUTING.md#writing-examples) for the full guide. Key rules: +1. The filename must be the schema `title` lowercased or the established example naming convention, e.g. `AgentSession` → `agent_session.json`. 2. All required fields must be present and valid. 3. Use existing cross-reference URNs from this directory so the example set stays coherent. 4. Run `ajv validate` before committing.