Canvas Conversion

Conversion turns a literal node — a definition held only as an artifact — into a first-class Schema, Experience, or Flow, and replaces the literal node with a reference node.

Start a conversion with Convert to resource on a literal node. See Canvas Editor Actions.

On success, the result is the new resource's type, its ID, its version, the Canvas version that records the conversion, and its editor URL (see Editor URL).

The conversion is all or nothing. If it fails, no resource, folder entry, or Canvas version is written.

Gates

Checks are applied in this order.

1. Access

Canvas must be enabled for the Space and the caller must be a Space admin. See Canvas Access.

2. Repeat Conversion

If this literal was already converted from the same artifact, the earlier result is returned unchanged. No second resource is created.

3. Stale Base

If the Canvas has changed since the version you are editing, conversion returns:

CONFLICT  "Canvas head changed"

4. Flow Literals

Converting a flow:literal node returns BAD_REQUEST with Flow conversion requires explicit confirmation. Flow literals cannot be converted from the Canvas.

5. Acceptance

For Schema and Experience literals that have review candidates (see Canvas Review and Provenance), conversion requires a candidate that is accepted with matching content:

• If one or more candidates exist and none is accepted with matching content, conversion returns CONFLICT with Literal candidate must be accepted before conversion.
• If no candidates exist for that node and artifact, conversion proceeds.

The gate constrains reviewed content. It does not require every literal to have been reviewed.

6. Definition Validity

The definition artifact pinned by the literal must be a valid definition of the resource type being created:

• A malformed pin returns BAD_REQUEST with Definition artifact pin is invalid.
• A definition of the wrong type, or one that cannot be read, returns BAD_REQUEST with Invalid <Schema|Experience|Flow> definition artifact.

Effects

On success:

1. A Schema, Experience, or Flow is created in the Space.
2. The resource is added to the target folder. If no target folder is set, the Space's hidden root folder is used and created if it does not exist.
3. The literal node is replaced with a <type>:reference node that points to the new resource.
4. A Canvas version is saved with the summary Converted <type> literal <nodeId>, and it becomes the current version.

For a Flow, the Flow is no longer associated with the Canvas.

Earlier Canvas versions still show the literal node. Conversion does not rewrite history.

Name Collisions

If a resource with the same name and type already exists in the Space, conversion returns:

CONFLICT  A <resourceType> named "<name>" already exists in this space

Editor URL

The result includes an editor URL for the created resource: