picked 0.0.101-next.2 → 0.0.101

package/docs/reference/management-api/schema/workspace-version.md

@@ -0,0 +1,823 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Workspace version schema
+
+The operations and types that `workspace-version.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `workspaceDiff`
+
+Compute a structural diff between two workspace snapshots. Each side
+can be either a live workspace (diffed against its current draft
+snapshot) or a previously-published `WorkspaceVersion`. Requires
+authentication and `ORGANIZATION_PROJECTS_READ` scope on the project
+shared by both sides.
+
+```graphql
+workspaceDiff(input: WorkspaceDiffInput!): WorkspaceDiffPayload! @auth
+```
+
+## Types
+
+### `WorkspaceVersion`
+
+```graphql
+"""
+An immutable snapshot of a workspace's config at publish time. Created
+by `workspacePublish`; never modified after creation.
+
+Snapshot contents (the underlying `config_json` blob) are deliberately
+not exposed via this type. To inspect the contents, use `workspaceDiff`
+to compare a snapshot against another snapshot or against the current
+draft.
+"""
+type WorkspaceVersion {
+  """Unique snapshot identifier."""
+  id: ID!
+  """The workspace this snapshot belongs to."""
+  workspaceId: ID!
+  """The workspace this snapshot was published from."""
+  workspace: Workspace!
+  """Id of the hidden workspace duplicated at publish time, if one exists."""
+  snapshotWorkspaceId: ID
+  """
+  The hidden workspace duplicated from the published workspace at publish
+  time — the editable state behind this version, opened by Publish History's
+  Restore action. Null on versions published before snapshots existed, when
+  snapshot duplication failed, or after the snapshot workspace was deleted.
+  """
+  snapshotWorkspace: Workspace
+  """When this snapshot was published."""
+  publishedAt: DateTime!
+}
+```
+
+### `WorkspaceVersionEdge`
+
+```graphql
+"""Edge type for `WorkspaceVersionConnection`."""
+type WorkspaceVersionEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The workspace version."""
+  node: WorkspaceVersion!
+}
+```
+
+### `WorkspaceVersionConnection`
+
+```graphql
+"""
+Relay-style connection of workspace versions, ordered newest-first by `publishedAt`.
+"""
+type WorkspaceVersionConnection {
+  """List of workspace-version edges."""
+  edges: [WorkspaceVersionEdge!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of published versions for the workspace."""
+  totalCount: Int!
+}
+```
+
+### `WorkspaceDiffInput`
+
+```graphql
+"""
+Input for `workspaceDiff`. Each side resolves to a snapshot: either a
+live workspace (diffed against its current draft snapshot) or a
+previously-published `WorkspaceVersion`.
+
+Exactly one of `baseWorkspaceId` / `baseWorkspaceVersionId` must be set,
+and exactly one of `compareWorkspaceId` / `compareWorkspaceVersionId`
+must be set. Both sides must resolve to the same project.
+"""
+input WorkspaceDiffInput {
+  """Base-side live workspace (diffed against its current draft snapshot)."""
+  baseWorkspaceId: ID
+  """Base-side published workspace version."""
+  baseWorkspaceVersionId: ID
+  """
+  Compare-side live workspace (diffed against its current draft snapshot).
+  """
+  compareWorkspaceId: ID
+  """Compare-side published workspace version."""
+  compareWorkspaceVersionId: ID
+}
+```
+
+### `WorkspaceDiffPayload`
+
+```graphql
+"""Payload returned by `workspaceDiff`."""
+type WorkspaceDiffPayload {
+  """The computed diff, or null when a `userError` was returned."""
+  diff: WorkspaceDiff
+  """
+  Validation, authorisation, and referential-integrity errors. Empty array indicates success.
+  """
+  userErrors: [UserError!]!
+}
+```
+
+### `WorkspaceSnapshotSummary`
+
+```graphql
+"""
+Identifies a snapshot on one side of a diff — workspace id plus optional version id and publish time.
+"""
+type WorkspaceSnapshotSummary {
+  """
+  The workspace the snapshot belongs to (for both live workspaces and published versions).
+  """
+  workspaceId: ID!
+  """
+  The workspace-version id, when this side resolves to a published version.
+  """
+  workspaceVersionId: ID
+  """
+  When the snapshot was published, when this side resolves to a published version.
+  """
+  publishedAt: DateTime
+}
+```
+
+### `WorkspaceDiff`
+
+```graphql
+"""
+A workspace-level structural diff between two snapshots. Each top-level
+section enumerates entities that were added, removed, or modified for
+one entity kind.
+
+`hasChanges` is `true` iff any per-entity section is non-empty —
+convenient for showing a "no changes to publish" CTA without scanning
+every section.
+"""
+type WorkspaceDiff {
+  """Identifier information for the base snapshot."""
+  base: WorkspaceSnapshotSummary!
+  """Identifier information for the compare snapshot."""
+  compare: WorkspaceSnapshotSummary!
+  """True iff any per-entity section is non-empty."""
+  hasChanges: Boolean!
+  """Per-entity feature differences."""
+  features: FeatureDiff!
+  """Per-entity step differences."""
+  steps: StepDiff!
+  """Per-entity field differences."""
+  fields: FieldDiff!
+  """Per-entity action differences."""
+  actions: ActionDiff!
+  """Per-entity condition differences."""
+  conditions: ConditionDiff!
+  """Per-entity experience differences."""
+  experiences: ExperienceDiff!
+  """Per-entity CMS Content Model differences."""
+  contentModels: ContentModelDiff!
+  """Per-entity CMS Content Block differences."""
+  contentBlocks: ContentBlockDiff!
+  """Per-entity CMS Content Entry differences."""
+  contentEntries: ContentEntryDiff!
+  """Per-entity workflow differences."""
+  workflows: WorkflowDiff!
+}
+```
+
+### `PropertyChange`
+
+```graphql
+"""A scalar or JSON-valued property that changed between two snapshots."""
+type PropertyChange {
+  """The property name on the parent entity (e.g. `name`, `weight`)."""
+  property: String!
+  """The base snapshot's value, as JSON."""
+  base: JSON
+  """The compare snapshot's value, as JSON."""
+  compare: JSON
+}
+```
+
+### `LogicChange`
+
+```graphql
+"""
+A structural change to a JSON subtree (conditions' `logic`, fields'
+`validation`, Content Model schemas). Presented as two opaque JSON
+values rather than a fine-grained path diff — clients render their own
+visualisations.
+"""
+type LogicChange {
+  """Which subtree changed (e.g. `logic`, `validation`)."""
+  property: String!
+  """Base snapshot's subtree."""
+  base: JSON
+  """Compare snapshot's subtree."""
+  compare: JSON
+}
+```
+
+### `FieldOptionSummary`
+
+```graphql
+"""
+A selectable option within a field, summarised for diff display. Named
+`FieldOptionSummary` (not `FieldOption`) because the workspace's
+`FieldOption` type carries a `JSON` `value`, whereas diffing keys by a
+string `value` identity.
+"""
+type FieldOptionSummary {
+  """Option machine value (identity key for diff comparison)."""
+  value: String!
+  """Option display label."""
+  label: String!
+}
+```
+
+### `FieldOptionModification`
+
+```graphql
+"""
+An option whose label changed while the `value` identity stayed the same.
+"""
+type FieldOptionModification {
+  """The option's unchanged identity key."""
+  value: String!
+  """Base snapshot's label."""
+  baseLabel: String!
+  """Compare snapshot's label."""
+  compareLabel: String!
+}
+```
+
+### `FieldOptionsChange`
+
+```graphql
+"""Changes to a field's selectable options, keyed by option `value`."""
+type FieldOptionsChange {
+  """Options present only in the compare snapshot."""
+  added: [FieldOptionSummary!]!
+  """Options present only in the base snapshot."""
+  removed: [FieldOptionSummary!]!
+  """Options whose `label` changed (same `value`)."""
+  modified: [FieldOptionModification!]!
+}
+```
+
+### `DiffStepRef`
+
+```graphql
+"""A reference to a step, used inside the diff payload."""
+type DiffStepRef {
+  """Stable id of the referenced step."""
+  id: ID!
+  """Display name from the snapshot."""
+  name: String!
+  """Stable, human-readable key from the snapshot."""
+  key: String!
+}
+```
+
+### `DiffFieldRef`
+
+```graphql
+"""A reference to a field, used inside the diff payload."""
+type DiffFieldRef {
+  """Stable id of the referenced field."""
+  id: ID!
+  """Display name from the snapshot."""
+  name: String!
+  """Stable, human-readable key from the snapshot."""
+  key: String!
+}
+```
+
+### `DiffActionRef`
+
+```graphql
+"""A reference to an action, used inside the diff payload."""
+type DiffActionRef {
+  """Stable id of the referenced action."""
+  id: ID!
+  """Display name from the snapshot."""
+  name: String!
+  """Stable, human-readable key from the snapshot."""
+  key: String!
+}
+```
+
+### `DiffConditionRef`
+
+```graphql
+"""A reference to a condition, used inside the diff payload."""
+type DiffConditionRef {
+  """Stable id of the referenced condition."""
+  id: ID!
+  """Display name from the snapshot."""
+  name: String!
+  """Stable, human-readable key from the snapshot."""
+  key: String!
+}
+```
+
+### `FlowStepRefsChange`
+
+```graphql
+"""Step refs added/removed from an experience's flow."""
+type FlowStepRefsChange {
+  """Step refs referenced only in the compare snapshot."""
+  added: [DiffStepRef!]!
+  """Step refs referenced only in the base snapshot."""
+  removed: [DiffStepRef!]!
+}
+```
+
+### `FlowActionRefsChange`
+
+```graphql
+"""Action refs added/removed from an experience's flow."""
+type FlowActionRefsChange {
+  """Action refs referenced only in the compare snapshot."""
+  added: [DiffActionRef!]!
+  """Action refs referenced only in the base snapshot."""
+  removed: [DiffActionRef!]!
+}
+```
+
+### `FlowConditionRefsChange`
+
+```graphql
+"""Condition refs added/removed from an experience's flow."""
+type FlowConditionRefsChange {
+  """Condition refs referenced only in the compare snapshot."""
+  added: [DiffConditionRef!]!
+  """Condition refs referenced only in the base snapshot."""
+  removed: [DiffConditionRef!]!
+}
+```
+
+### `FieldRefsChange`
+
+```graphql
+"""
+`Step.fieldIds` change — added/removed field refs, plus an order-only flag.
+"""
+type FieldRefsChange {
+  """Field refs present only in the compare snapshot."""
+  added: [DiffFieldRef!]!
+  """Field refs present only in the base snapshot."""
+  removed: [DiffFieldRef!]!
+  """True iff the same set of refs is present in a different order."""
+  reordered: Boolean!
+}
+```
+
+### `ExperienceFlowChange`
+
+```graphql
+"""
+Summary of how an experience's flow graph changed. `structureChanged` is
+true when the graph (nodes/edges) differs beyond node/edge id renaming
+despite every referenced-entity set being equal — i.e. existing
+nodes/edges were re-arranged without changing what they reference.
+"""
+type ExperienceFlowChange {
+  """Step ref changes, or null when unchanged."""
+  stepRefsChange: FlowStepRefsChange
+  """Action ref changes, or null when unchanged."""
+  actionRefsChange: FlowActionRefsChange
+  """Condition ref changes, or null when unchanged."""
+  conditionRefsChange: FlowConditionRefsChange
+  """
+  True iff nodes/edges differ beyond id renaming while all referenced-entity sets are equal.
+  """
+  structureChanged: Boolean!
+}
+```
+
+### `FeatureDiffEntry`
+
+```graphql
+"""A feature's scalar property differences."""
+type FeatureDiffEntry {
+  """Feature id (stable across snapshots)."""
+  id: ID!
+  """Display name of the feature, sourced from the compare snapshot."""
+  name: String!
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+}
+```
+
+### `FeatureDiff`
+
+```graphql
+"""Feature section of the workspace diff."""
+type FeatureDiff {
+  """Features present only in the compare snapshot."""
+  added: [JSON!]!
+  """Features present only in the base snapshot."""
+  removed: [JSON!]!
+  """Features present in both snapshots but with differing properties."""
+  modified: [FeatureDiffEntry!]!
+}
+```
+
+### `StepDiffEntry`
+
+```graphql
+"""A step's scalar property and field-ref differences."""
+type StepDiffEntry {
+  """Step id (stable across snapshots)."""
+  id: ID!
+  """Display name of the step, sourced from the compare snapshot."""
+  name: String!
+  """Stable, human-readable key, sourced from the compare snapshot."""
+  key: String!
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+  """Field-ref change (the step's `fieldIds`), or null when unchanged."""
+  fieldRefsChange: FieldRefsChange
+}
+```
+
+### `StepDiff`
+
+```graphql
+"""Step section of the workspace diff."""
+type StepDiff {
+  """Steps present only in the compare snapshot."""
+  added: [JSON!]!
+  """Steps present only in the base snapshot."""
+  removed: [JSON!]!
+  """Steps present in both snapshots but with differing properties."""
+  modified: [StepDiffEntry!]!
+}
+```
+
+### `FieldDiffEntry`
+
+```graphql
+"""A field's scalar, validation, and options differences."""
+type FieldDiffEntry {
+  """Field id (stable across snapshots)."""
+  id: ID!
+  """Display name of the field, sourced from the compare snapshot."""
+  name: String!
+  """Stable, human-readable key, sourced from the compare snapshot."""
+  key: String!
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+  """Validation subtree change, or null when unchanged."""
+  validationChange: LogicChange
+  """Visibility-condition subtree change, or null when unchanged."""
+  conditionChange: LogicChange
+  """Options-set change, or null when unchanged."""
+  optionsChange: FieldOptionsChange
+}
+```
+
+### `FieldDiff`
+
+```graphql
+"""Field section of the workspace diff."""
+type FieldDiff {
+  """Fields present only in the compare snapshot."""
+  added: [JSON!]!
+  """Fields present only in the base snapshot."""
+  removed: [JSON!]!
+  """Fields present in both snapshots but with differing properties."""
+  modified: [FieldDiffEntry!]!
+}
+```
+
+### `ActionDiffEntry`
+
+```graphql
+"""An action's scalar property differences."""
+type ActionDiffEntry {
+  """Action id (stable across snapshots)."""
+  id: ID!
+  """Display name of the action, sourced from the compare snapshot."""
+  name: String!
+  """Stable, human-readable key, sourced from the compare snapshot."""
+  key: String!
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+}
+```
+
+### `ActionDiff`
+
+```graphql
+"""Action section of the workspace diff."""
+type ActionDiff {
+  """Actions present only in the compare snapshot."""
+  added: [JSON!]!
+  """Actions present only in the base snapshot."""
+  removed: [JSON!]!
+  """Actions present in both snapshots but with differing properties."""
+  modified: [ActionDiffEntry!]!
+}
+```
+
+### `ConditionDiffEntry`
+
+```graphql
+"""A condition's scalar and logic differences."""
+type ConditionDiffEntry {
+  """Condition id (stable across snapshots)."""
+  id: ID!
+  """Display name of the condition, sourced from the compare snapshot."""
+  name: String!
+  """Stable, human-readable key, sourced from the compare snapshot."""
+  key: String!
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+  """Logic subtree change, or null when unchanged."""
+  logicChange: LogicChange
+}
+```
+
+### `ConditionDiff`
+
+```graphql
+"""Condition section of the workspace diff."""
+type ConditionDiff {
+  """Conditions present only in the compare snapshot."""
+  added: [JSON!]!
+  """Conditions present only in the base snapshot."""
+  removed: [JSON!]!
+  """Conditions present in both snapshots but with differing properties."""
+  modified: [ConditionDiffEntry!]!
+}
+```
+
+### `ExperienceDiffEntry`
+
+```graphql
+"""An experience's scalar property, target, and flow differences."""
+type ExperienceDiffEntry {
+  """Experience id (stable across snapshots)."""
+  id: ID!
+  """Display name of the experience, sourced from the compare snapshot."""
+  name: String!
+  """Stable, human-readable key, sourced from the compare snapshot."""
+  key: String!
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+  """Targeting change, or null when unchanged."""
+  targetChange: LogicChange
+  """Flow change, or null when unchanged."""
+  flowChange: ExperienceFlowChange
+}
+```
+
+### `ExperienceDiff`
+
+```graphql
+"""Experience section of the workspace diff."""
+type ExperienceDiff {
+  """Experiences present only in the compare snapshot."""
+  added: [JSON!]!
+  """Experiences present only in the base snapshot."""
+  removed: [JSON!]!
+  """Experiences present in both snapshots but with differing properties."""
+  modified: [ExperienceDiffEntry!]!
+}
+```
+
+### `ContentModelDiffEntry`
+
+```graphql
+"""A Content Model's scalar and schema differences."""
+type ContentModelDiffEntry {
+  """Content Model id (stable across snapshots)."""
+  id: ID!
+  """Display name, sourced from the compare snapshot."""
+  name: String!
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+  """Schema subtree change, or null when unchanged."""
+  schemaChange: LogicChange
+}
+```
+
+### `ContentModelDiff`
+
+```graphql
+"""Content Model section of the workspace diff."""
+type ContentModelDiff {
+  """Content Models present only in the compare snapshot."""
+  added: [JSON!]!
+  """Content Models present only in the base snapshot."""
+  removed: [JSON!]!
+  """
+  Content Models present in both snapshots but with differing properties.
+  """
+  modified: [ContentModelDiffEntry!]!
+}
+```
+
+### `ContentBlockDiffEntry`
+
+```graphql
+"""A Content Block's scalar and schema differences."""
+type ContentBlockDiffEntry {
+  """Content Block id (stable across snapshots)."""
+  id: ID!
+  """Display name, sourced from the compare snapshot."""
+  name: String!
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+  """Schema subtree change, or null when unchanged."""
+  schemaChange: LogicChange
+}
+```
+
+### `ContentBlockDiff`
+
+```graphql
+"""Content Block section of the workspace diff."""
+type ContentBlockDiff {
+  """Content Blocks present only in the compare snapshot."""
+  added: [JSON!]!
+  """Content Blocks present only in the base snapshot."""
+  removed: [JSON!]!
+  """
+  Content Blocks present in both snapshots but with differing properties.
+  """
+  modified: [ContentBlockDiffEntry!]!
+}
+```
+
+### `ContentEntryDiffEntry`
+
+```graphql
+"""A Content Entry's scalar and data differences."""
+type ContentEntryDiffEntry {
+  """Content Entry id (stable across snapshots)."""
+  id: ID!
+  """Parent Content Model id, sourced from the compare snapshot."""
+  contentModelId: ID!
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+  """Data subtree change, or null when unchanged."""
+  dataChange: LogicChange
+}
+```
+
+### `ContentEntryDiff`
+
+```graphql
+"""Content Entry section of the workspace diff."""
+type ContentEntryDiff {
+  """Content Entries present only in the compare snapshot."""
+  added: [JSON!]!
+  """Content Entries present only in the base snapshot."""
+  removed: [JSON!]!
+  """
+  Content Entries present in both snapshots but with differing properties.
+  """
+  modified: [ContentEntryDiffEntry!]!
+}
+```
+
+### `WorkflowDiffTrigger`
+
+```graphql
+"""
+A workflow's trigger as the diff reports it. The action an `ACTION` trigger
+names is resolved against the snapshot the workflow belongs to, so a removed
+workflow still shows the action it was bound to.
+"""
+type WorkflowDiffTrigger {
+  """Which kind of trigger this is."""
+  type: WorkflowTriggerType!
+  """The event that starts the run. Set for an `EVENT` trigger only."""
+  eventName: WorkflowEventName
+  """
+  ID of the action whose run starts the workflow. Set for an `ACTION` trigger only.
+  """
+  actionId: ID
+  """
+  The action `actionId` names, resolved from the snapshot. Null for an
+  `EVENT` trigger, and for an `ACTION` trigger whose action neither snapshot holds.
+  """
+  action: DiffActionRef
+}
+```
+
+### `WorkflowDiffNodeRef`
+
+```graphql
+"""A node in a workflow graph, summarised for the diff."""
+type WorkflowDiffNodeRef {
+  """Graph-unique node id, stable across snapshots of the same workflow."""
+  id: ID!
+  """
+  The node kind as stored: `ORIGIN`, `TOOL`, `CONDITION` or `SLEEP`; `UNKNOWN` when missing.
+  """
+  type: String!
+  """
+  What tells the node apart from others of its kind: the tool name, or the sleep duration. Null for other kinds.
+  """
+  label: String
+}
+```
+
+### `WorkflowGraphChange`
+
+```graphql
+"""
+How a workflow's graph changed between two snapshots. Nodes are matched by
+id; a node's canvas position is layout and never makes it a modified node.
+"""
+type WorkflowGraphChange {
+  """Number of nodes in the base snapshot's graph."""
+  baseNodeCount: Int!
+  """Number of nodes in the compare snapshot's graph."""
+  compareNodeCount: Int!
+  """Number of edges in the base snapshot's graph."""
+  baseEdgeCount: Int!
+  """Number of edges in the compare snapshot's graph."""
+  compareEdgeCount: Int!
+  """Nodes present only in the compare snapshot."""
+  addedNodes: [WorkflowDiffNodeRef!]!
+  """Nodes present only in the base snapshot."""
+  removedNodes: [WorkflowDiffNodeRef!]!
+  """Nodes present in both snapshots whose configuration differs."""
+  modifiedNodes: [WorkflowDiffNodeRef!]!
+  """
+  True iff the graph differs with no node added, removed or reconfigured: edges were rewired, or nodes moved.
+  """
+  structureChanged: Boolean!
+}
+```
+
+### `WorkflowDiffSummary`
+
+```graphql
+"""
+A workflow as the diff lists it when it is present in one snapshot only.
+"""
+type WorkflowDiffSummary {
+  """Workflow id (stable across snapshots)."""
+  id: ID!
+  """Display name of the workflow."""
+  name: String!
+  """The trigger, or null when the stored trigger cannot be read."""
+  trigger: WorkflowDiffTrigger
+  """Number of nodes in the workflow's graph."""
+  nodeCount: Int!
+  """Number of edges in the workflow's graph."""
+  edgeCount: Int!
+}
+```
+
+### `WorkflowDiffEntry`
+
+```graphql
+"""A workflow's scalar, trigger and graph differences."""
+type WorkflowDiffEntry {
+  """Workflow id (stable across snapshots)."""
+  id: ID!
+  """Display name of the workflow, sourced from the compare snapshot."""
+  name: String!
+  """
+  The compare snapshot's trigger, or null when the stored trigger cannot be read.
+  """
+  trigger: WorkflowDiffTrigger
+  """Scalar property changes."""
+  propertyChanges: [PropertyChange!]!
+  """Trigger subtree change, or null when unchanged."""
+  triggerChange: LogicChange
+  """Graph change, or null when unchanged."""
+  graphChange: WorkflowGraphChange
+}
+```
+
+### `WorkflowDiff`
+
+```graphql
+"""
+Workflow section of the workspace diff. Workflows are frozen onto a version
+by `workspacePublish`, so a live workspace's workflows are compared against
+the copies the version froze.
+"""
+type WorkflowDiff {
+  """Workflows present only in the compare snapshot."""
+  added: [WorkflowDiffSummary!]!
+  """Workflows present only in the base snapshot."""
+  removed: [WorkflowDiffSummary!]!
+  """
+  Workflows present in both snapshots but with differing properties, trigger or graph.
+  """
+  modified: [WorkflowDiffEntry!]!
+}
+```