Resolve one Form hierarchy selection to its safe root-to-terminal chain.

POST

/api/workspace/entity/{entityIdOrKey}/ui/form/{formSurfaceId}/items/{formItemId}/reference-hierarchy/selection

curl --request POST \
  --url https://example.com/api/workspace/entity/example/ui/form/example/items/example/reference-hierarchy/selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "Context": { "ExpectedFormSurfaceRowVersion": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "SourceInstanceId": "example", "CurrentValues": { "additionalProperty": "example" }, "ParentContext": { "EntityDefinitionId": "example", "FormSurfaceId": "example", "ExpectedRevision": "example", "ItemId": "example", "ParentInstanceId": "example", "ParentFields": { "additionalProperty": "example" } } }, "Selection": { "SelectedId": "example" } }'

Authorizations

• WorkspaceBearer

Parameters

Path Parameters

entityIdOrKey

required

string

formSurfaceId

required

string

formItemId

required

string

Query Parameters

access_token

string

Optional access token for clients that cannot set Authorization headers. Prefer Authorization: Bearer <token> when possible.

Request Body

Form hierarchy selected-chain request.

object

Context

required

Saved Form context used by hierarchy model, page, and selection routes.

object

ExpectedFormSurfaceRowVersion

required

Exact owning Form Surface revision.

string format: uuid

SourceInstanceId

Existing source record identifier for edit, or null for create.

string

nullable

CurrentValues

Dynamic Form draft values keyed by the server-declared source field keys. Reference values are raw Entity Instance identifier strings, not value wrappers.

object

key

additional properties

A typed scalar or complex field value. Reference fields use the raw Entity Instance identifier string.

nullable

ParentContext

The parent draft of a child draft in a Form with a WithParent section, sent with a child-scoped request made before the Form is saved. The server builds the parent’s effective draft for the actor (defaults, effects and calculations of the parent Form evaluation) and exposes it only as the record the child’s parent Reference points to; the child’s parent Reference is set by the server. Preview only: nothing is written and nothing is granted, the Form submission decides everything again.

object

EntityDefinitionId

required

Id of the parent Entity definition.

string

FormSurfaceId

required

Id of the parent Form surface.

string

ExpectedRevision

required

The Submission.Revision of the parent Form the client renders.

string

ItemId

required

Id of a WithParent related-table item of the child’s relation (any repeated item of that relation; its own child Form is the one the request runs on).

string

ParentInstanceId

Id of the existing parent record; null while the parent is created by the same Form.

string

nullable

ParentFields

Unsaved parent draft values by field key, as the parent Form evaluation takes them.

object

key

additional properties

Selection

required

One proposed terminal hierarchy selection.

object

SelectedId

required

Proposed terminal Entity Instance identifier.

string

Example^generated

{
  "Context": {
    "ExpectedFormSurfaceRowVersion": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "SourceInstanceId": "example",
    "CurrentValues": {
      "additionalProperty": "example"
    },
    "ParentContext": {
      "EntityDefinitionId": "example",
      "FormSurfaceId": "example",
      "ExpectedRevision": "example",
      "ItemId": "example",
      "ParentInstanceId": "example",
      "ParentFields": {
        "additionalProperty": "example"
      }
    }
  },
  "Selection": {
    "SelectedId": "example"
  }
}

Form hierarchy selected-chain request.

object

Context

required

Saved Form context used by hierarchy model, page, and selection routes.

object

ExpectedFormSurfaceRowVersion

required

Exact owning Form Surface revision.

string format: uuid

SourceInstanceId

Existing source record identifier for edit, or null for create.

string

nullable

CurrentValues

Dynamic Form draft values keyed by the server-declared source field keys. Reference values are raw Entity Instance identifier strings, not value wrappers.

object

key

additional properties

A typed scalar or complex field value. Reference fields use the raw Entity Instance identifier string.

nullable

ParentContext

The parent draft of a child draft in a Form with a WithParent section, sent with a child-scoped request made before the Form is saved. The server builds the parent’s effective draft for the actor (defaults, effects and calculations of the parent Form evaluation) and exposes it only as the record the child’s parent Reference points to; the child’s parent Reference is set by the server. Preview only: nothing is written and nothing is granted, the Form submission decides everything again.

object

EntityDefinitionId

required

Id of the parent Entity definition.

string

FormSurfaceId

required

Id of the parent Form surface.

string

ExpectedRevision

required

The Submission.Revision of the parent Form the client renders.

string

ItemId

required

Id of a WithParent related-table item of the child’s relation (any repeated item of that relation; its own child Form is the one the request runs on).

string

ParentInstanceId

Id of the existing parent record; null while the parent is created by the same Form.

string

nullable

ParentFields

Unsaved parent draft values by field key, as the parent Form evaluation takes them.

object

key

additional properties

Selection

required

One proposed terminal hierarchy selection.

object

SelectedId

required

Proposed terminal Entity Instance identifier.

string

Example^generated

{
  "Context": {
    "ExpectedFormSurfaceRowVersion": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "SourceInstanceId": "example",
    "CurrentValues": {
      "additionalProperty": "example"
    },
    "ParentContext": {
      "EntityDefinitionId": "example",
      "FormSurfaceId": "example",
      "ExpectedRevision": "example",
      "ItemId": "example",
      "ParentInstanceId": "example",
      "ParentFields": {
        "additionalProperty": "example"
      }
    }
  },
  "Selection": {
    "SelectedId": "example"
  }
}

Form hierarchy selected-chain request.

object

Context

required

Saved Form context used by hierarchy model, page, and selection routes.

object

ExpectedFormSurfaceRowVersion

required

Exact owning Form Surface revision.

string format: uuid

SourceInstanceId

Existing source record identifier for edit, or null for create.

string

nullable

CurrentValues

Dynamic Form draft values keyed by the server-declared source field keys. Reference values are raw Entity Instance identifier strings, not value wrappers.

object

key

additional properties

A typed scalar or complex field value. Reference fields use the raw Entity Instance identifier string.

nullable

ParentContext

The parent draft of a child draft in a Form with a WithParent section, sent with a child-scoped request made before the Form is saved. The server builds the parent’s effective draft for the actor (defaults, effects and calculations of the parent Form evaluation) and exposes it only as the record the child’s parent Reference points to; the child’s parent Reference is set by the server. Preview only: nothing is written and nothing is granted, the Form submission decides everything again.

object

EntityDefinitionId

required

Id of the parent Entity definition.

string

FormSurfaceId

required

Id of the parent Form surface.

string

ExpectedRevision

required

The Submission.Revision of the parent Form the client renders.

string

ItemId

required

Id of a WithParent related-table item of the child’s relation (any repeated item of that relation; its own child Form is the one the request runs on).

string

ParentInstanceId

Id of the existing parent record; null while the parent is created by the same Form.

string

nullable

ParentFields

Unsaved parent draft values by field key, as the parent Form evaluation takes them.

object

key

additional properties

Selection

required

One proposed terminal hierarchy selection.

object

SelectedId

required

Proposed terminal Entity Instance identifier.

string

Example^generated

{
  "Context": {
    "ExpectedFormSurfaceRowVersion": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "SourceInstanceId": "example",
    "CurrentValues": {
      "additionalProperty": "example"
    },
    "ParentContext": {
      "EntityDefinitionId": "example",
      "FormSurfaceId": "example",
      "ExpectedRevision": "example",
      "ItemId": "example",
      "ParentInstanceId": "example",
      "ParentFields": {
        "additionalProperty": "example"
      }
    }
  },
  "Selection": {
    "SelectedId": "example"
  }
}

Responses

200

OK

Media typeapplication/json

object

Data

Safe selected hierarchy chain resolution.

object

State

integer format: int32

Allowed values: 0 1 2 3 4 5 6 7 8 9 10

ErrorCode

Stable guidance code for a closed or ineligible state.

string

nullable

Chain

Readable root-to-terminal chain for eligible or observable ineligible selections only.

Array<object>

nullable

One display-safe hierarchy option.

object

Id

Entity Instance identifier.

string

nullable

DisplayName

Current display name.

string

nullable

Subtitle

Optional current subtitle.

string

nullable

HasChildren

Whether at least one readable structural child exists.

boolean

CanConfirm

Whether the option may be returned as the terminal Reference value.

boolean

ConfirmationState

integer format: int32

Allowed values: 0 1 2

ConfirmationMessage

Optional safe localized explanation for a non-confirmable state.

string

nullable

SelectedValue

Compact runtime payload for one resolved or unresolved entity reference.

object

State

integer format: int32

Allowed values: 0 1 2

Id

Linked entity identifier when resolved.

string

nullable

Number

Linked entity number when resolved.

string

nullable

DisplayName

Linked entity display name from the presentation cache when resolved.

string

nullable

Subtitle

Linked entity subtitle from the presentation cache when resolved.

string

nullable

ProjectedValues

Projected primary-field scalar values and requested nested reference values keyed by target field key when resolved.

object

key

additional properties

nullable

EntityDefinitionId

Linked entity definition identifier when resolved.

string

nullable

ProjectedPlainTextPreviews

Compact server-created previews for projected Markdown fields, keyed by target field key.

object

key

additional properties

Safe compact visible-text representation of a Markdown value.

object

Text

Visible text when available.

string

nullable

IsTruncated

Whether the visible text was shortened for compact presentation.

boolean

State

integer format: int32

Allowed values: 0 1 2 3

SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object

UsageType

integer format: int32

Allowed values: 0 1 2

SemanticType

string

nullable

LinkRegistrationKey

string

nullable

CellRegistrationKey

string

nullable

Errors

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Warnings

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Success

boolean

Example

{
  "Data": {
    "State": 0,
    "Chain": [
      {
        "ConfirmationState": 0
      }
    ],
    "SelectedValue": {
      "State": 0,
      "ProjectedPlainTextPreviews": {
        "additionalProperty": {
          "State": 0
        }
      },
      "SemanticPresentation": {
        "UsageType": 0
      }
    }
  },
  "Errors": [
    {
      "Type": 0,
      "Severity": 0
    }
  ],
  "Warnings": [
    {
      "Type": 0,
      "Severity": 0
    }
  ]
}

400

Bad Request

Media typeapplication/json

object

Data

Safe selected hierarchy chain resolution.

object

State

integer format: int32

Allowed values: 0 1 2 3 4 5 6 7 8 9 10

ErrorCode

Stable guidance code for a closed or ineligible state.

string

nullable

Chain

Readable root-to-terminal chain for eligible or observable ineligible selections only.

Array<object>

nullable

One display-safe hierarchy option.

object

Id

Entity Instance identifier.

string

nullable

DisplayName

Current display name.

string

nullable

Subtitle

Optional current subtitle.

string

nullable

HasChildren

Whether at least one readable structural child exists.

boolean

CanConfirm

Whether the option may be returned as the terminal Reference value.

boolean

ConfirmationState

integer format: int32

Allowed values: 0 1 2

ConfirmationMessage

Optional safe localized explanation for a non-confirmable state.

string

nullable

SelectedValue

Compact runtime payload for one resolved or unresolved entity reference.

object

State

integer format: int32

Allowed values: 0 1 2

Id

Linked entity identifier when resolved.

string

nullable

Number

Linked entity number when resolved.

string

nullable

DisplayName

Linked entity display name from the presentation cache when resolved.

string

nullable

Subtitle

Linked entity subtitle from the presentation cache when resolved.

string

nullable

ProjectedValues

Projected primary-field scalar values and requested nested reference values keyed by target field key when resolved.

object

key

additional properties

nullable

EntityDefinitionId

Linked entity definition identifier when resolved.

string

nullable

ProjectedPlainTextPreviews

Compact server-created previews for projected Markdown fields, keyed by target field key.

object

key

additional properties

Safe compact visible-text representation of a Markdown value.

object

Text

Visible text when available.

string

nullable

IsTruncated

Whether the visible text was shortened for compact presentation.

boolean

State

integer format: int32

Allowed values: 0 1 2 3

SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object

UsageType

integer format: int32

Allowed values: 0 1 2

SemanticType

string

nullable

LinkRegistrationKey

string

nullable

CellRegistrationKey

string

nullable

Errors

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Warnings

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Success

boolean

Example

{
  "Data": {
    "State": 0,
    "Chain": [
      {
        "ConfirmationState": 0
      }
    ],
    "SelectedValue": {
      "State": 0,
      "ProjectedPlainTextPreviews": {
        "additionalProperty": {
          "State": 0
        }
      },
      "SemanticPresentation": {
        "UsageType": 0
      }
    }
  },
  "Errors": [
    {
      "Type": 0,
      "Severity": 0
    }
  ],
  "Warnings": [
    {
      "Type": 0,
      "Severity": 0
    }
  ]
}

403

Forbidden

Media typeapplication/json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

key

additional properties

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

404

Not Found

Media typeapplication/json

object

Data

Safe selected hierarchy chain resolution.

object

State

integer format: int32

Allowed values: 0 1 2 3 4 5 6 7 8 9 10

ErrorCode

Stable guidance code for a closed or ineligible state.

string

nullable

Chain

Readable root-to-terminal chain for eligible or observable ineligible selections only.

Array<object>

nullable

One display-safe hierarchy option.

object

Id

Entity Instance identifier.

string

nullable

DisplayName

Current display name.

string

nullable

Subtitle

Optional current subtitle.

string

nullable

HasChildren

Whether at least one readable structural child exists.

boolean

CanConfirm

Whether the option may be returned as the terminal Reference value.

boolean

ConfirmationState

integer format: int32

Allowed values: 0 1 2

ConfirmationMessage

Optional safe localized explanation for a non-confirmable state.

string

nullable

SelectedValue

Compact runtime payload for one resolved or unresolved entity reference.

object

State

integer format: int32

Allowed values: 0 1 2

Id

Linked entity identifier when resolved.

string

nullable

Number

Linked entity number when resolved.

string

nullable

DisplayName

Linked entity display name from the presentation cache when resolved.

string

nullable

Subtitle

Linked entity subtitle from the presentation cache when resolved.

string

nullable

ProjectedValues

Projected primary-field scalar values and requested nested reference values keyed by target field key when resolved.

object

key

additional properties

nullable

EntityDefinitionId

Linked entity definition identifier when resolved.

string

nullable

ProjectedPlainTextPreviews

Compact server-created previews for projected Markdown fields, keyed by target field key.

object

key

additional properties

Safe compact visible-text representation of a Markdown value.

object

Text

Visible text when available.

string

nullable

IsTruncated

Whether the visible text was shortened for compact presentation.

boolean

State

integer format: int32

Allowed values: 0 1 2 3

SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object

UsageType

integer format: int32

Allowed values: 0 1 2

SemanticType

string

nullable

LinkRegistrationKey

string

nullable

CellRegistrationKey

string

nullable

Errors

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Warnings

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Success

boolean

Example

{
  "Data": {
    "State": 0,
    "Chain": [
      {
        "ConfirmationState": 0
      }
    ],
    "SelectedValue": {
      "State": 0,
      "ProjectedPlainTextPreviews": {
        "additionalProperty": {
          "State": 0
        }
      },
      "SemanticPresentation": {
        "UsageType": 0
      }
    }
  },
  "Errors": [
    {
      "Type": 0,
      "Severity": 0
    }
  ],
  "Warnings": [
    {
      "Type": 0,
      "Severity": 0
    }
  ]
}

409

Conflict

Media typeapplication/json

object

Data

Safe selected hierarchy chain resolution.

object

State

integer format: int32

Allowed values: 0 1 2 3 4 5 6 7 8 9 10

ErrorCode

Stable guidance code for a closed or ineligible state.

string

nullable

Chain

Readable root-to-terminal chain for eligible or observable ineligible selections only.

Array<object>

nullable

One display-safe hierarchy option.

object

Id

Entity Instance identifier.

string

nullable

DisplayName

Current display name.

string

nullable

Subtitle

Optional current subtitle.

string

nullable

HasChildren

Whether at least one readable structural child exists.

boolean

CanConfirm

Whether the option may be returned as the terminal Reference value.

boolean

ConfirmationState

integer format: int32

Allowed values: 0 1 2

ConfirmationMessage

Optional safe localized explanation for a non-confirmable state.

string

nullable

SelectedValue

Compact runtime payload for one resolved or unresolved entity reference.

object

State

integer format: int32

Allowed values: 0 1 2

Id

Linked entity identifier when resolved.

string

nullable

Number

Linked entity number when resolved.

string

nullable

DisplayName

Linked entity display name from the presentation cache when resolved.

string

nullable

Subtitle

Linked entity subtitle from the presentation cache when resolved.

string

nullable

ProjectedValues

Projected primary-field scalar values and requested nested reference values keyed by target field key when resolved.

object

key

additional properties

nullable

EntityDefinitionId

Linked entity definition identifier when resolved.

string

nullable

ProjectedPlainTextPreviews

Compact server-created previews for projected Markdown fields, keyed by target field key.

object

key

additional properties

Safe compact visible-text representation of a Markdown value.

object

Text

Visible text when available.

string

nullable

IsTruncated

Whether the visible text was shortened for compact presentation.

boolean

State

integer format: int32

Allowed values: 0 1 2 3

SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object

UsageType

integer format: int32

Allowed values: 0 1 2

SemanticType

string

nullable

LinkRegistrationKey

string

nullable

CellRegistrationKey

string

nullable

Errors

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Warnings

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Success

boolean

Example

{
  "Data": {
    "State": 0,
    "Chain": [
      {
        "ConfirmationState": 0
      }
    ],
    "SelectedValue": {
      "State": 0,
      "ProjectedPlainTextPreviews": {
        "additionalProperty": {
          "State": 0
        }
      },
      "SemanticPresentation": {
        "UsageType": 0
      }
    }
  },
  "Errors": [
    {
      "Type": 0,
      "Severity": 0
    }
  ],
  "Warnings": [
    {
      "Type": 0,
      "Severity": 0
    }
  ]
}

503

Service Unavailable

Media typeapplication/json

object

Data

Safe selected hierarchy chain resolution.

object

State

integer format: int32

Allowed values: 0 1 2 3 4 5 6 7 8 9 10

ErrorCode

Stable guidance code for a closed or ineligible state.

string

nullable

Chain

Readable root-to-terminal chain for eligible or observable ineligible selections only.

Array<object>

nullable

One display-safe hierarchy option.

object

Id

Entity Instance identifier.

string

nullable

DisplayName

Current display name.

string

nullable

Subtitle

Optional current subtitle.

string

nullable

HasChildren

Whether at least one readable structural child exists.

boolean

CanConfirm

Whether the option may be returned as the terminal Reference value.

boolean

ConfirmationState

integer format: int32

Allowed values: 0 1 2

ConfirmationMessage

Optional safe localized explanation for a non-confirmable state.

string

nullable

SelectedValue

Compact runtime payload for one resolved or unresolved entity reference.

object

State

integer format: int32

Allowed values: 0 1 2

Id

Linked entity identifier when resolved.

string

nullable

Number

Linked entity number when resolved.

string

nullable

DisplayName

Linked entity display name from the presentation cache when resolved.

string

nullable

Subtitle

Linked entity subtitle from the presentation cache when resolved.

string

nullable

ProjectedValues

Projected primary-field scalar values and requested nested reference values keyed by target field key when resolved.

object

key

additional properties

nullable

EntityDefinitionId

Linked entity definition identifier when resolved.

string

nullable

ProjectedPlainTextPreviews

Compact server-created previews for projected Markdown fields, keyed by target field key.

object

key

additional properties

Safe compact visible-text representation of a Markdown value.

object

Text

Visible text when available.

string

nullable

IsTruncated

Whether the visible text was shortened for compact presentation.

boolean

State

integer format: int32

Allowed values: 0 1 2 3

SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object

UsageType

integer format: int32

Allowed values: 0 1 2

SemanticType

string

nullable

LinkRegistrationKey

string

nullable

CellRegistrationKey

string

nullable

Errors

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Warnings

Array<object>

nullable

object

Code

required

string

nullable

Message

required

string

nullable

Target

string

nullable

Field

string

nullable

Metadata

object

key

additional properties

string

nullable

Type

integer format: int32

Allowed values: 0 1 2

Severity

integer format: int32

Allowed values: 0 1 2

Success

boolean

Example

{
  "Data": {
    "State": 0,
    "Chain": [
      {
        "ConfirmationState": 0
      }
    ],
    "SelectedValue": {
      "State": 0,
      "ProjectedPlainTextPreviews": {
        "additionalProperty": {
          "State": 0
        }
      },
      "SemanticPresentation": {
        "UsageType": 0
      }
    }
  },
  "Errors": [
    {
      "Type": 0,
      "Severity": 0
    }
  ],
  "Warnings": [
    {
      "Type": 0,
      "Severity": 0
    }
  ]
}