Summary
Resolve two explicit anchors into a contiguous document range. Returns a transparent SelectionTarget, a mutation-ready ref, and preview metadata. Stateless and deterministic.- Operation ID:
ranges.resolve - API member path:
editor.doc.ranges.resolve(...) - Mutates document:
no - Idempotency:
idempotent - Supports tracked mode:
no - Supports dry run:
no - Deterministic target resolution:
yes
Expected result
Returns a ResolveRangeOutput with evaluatedRevision, handle.ref, target (SelectionTarget), and preview metadata.Input fields
| Field | Type | Required | Description |
|---|---|---|---|
end | object(kind=“document”) | object(kind=“point”) | object(kind=“ref”) | yes | One of: object(kind=“document”), object(kind=“point”), object(kind=“ref”) |
expectedRevision | string | no | |
start | object(kind=“document”) | object(kind=“point”) | object(kind=“ref”) | yes | One of: object(kind=“document”), object(kind=“point”), object(kind=“ref”) |
Example request
{
"end": {
"edge": "start",
"kind": "document"
},
"expectedRevision": "rev-001",
"start": {
"edge": "start",
"kind": "document"
}
}
Output fields
| Field | Type | Required | Description |
|---|---|---|---|
evaluatedRevision | string | yes | |
handle | object(refStability=“ephemeral”) | yes | |
handle.coversFullTarget | boolean | yes | |
handle.ref | string | null | yes | One of: string, null |
handle.refStability | "ephemeral" | yes | Constant: "ephemeral" |
preview | object | yes | |
preview.blocks | object[] | yes | |
preview.text | string | yes | |
preview.truncated | boolean | yes | |
target | SelectionTarget | yes | SelectionTarget |
target.end | SelectionPoint | yes | SelectionPoint |
target.kind | "selection" | yes | Constant: "selection" |
target.start | SelectionPoint | yes | SelectionPoint |
Example response
{
"evaluatedRevision": "rev-001",
"handle": {
"coversFullTarget": true,
"ref": "handle:abc123",
"refStability": "ephemeral"
},
"preview": {
"blocks": [
{
"nodeId": "node-def456",
"nodeType": "paragraph",
"textPreview": "example"
}
],
"text": "Hello, world.",
"truncated": true
},
"target": {
"end": {
"blockId": "block-abc123",
"kind": "text",
"offset": 0
},
"kind": "selection",
"start": {
"blockId": "block-abc123",
"kind": "text",
"offset": 0
}
}
}
Pre-apply throws
INVALID_INPUTINVALID_TARGETTARGET_NOT_FOUNDINVALID_CONTEXTREVISION_MISMATCH
Non-applied failure codes
- None
Raw schemas
Raw input schema
Raw input schema
{
"additionalProperties": false,
"properties": {
"end": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"edge": {
"enum": [
"start",
"end"
]
},
"kind": {
"const": "document"
}
},
"required": [
"kind",
"edge"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "point"
},
"point": {
"$ref": "#/$defs/SelectionPoint"
}
},
"required": [
"kind",
"point"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"boundary": {
"enum": [
"start",
"end"
]
},
"kind": {
"const": "ref"
},
"ref": {
"minLength": 1,
"type": "string"
}
},
"required": [
"kind",
"ref",
"boundary"
],
"type": "object"
}
]
},
"expectedRevision": {
"type": "string"
},
"start": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"edge": {
"enum": [
"start",
"end"
]
},
"kind": {
"const": "document"
}
},
"required": [
"kind",
"edge"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "point"
},
"point": {
"$ref": "#/$defs/SelectionPoint"
}
},
"required": [
"kind",
"point"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"boundary": {
"enum": [
"start",
"end"
]
},
"kind": {
"const": "ref"
},
"ref": {
"minLength": 1,
"type": "string"
}
},
"required": [
"kind",
"ref",
"boundary"
],
"type": "object"
}
]
}
},
"required": [
"start",
"end"
],
"type": "object"
}
Raw output schema
Raw output schema
{
"additionalProperties": false,
"properties": {
"evaluatedRevision": {
"type": "string"
},
"handle": {
"additionalProperties": false,
"properties": {
"coversFullTarget": {
"type": "boolean"
},
"ref": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"refStability": {
"const": "ephemeral"
}
},
"required": [
"ref",
"refStability",
"coversFullTarget"
],
"type": "object"
},
"preview": {
"additionalProperties": false,
"properties": {
"blocks": {
"items": {
"additionalProperties": false,
"properties": {
"nodeId": {
"type": "string"
},
"nodeType": {
"enum": [
"paragraph",
"heading",
"listItem",
"table",
"tableRow",
"tableCell",
"tableOfContents",
"image",
"sdt"
]
},
"textPreview": {
"type": "string"
}
},
"required": [
"nodeId",
"nodeType",
"textPreview"
],
"type": "object"
},
"type": "array"
},
"text": {
"type": "string"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"text",
"truncated",
"blocks"
],
"type": "object"
},
"target": {
"$ref": "#/$defs/SelectionTarget"
}
},
"required": [
"evaluatedRevision",
"handle",
"target",
"preview"
],
"type": "object"
}