Platform Protocol Specs
The platform protocol catalog tells SDK authors, agents, operators, and third-party tooling exactly which machine-readable specification governs each public Durable Workflow surface.
Use the machine-readable catalog for automation. Every available entry provides both a stable specification identifier and a public HTTPS URL that resolves directly to an OpenAPI, AsyncAPI, or JSON Schema artifact.
Repository paths, implementation symbols, and test fixtures are intentionally not consumer authority. They are excluded from the published catalog and kept only as validation diagnostics.
Catalog identity and discovery
The catalog has schema durable-workflow.v2.platform-protocol-specs.catalog and version 15. It is available through:
- the public JSON catalog at https://durable-workflow.github.io/platform-protocol-specs.json;
- platform_protocol_specs in GET /api/cluster/info on the standalone server;
- this 2.0 guide for human-readable context.
The JSON URL is the machine-consumable catalog authority. The server re-exports the same catalog so clients can discover the active protocol surface without assuming a repository layout.
Consumer fields
Each entry exposes the following contract:
| Field | Meaning |
|---|---|
| spec_id | Stable Durable Workflow protocol identifier. Published documents carry the matching identity. |
| spec_url | Direct public HTTPS URL for the machine-readable specification. |
| format | openapi, json_schema, or asyncapi. |
| status | Whether the referenced artifact is published, in progress, or planned. |
| surface_family | Compatibility-policy family that governs the surface. |
| authority_manifest | Discovery manifest through which a runtime advertises the surface. |
| owner_repo | Project responsible for the specification. |
| object_families | Public object-family names and their owning projects. |
| evolution_rule | Compatibility rule for additive and breaking changes. |
| breaking_change_release | Release boundary required by that evolution rule. |
Consumers should resolve spec_url and validate the document identity against spec_id. They do not need source checkout access.
Available specifications
This inventory is rendered from the public JSON catalog. Specification identity, availability, public links, and object-family ownership therefore remain catalog data rather than a second prose authority.
control_plane_api
- Specification ID
durable-workflow.v2.control-plane-api- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/control-plane-api.openapi.yaml
- Format and status
openapi·published- Owning contract
durable-workflow/server
Object families and owning contracts
control_plane_request_contract—durable-workflow/servercontrol_plane_response_envelope—durable-workflow/servercontrol_plane_operation_contract—durable-workflow/server
worker_protocol_api
- Specification ID
durable-workflow.v2.worker-protocol-api- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/worker-protocol-api.openapi.yaml
- Format and status
openapi·published- Owning contract
durable-workflow/server
Object families and owning contracts
worker_registration_request—durable-workflow/serverworker_task_poll_request—durable-workflow/serverworker_task_result—durable-workflow/serverworker_query_task_poll_request—durable-workflow/serverworker_query_task_result—durable-workflow/serverexternal_task_input_contract—durable-workflow/serverexternal_task_result_contract—durable-workflow/server
worker_protocol_stream
- Specification ID
durable-workflow.v2.worker-protocol-stream- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/worker-protocol-stream.asyncapi.yaml
- Format and status
asyncapi·published- Owning contract
durable-workflow/server
Object families and owning contracts
worker_poll_stream—durable-workflow/serverworker_task_lease—durable-workflow/serverworker_task_heartbeat—durable-workflow/server
worker_sessions_runtime
- Specification ID
durable-workflow.v2.worker-sessions-runtime- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/worker-sessions-runtime.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/server
Object families and owning contracts
worker_session_runtime_contract—durable-workflow/workflowworker_session_options—durable-workflow/workflowworker_session_lifecycle—durable-workflow/serverworker_session_visibility—durable-workflow/server
local_activity_runtime
- Specification ID
durable-workflow.v2.local-activity-runtime- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/local-activity-runtime.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/workflow
Object families and owning contracts
local_activity_runtime_contract—durable-workflow/workflowlocal_activity_options—durable-workflow/workflowlocal_activity_history_markers—durable-workflow/workflowlocal_activity_visibility—durable-workflow/workflow
history_event_payloads
- Specification ID
durable-workflow.v2.history-event-payloads- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/history-event-payloads.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/workflow
Object families and owning contracts
workflow_history_events—durable-workflow/workflowworkflow_schedule_history_events—durable-workflow/workflow
history_export_bundle
- Specification ID
durable-workflow.v2.history-export-bundle- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/history-export-bundle.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/workflow
Object families and owning contracts
history_export_bundle—durable-workflow/workflow
replay_bundle
- Specification ID
durable-workflow.v2.replay-bundle- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/replay-bundle.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/workflow
Object families and owning contracts
replay_bundle—durable-workflow/workflow
waterline_read_api
- Specification ID
durable-workflow.v2.waterline-read-api- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/waterline-read-api.openapi.yaml
- Format and status
openapi·published- Owning contract
durable-workflow/waterline
Object families and owning contracts
waterline_read_envelope—durable-workflow/waterlinewaterline_operator_action_envelope—durable-workflow/waterline
waterline_diagnostic_objects
- Specification ID
durable-workflow.v2.waterline-diagnostic-objects- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/waterline-diagnostic-objects.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/waterline
Object families and owning contracts
waterline_run_detail—durable-workflow/waterlinewaterline_health_diagnostics—durable-workflow/waterlinewaterline_timeline_rows—durable-workflow/waterlinewaterline_lineage_edges—durable-workflow/waterline
repair_actionability_objects
- Specification ID
durable-workflow.v2.repair-actionability-objects- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/repair-actionability-objects.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/workflow
Object families and owning contracts
task_repair_policy—durable-workflow/workflowtask_repair_candidates—durable-workflow/workflowoperator_queue_visibility—durable-workflow/workflowactionability—durable-workflow/waterlineagent_root_cause—durable-workflow/durable-workflow.github.ioagent_remediation—durable-workflow/durable-workflow.github.iosafe_mutation—durable-workflow/durable-workflow.github.io
cli_json_envelopes
- Specification ID
durable-workflow.v2.cli-json-envelopes- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/cli-json-envelopes.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/cli
Object families and owning contracts
cli_output_schema_manifest—durable-workflow/clicli_command_output_schema—durable-workflow/cli
mcp_discovery
- Specification ID
durable-workflow.v2.mcp-discovery- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/mcp-discovery.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/durable-workflow.github.io
Object families and owning contracts
mcp_tool_discovery—durable-workflow/durable-workflow.github.iollms_txt_discovery—durable-workflow/durable-workflow.github.io
mcp_tool_results
- Specification ID
durable-workflow.v2.mcp-tool-results- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/mcp-tool-results.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/durable-workflow.github.io
Object families and owning contracts
mcp_tool_result_envelope—durable-workflow/durable-workflow.github.ioagent_root_cause—durable-workflow/durable-workflow.github.ioagent_remediation—durable-workflow/durable-workflow.github.iosafe_mutation—durable-workflow/durable-workflow.github.io
cluster_info_envelope
- Specification ID
durable-workflow.v2.cluster-info-envelope- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/cluster-info-envelope.schema.json
- Format and status
json_schema·published- Owning contract
durable-workflow/server
Object families and owning contracts
cluster_info_envelope—durable-workflow/serverclient_compatibility_manifest—durable-workflow/serversurface_stability_contract—durable-workflow/workflowplatform_protocol_specs_catalog—durable-workflow/workflowplatform_conformance_suite_manifest—durable-workflow/workflowsdk_neutrality_contract—durable-workflow/workflow
invocable_carrier_execution
- Specification ID
durable-workflow.v2.invocable-carrier-execution- Public specification
- https://durable-workflow.github.io/platform-protocol-specs/invocable-carrier-execution.schema.json
- Format and status
json_schema·in_progress- Owning contract
durable-workflow/server
Object families and owning contracts
invocable_carrier_contract—durable-workflow/serverexternal_execution_surface_contract—durable-workflow/serverexternal_executor_config_contract—durable-workflow/server
Worker session runtime notes
This schema covers worker-session capability discovery, lifecycle envelopes, task-affinity snapshots, and operator visibility. Its stable identifier is durable-workflow.v2.worker-sessions-runtime.
Local activity runtime notes
This schema covers local-activity capability discovery, option snapshots, history markers, retry semantics, and operator visibility. Its stable identifier is durable-workflow.v2.local-activity-runtime.
Cluster-info envelope notes
This schema covers GET /api/cluster/info and the nested discovery manifests available from that endpoint. Its stable identifier is durable-workflow.v2.cluster-info-envelope.
Formats
| Format | Use |
|---|---|
| OpenAPI 3.1 | HTTP and JSON request-response surfaces whose routes, methods, status codes, and envelopes are part of the contract. |
| JSON Schema 2020-12 | Persisted records, event payloads, result envelopes, runtime options, and related object families. |
| AsyncAPI 2.6 or newer | Poll, stream, lease-renewal, ordering, and delivery semantics. |
Status levels
| Status | Meaning |
|---|---|
| published | The public machine-readable specification is available at spec_url and can be consumed directly. |
| in_progress | A public specification is available, but its coverage is partial. Listed fields and routes are normative. |
| planned | The entry has a stable catalog identity but no consumable specification yet. Planned entries do not advertise spec_url. |
Evolution rules
additive_minor_breaking_major allows additive changes in minor releases. Removals, renames, type narrowings, and semantic changes require a major release and should use a parallel route or field where practical.
parallel_primitive_only governs frozen wire formats. A breaking shape must be introduced under a new event type, command type, or schema identifier while the original remains decodable.
experimental_any_release applies only to explicitly experimental specifications and allows change in any release.
Release validation
Docs-site CI enforces the following machine checks:
| Gate | What CI checks |
|---|---|
| catalog_aligned_with_surface_families | Every entry references a declared public compatibility family. |
| owner_repo_known | Entry and object-family owners use the catalog vocabulary. |
| format_known | Every available artifact parses as its declared format. |
| public_spec_references_resolve | Every available spec_url is an HTTPS URL in the public protocol-spec namespace and resolves to a shipped artifact whose identity matches spec_id. |
| repository_local_authority_fields_rejected | Published entries contain no repository-local paths, implementation symbols, test references, or legacy authority fields. |
| workflow_package_mirror_aligned | The public catalog matches the packaged Workflow catalog when that release input is available. |
| server_owned_spec_mirrors_aligned | Server-owned published artifacts match owner-repository mirrors when those inputs are available. |
| diagnostic_provenance_complete | Validation-only provenance covers every catalog entry and object family. |
| object_family_metadata_declared | Catalog entries and published documents agree on object-family names and owners. |
| rendered_retrieval_surfaces_aligned | The built 2.0 page and full 2.0 model-retrieval bundles expose every available entry's catalog identity, public URL, and object-family ownership. |
| breaking_change_release_consistent_with_evolution_rule | Every breaking-change release value matches its evolution rule. |
| deliverable_specs_published | Every required platform surface has a published, parseable specification. |
The machine check loads the public JSON catalog, validates its vocabulary and consumer-safe references, parses shipped specifications, checks object-family and embedded-schema metadata, and compares package mirrors when available. After the site and model bundles are generated, a semantic check compares their rendered catalog values to that same JSON authority. Documentation prose and heading text are not part of the comparison.
When the contract changes, update the packaged Workflow catalog, this public JSON mirror, and affected published specification artifacts together. Human review confirms that explanatory prose remains useful without treating it as machine authority.