Product Journey YAML Reference

The Product Journey YAML Reference describes Reshot’s developer-readable representation of the canonical Journey authoring model. The current exporter emits deterministic, pretty-printed JSON syntax with media type application/yaml; JSON is a YAML 1.2-compatible subset, so the same bytes remain unambiguous across JSON/YAML tooling.

The YAML format does not define a second Journey model. TypeScript, JSON, and YAML representations round-trip through the same canonical authoring contract and semantic hash.

Canonical structure

A representation contains contract/schema version, durable Journey and version identity, referenced Observations/uploads/Renditions, field-level ownership and revision attribution, protected advanced code, unsupported source, and revision history.

{
  "contract": "journey/canonical-authoring",
  "schemaVersion": "1.0",
  "journey": { "id": "journey-invite-member" },
  "version": {
    "id": "journey-invite-member-v1",
    "journeyId": "journey-invite-member",
    "baseVersionId": null
  },
  "observationRefs": [],
  "uploadRefs": [],
  "renditionRefs": [],
  "readinessReportRef": null,
  "fields": [
    {
      "path": "/shared/name",
      "value": "Invite a member",
      "ownership": "visual-editable",
      "lastRevision": {
        "revisionId": "journey-invite-member-v1",
        "authorId": "developer:jake",
        "channel": "code",
        "occurredAt": "2026-08-24T00:00:00.000Z",
        "baseVersionId": null,
        "reason": "Initial Journey definition"
      }
    }
  ],
  "advancedCode": [],
  "unsupportedSources": [],
  "revisionHistory": [
    {
      "revisionId": "journey-invite-member-v1",
      "authorId": "developer:jake",
      "channel": "code",
      "occurredAt": "2026-08-24T00:00:00.000Z",
      "baseVersionId": null,
      "reason": "Initial Journey definition"
    }
  ]
}

Field ownership

Ownership prevents a visual editor, importer, or generator from silently rewriting repository-controlled semantics.

• visual-editable: product language and presentation fields supported by the non-developer path;
• repository-controlled: behavior whose authority remains in source;
• protected: advanced code or references that cannot be safely edited visually;
• generated: derived proposals or metadata that must not be mistaken for authored truth.

Every field carries an attributed revision.

Native Playwright import

Imported Playwright source stores file paths, hashes, config identity, fixtures, authentication/storage-state references, locators, assertions, traces, visual checks, and preservation results. Potentially sensitive source text is not duplicated into the canonical public representation.

Advanced constructs remain locked with their source location and reason. Unsupported semantics stay explicit.

Export

Use an explicit offline export from the CLI cache:

reshot journey export journey-invite-member --format yaml --offline

The --offline confirmation matters: local cache export is not a claim that the server or latest published Journey was fetched. For connected current state, use the scoped API/export path.

Validation

The canonical runtime validates identity, version linkage, revision attribution, field paths, ownership, source locations, reference arrays, and protected source. A syntactically valid YAML document can still be semantically invalid.

Use:

reshot journey validate journey-invite-member
reshot journey doctor journey-invite-member

Doctor also checks whether imported Playwright source, fixtures, or authentication references were rewritten and proposes bounded instrumentation without requiring a data-testid by default.

Round-trip guarantee

Import and export normalize into the canonical model. Compare the semantic hash and semantic diff, not whitespace, object-key order, or YAML style. An export may return JSON-shaped YAML even if the input used native YAML indentation.

Round-trip tests cover TypeScript, JSON, and YAML format identifiers through the same representation.

Merge behavior

Code and non-developer edits use attributed revisions and a three-way merge. Both authors remain visible and hidden overwrite is rejected. Protected repository source cannot be modified through presentation-owned changes.

Secrets and state

Store secret references and environment references, not secret values. Do not put storage-state contents, cookies, tokens, customer data, or private Observation payloads into Journey YAML. Public examples use fictional identities.

Versioning

Changing the intended outcome or protected semantics produces a new Journey Version. Publishing requires approval of the exact current revision. Stable Journey identity continues while historical versions remain immutable.

Conversion diagnostics

A converter should report its input contract, output format, semantic hash, validation issues, protected fields, unsupported source, and whether any reference was rewritten. Fail when a required identity is missing or a version points to another Journey.

Do not accept unknown fields by silently discarding them. Preserve them under a supported extension boundary or mark the conversion lossy and require Review.

Repository use

Store Journey representations beside code only when repository ownership is intended. Review them like other source, but keep generated evidence and secret state out of Git. A pull-request writeback requires an explicit adapter, branch, title, semantic hash, and content; local writeback remains a separate mode.

Open schema relationship

The Open Product Journey Contract publishes versioned identity/envelope and Journey Definition JSON Schemas. The authoring model includes additional ownership and revision detail needed for round-trip editing. Do not assume the schemas are interchangeable without conversion.

Portability checklist

Preserve canonical identity, source hashes, revision authorship, ownership, unsupported constructs, references, semantic hash, and validation result. A converter that keeps visible steps but drops protected source or state is lossy and must say so.

Continue with Reshot CLI, Product Journey API, and Import, Export, and Portability.