Open Product Journey Contract

The Open Product Journey Contract is Reshot's versioned, machine-readable boundary for stable Journey identities and round-trippable Journey definitions. The public files on this page are generated from the same Zod schemas used by the current TypeScript package, so the documentation cannot silently invent a second wire format.

The contract is licensed under Apache-2.0. It defines interoperability and validation; it does not declare that every product capability is currently available through every client surface.

Contract layers and versions

Layer	Contract identifier	Current version	Purpose
Canonical identity envelope	journey-contract	1.0	Stable, content-free identity for every canonical object.
Journey definition	reshot/journey-definition	2.0	Shared Journey fields plus explicit developer or visual authoring boundaries.
Capability negotiation	reshot/journey-capability-negotiation	1.0	Explicit agreement between a client surface and the server's supported definition version and capabilities.

Different layers can evolve independently. An identity envelope should remain stable while richer Journey definition semantics or client capabilities change.

Download the machine-readable schemas

• Contract index JSON
• Canonical envelope JSON Schema 2020-12
• Canonical identity JSON Schema 2020-12
• Journey definition JSON Schema 2020-12
• Capability-negotiation request schema
• Capability-negotiation response schema

The schema endpoints permit cross-origin reads and return long-lived public cache headers. Consumers should pin the versioned URL rather than assuming the latest contract.

Canonical identity envelope

The identity envelope is intentionally content-free. It proves which workspace, project, Journey, Journey Version, and canonical object a record refers to without prematurely standardizing every product payload.

{
  "contract": "journey-contract",
  "schemaVersion": "1.0",
  "objectType": "journey",
  "identity": {
    "workspaceId": "workspace-acme",
    "projectId": "project-checkout",
    "objectType": "journey",
    "id": "journey-complete-checkout",
    "journeyId": "journey-complete-checkout"
  }
}

The schemas are strict: unknown properties fail validation, identity strings are bounded, and a Journey's id must equal its journeyId. Journey-scoped evidence objects also retain the owning journeyId and journeyVersionId.

Canonical object types

Version 1.0 recognizes these identities:

Phase	Object types
Product Journey system of record	journey, journey-version, state-capsule, target-bundle, run, observation, decision, rendition, publication, dependency, experience-signal, release-book
Product Journey Network continuation	capability-manifest, agent-evaluation, registry-entry, credential, subscription, change-notification

Including Network identities in the contract does not reduce the Phase One boundary. Journey authoring, execution, Review, Rendition creation, and Publication remain the first complete customer loop.

Journey definition 2.0

The Journey definition contract protects the shared semantics that must survive between developer and visual authoring:

• stable workspace, project, Journey, and Journey Version identity;
• revision number;
• name, description, and HTTP(S) start URL;
• tags and declared contexts;
• ordered steps with action, target, and optional value;
• source kind: developer or visual.

Developer definitions may retain code-only advanced constructs. Visual definitions expose those constructs as locked material with explicit editable and protected paths. A visual edit cannot silently rewrite protected source, and a later developer round trip must preserve the advanced constructs.

{
  "contract": "reshot/journey-definition",
  "schemaVersion": "2.0",
  "sourceKind": "developer",
  "identity": {
    "workspaceId": "workspace-acme",
    "projectId": "project-checkout",
    "journeyId": "journey-complete-checkout",
    "journeyVersionId": "journey-complete-checkout-v3"
  },
  "revision": 3,
  "shared": {
    "name": "Complete checkout",
    "description": "A buyer completes payment and receives the correct order confirmation.",
    "startUrl": "https://shop.example/checkout",
    "tags": ["release-critical"],
    "contexts": ["buyer-usd-desktop"],
    "steps": [
      {
        "id": "submit-order",
        "action": "click",
        "target": "role=button[name='Place order']"
      }
    ]
  },
  "advanced": []
}

This example validates structure, not outcome completeness. Product checkpoints, State Capsule semantics, allowed side effects, and retained evidence remain richer application contracts around the portable definition.

Capability negotiation

Clients identify their surface—web, api, cli, worker, extension, or desktop—and declare supported Journey definition versions plus required and optional capabilities. The server responds with an accepted definition version, enabled capabilities, missing required capabilities, and explicit messages.

Unknown requested capabilities are not discarded. They remain visible in negotiation so a newer client receives a deterministic rejection instead of a false success.

Capabilities currently cover Journey read/write, publish, branch, compare, archive, import/export, dependencies, visual editing, code-advanced constructs, legacy reads, interface compilation, surface execution, outcome tracking, agent evaluation, credential signing, registry publication, subscription, and change propagation.

Evidence-to-publication reference schemas

Versioned serializable reference schemas and fixtures cover:

• State Capsule transport and example;
• exact-session Observation and example;
• Review Decision and example;
• Rendition Version and example;
• Publication Version and example;
• contract changelog.

Runtime State Capsules contain executable precondition and cleanup functions. JSON cannot serialize functions. The public transport schema therefore preserves check identity/category and requires the supported runtime to hydrate the executable implementation before materialization. Passing the transport schema alone is never a successful state Run.

Observation, Decision, Rendition, and Publication hashes remain application integrity contracts. A structurally valid example is not customer evidence or a release approval.

Compatibility rules

1. Consumers pin a schema URL and contract version.
2. Strict validation rejects unknown properties rather than silently dropping meaning.
3. Legacy identities are read-only compatibility inputs with explicit migration outcomes.
4. Developer and visual definitions preserve shared fields in both directions.
5. Code-only constructs remain visibly locked during visual editing.
6. Same-field conflicts create attributable conflict records rather than last-write-wins overwrites.
7. The identity envelope never proves that an Observation is trustworthy or a Publication is approved; application evidence and policy establish those claims.

Relationship to the product glossary

The JSON Schemas define stable machine boundaries. The Product Journey glossary explains the product meaning of Journeys, Journey Versions, State Capsules, Observations, Decisions, Renditions, Publications, and Release Books. Neither layer can override current product authority or turn package-only behavior into a complete customer path.

For developer implementation, see Import and Export, CLI commands, and the Journey documentation.