Shared contracts and schemas

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

These JSON Schemas (draft 2020-12) are the typed form of the contracts that the design pages describe in prose. Each is registered in the architecture model (model/descriptors.yaml) so that agents, workflows and services can reference a contract by its descriptor id; the generated descriptors catalog lists them with owners and versions. Content never travels inside a contract: records carry hashes and references into the artifact store.

Descriptor id	Schema	Owner	Used by
execution-scope-v1	execution-scope.schema.json	BC-33 Factory Tenancy	Every command, event, tool and model invocation, retrieval request and usage record
run-submission-v1	run-submission.schema.json	BC-03 Run Control	POST /factory/runs, CLI, VS Code, A2A inbound tasks
resolved-execution-snapshot-v1	resolved-execution-snapshot.schema.json	BC-03 Run Control	Workers execute against it; immutable after acceptance
run-event-envelope-v1	run-event-envelope.schema.json	BC-42 Data & Event Foundations	Every integration event (ADR-0014)
approval-request-v1, approval-decision-v1	approval.schema.json	BC-03 (instances), BC-20 (policy)	Review Center, POST /factory/approvals/{id}/decision
acquire-lease-v1, lease-v1, attempt-outcome-v1	attempt-outcome.schema.json	BC-03 / BC-06	Runtime worker ↔ Run Control gRPC
tool-invocation-v1, tool-receipt-v1	tool-invocation.schema.json	BC-08 Tool Execution	Governed executor (GW-05), MCP servers (ADR-0022)
model-invocation-v1, model-receipt-v1	model-invocation.schema.json	BC-07 Model Access	Model gateway (GW-04)
usage-reservation-v1, usage-record-v1	usage-record.schema.json	BC-05 Usage Accounting	Budgets, meters, billing (ADR-0020)
policy-decision-v1	policy-decision.schema.json	BC-18 Policy	Attached to receipts and approval requests
release-manifest-v1	release-manifest.schema.json	BC-04 Asset Publication	Registries, release loading, agent cards (ADR-0023)
context-package-v1	context-snapshot.schema.json	BC-09 Context Assembly	Attempts; citations in reports (ADR-0013)
artifact-v1	artifact.schema.json	BC-12 Artifacts & Lineage	Every produced output; evaluation records
audit-evidence-v1	audit-evidence.schema.json	BC-19 Audit	Governance-relevant actions; 7-year retention
agent-task-contract-v1	agent-task-contract.schema.json	BC-06 Execution	What an agent receives per attempt
change-set-v1, pull-request-proposal-v1	change-set.schema.json	Software Factory pack	Engineering agents; PR creation is a shared-write action
agent-manifest-v1, skill-manifest-v1, tool-descriptor-v1, workflow-definition-v1, model-profile-v1	asset-manifests.schema.json	BC-04 / BC-08 / BC-38 / BC-07	Authoring in Git; compiled into release manifests

Conventions

• Identifiers are UUIDs for runtime objects (runs, steps, attempts, leases, approvals, invocations, artifacts) and stable kebab-case ids for assets (agents, skills, tools, workflows, profiles). Hashes are SHA-256 over a canonical serialization.
• Trusted scope fields are set by the backend from the authenticated context; a schema that carries scope or tenantId never accepts it from a client body.
• Idempotency keys are unique per scope and operation: the same key with the same canonical input returns the prior result; the same key with a different input is a conflict (HTTP 409).
• Versioning is additive: a new field arrives in a new schema version; old versions stay readable for a stated window (ADR-0014).
• Every receipt (attempt, tool, model, usage) has a receiptHash; a run's outcome hash is derived from its receipts, which makes "what ran and what it consumed" reproducible without content.

Relation to earlier reference pages

Event envelope, metadata schema, artifact metadata, context package schema and agent task contract are the 2025–2026 prose pages; the schemas here supersede their field lists. The prose pages are kept for their explanations and point here.

Blueprint schemas (design plan B1, 2026-10-09)

Every blueprint kind of the Software Factory pack has a JSON Schema; the common metadata is shared. Validation rules beyond the schema and the generation outputs per kind are in the blueprints catalog.

Descriptor id	Schema	Kind
blueprint-common-v1	blueprint-common.schema.json	metadata shared by every kind
blueprint-vision-v1	blueprint-vision.schema.json	Vision Blueprint
blueprint-service-v1	blueprint-service.schema.json	Service Blueprint
blueprint-module-v1	blueprint-module.schema.json	Module Blueprint
blueprint-frontend-v1	blueprint-frontend.schema.json	Frontend Blueprint
blueprint-frontend-library-v1	blueprint-frontend-library.schema.json	Frontend Library Blueprint
blueprint-backend-library-v1	blueprint-backend-library.schema.json	Backend Library Blueprint
blueprint-backend-api-library-v1	blueprint-backend-api-library.schema.json	Backend API Library Blueprint
blueprint-api-gateway-v1	blueprint-api-gateway.schema.json	API Gateway Blueprint
blueprint-database-v1	blueprint-database.schema.json	Database Blueprint
blueprint-security-v1	blueprint-security.schema.json	Security Blueprint
blueprint-pipeline-v1	blueprint-pipeline.schema.json	Pipeline Blueprint
blueprint-observability-v1	blueprint-observability.schema.json	Observability Blueprint
blueprint-integration-v1	blueprint-integration.schema.json	Integration Blueprint
blueprint-infrastructure-v1	blueprint-infrastructure.schema.json	Infrastructure Blueprint
blueprint-documentation-v1	blueprint-documentation.schema.json	Documentation Blueprint
blueprint-localization-v1	blueprint-localization.schema.json	Localization Blueprint
blueprint-mobile-v1	blueprint-mobile.schema.json	Mobile Blueprint
blueprint-test-v1	blueprint-test.schema.json	Test Blueprint
blueprint-ux-v1	blueprint-ux.schema.json	User Experience Blueprint
blueprint-agent-microservice-v1	blueprint-agent-microservice.schema.json	Agent Microservice Standard Blueprint
blueprint-agentic-saas-product-v1	blueprint-agentic-saas-product.schema.json	Agentic SaaS Product Blueprint
blueprint-saas-descriptor-v1	blueprint-saas-descriptor.schema.json	SaaS descriptor import (ADR-0025)

Factory DSLs and descriptors

Blueprint descriptors (vision, service, module, test, security, pipeline, observability, integration, database, documentation), the SaaS descriptor family (<Context>.json, .schema.json, .entitymodel.schema.json, Microservice.schema.json — an import format into Service and Module blueprints, ADR-0025) and the generation recipe are designed with the Software Factory pack (work package B1) and registered in the same descriptors catalog.