---
title: "workspaceQuery"
url: https://developers.dagio.ai/reference/workspace-query/
---

# workspaceQuery

   
                       
                                                                         
                                 
                  
           
          
   

This reference describes the full structure of `workspaceQuery`. Paths include nested objects, list items and conditional branches. A branch selected by `kind`, `contract` or `mode` only admits its own properties.

## Structure and values

| Field | Options / expected values | Description |
| --- | --- | --- |
| `key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `projection` | `closed object; optional` | Optional. Defines projection for this object. Observe the type, variants and bounds in the Options column. |
| `projection.contract` | `"WorkspaceQueryProjection@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `projection.anchors` | `true \| false` | **Required.** Document section prototypes with identity, protection and cardinality. |
| `projection.calculations` | `Array<string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u>; max length 20` | **Required.** Defines calculations for this object. Observe the type, variants and bounds in the Options column. |
| `evidenceEvaluation` | `closed object; semantic validation; optional` | Optional. Defines evidence Evaluation for this object. Observe the type, variants and bounds in the Options column. |
| `evidenceEvaluation.contract` | `"WorkspaceQueryEvidenceEvaluation@1" \| "WorkspaceQueryEvidenceEvaluation@2" \| "WorkspaceQueryEvidenceEvaluation@3"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `evidenceEvaluation.sourceParameterKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `evidenceEvaluation.sourceDefinitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Exact path of the relevant definition type; each reference must exist in the Model and respect declared scope. |
| `evidenceEvaluation.evidenceDefinitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Exact path of the relevant definition type; each reference must exist in the Model and respect declared scope. |
| `evidenceEvaluation.evidencePredicates` | `Array<closed object>; max length 30` | **Required.** Defines evidence Predicates for this object. Observe the type, variants and bounds in the Options column. |
| `evidenceEvaluation.evidencePredicates[].fieldKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Key of a Field declared on the referenced Surface definition. |
| `evidenceEvaluation.evidencePredicates[].operator` | `"eq" \| "ne" \| "lt" \| "lte" \| "gt" \| "gte" \| "in" \| "exists"` | **Required.** Variant comparison or operation; its value must match the expected type. |
| `evidenceEvaluation.evidencePredicates[].value` | `string; max length 4000 OR number OR true \| false OR null OR Array<string; max length 4000 OR number OR true \| false OR null>; max length 100` | **Required.** Effective value interpreted according to the enclosing type and discriminant. |
| `evidenceEvaluation.resultDefinitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Exact path of the relevant definition type; each reference must exist in the Model and respect declared scope. |
| `evidenceEvaluation.resultLinkTypePath` | `string; min length 1; max length 4000` | **Required.** Declared relation type with sources, targets and direction compatible with this traversal. |
| `evidenceEvaluation.requiredSourceDefinitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Exact path of the relevant definition type; each reference must exist in the Model and respect declared scope. |
| `evidenceEvaluation.coveredSourceDefinitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; max length 100; optional` | Optional. Exact path of the relevant definition type; each reference must exist in the Model and respect declared scope. |
| `evidenceEvaluation.minimumResults` | `integer; ≥ 1; ≤ 1000` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `evidenceEvaluation.maximumResults` | `integer; ≥ 1; ≤ 1000` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `evidenceEvaluation.maximumPages` | `integer; ≥ 1; ≤ 100` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `evidenceEvaluation.maximumOutputBytes` | `integer; ≥ 1000; ≤ 2000000` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `evidenceEvaluation.blockingSources` | `closed object; optional` | Optional. Defines blocking Sources for this object. Observe the type, variants and bounds in the Options column. |
| `evidenceEvaluation.blockingSources.definitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Defines definition Paths for this object. Observe the type, variants and bounds in the Options column. |
| `evidenceEvaluation.blockingSources.predicates` | `Array<closed object>; min length 1; max length 30` | **Required.** Typed conditions restricting objects within the declared scope. |
| `evidenceEvaluation.blockingSources.predicates[].fieldKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Key of a Field declared on the referenced Surface definition. |
| `evidenceEvaluation.blockingSources.predicates[].operator` | `"eq" \| "ne" \| "lt" \| "lte" \| "gt" \| "gte" \| "in" \| "exists"` | **Required.** Variant comparison or operation; its value must match the expected type. |
| `evidenceEvaluation.blockingSources.predicates[].value` | `string; max length 4000 OR number OR true \| false OR null OR Array<string; max length 4000 OR number OR true \| false OR null>; max length 100` | **Required.** Effective value interpreted according to the enclosing type and discriminant. |
| `evidenceEvaluation.additionalBlockingSources` | `Array<closed object>; min length 1; max length 20; optional` | Optional. Defines additional Blocking Sources for this object. Observe the type, variants and bounds in the Options column. |
| `evidenceEvaluation.additionalBlockingSources[].definitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Defines definition Paths for this object. Observe the type, variants and bounds in the Options column. |
| `evidenceEvaluation.additionalBlockingSources[].predicates` | `Array<closed object>; min length 1; max length 30` | **Required.** Typed conditions restricting objects within the declared scope. |
| `evidenceEvaluation.additionalBlockingSources[].predicates[].fieldKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Key of a Field declared on the referenced Surface definition. |
| `evidenceEvaluation.additionalBlockingSources[].predicates[].operator` | `"eq" \| "ne" \| "lt" \| "lte" \| "gt" \| "gte" \| "in" \| "exists"` | **Required.** Variant comparison or operation; its value must match the expected type. |
| `evidenceEvaluation.additionalBlockingSources[].predicates[].value` | `string; max length 4000 OR number OR true \| false OR null OR Array<string; max length 4000 OR number OR true \| false OR null>; max length 100` | **Required.** Effective value interpreted according to the enclosing type and discriminant. |
| `search` | `closed object; null; optional` | Optional. Search policy or configuration according to the enclosing context. |
| `search.parameterKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `search.mode` | `"lexical" \| "phrase" \| "prefix"` | **Required.** Defines mode for this object. Observe the type, variants and bounds in the Options column. |
| `spaceKeys` | `Array<string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u>; min length 1; max length 20` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `definitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Defines definition Paths for this object. Observe the type, variants and bounds in the Options column. |
| `parameters` | `Array<closed object OR closed object OR closed object OR closed object OR closed object; semantic validation>; max length 20` | **Required.** Named operation or Query parameters and their associated values. |
| `parameters[].[variant 1].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 1].type` | `"text" \| "number" \| "boolean" \| "node-id"` | **Required.** Defines type for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 1].required` | `true \| false` | **Required.** Whether a value is required by this declaration. |
| `parameters[].[variant 2].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 2].type` | `"decimal"` | **Required.** Defines type for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 2].required` | `true \| false` | **Required.** Whether a value is required by this declaration. |
| `parameters[].[variant 2].format` | `closed object; semantic validation` | **Required.** Presentation format compatible with the value type. |
| `parameters[].[variant 2].format.precision` | `integer; ≥ 1; ≤ 1000` | **Required.** Defines precision for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 2].format.scale` | `integer; ≥ 0; ≤ 1000` | **Required.** Defines scale for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 2].unit` | `closed object OR closed object OR closed object` | **Required.** Defines unit for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 2].unit.[kind=dimensionless].kind` | `"dimensionless"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 2].unit.[kind=unit].kind` | `"unit"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 2].unit.[kind=unit].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 2].unit.[kind=currency].kind` | `"currency"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 2].unit.[kind=currency].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 3].[variant 1].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 3].[variant 1].type` | `"integer"` | **Required.** Defines type for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 1].required` | `true \| false` | **Required.** Whether a value is required by this declaration. |
| `parameters[].[variant 3].[variant 1].schema` | `closed object` | **Required.** Defines schema for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 1].schema.kind` | `"integer"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 3].[variant 1].schema.minimum` | `string; max length 1001; /^(?:0\|-?[1-9][0-9]{0,999})(?![\s\S])/u` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `parameters[].[variant 3].[variant 1].schema.maximum` | `string; max length 1001; /^(?:0\|-?[1-9][0-9]{0,999})(?![\s\S])/u` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `parameters[].[variant 3].[variant 1].schema.unit` | `closed object OR closed object OR closed object` | **Required.** Defines unit for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 1].schema.unit.[kind=dimensionless].kind` | `"dimensionless"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 3].[variant 1].schema.unit.[kind=unit].kind` | `"unit"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 3].[variant 1].schema.unit.[kind=unit].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 3].[variant 1].schema.unit.[kind=currency].kind` | `"currency"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 3].[variant 1].schema.unit.[kind=currency].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 3].[variant 2].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 3].[variant 2].type` | `"real"` | **Required.** Defines type for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 2].required` | `true \| false` | **Required.** Whether a value is required by this declaration. |
| `parameters[].[variant 3].[variant 2].schema` | `closed object` | **Required.** Defines schema for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 2].schema.kind` | `"real"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 3].[variant 2].schema.representation` | `"binary64"` | **Required.** Defines representation for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 2].schema.precisionBits` | `53` | **Required.** Defines precision Bits for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 2].schema.minimum` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `parameters[].[variant 3].[variant 2].schema.maximum` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `parameters[].[variant 3].[variant 2].schema.tolerance` | `closed object` | **Required.** Defines tolerance for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 2].schema.tolerance.absolute` | `number; ≥ 0` | **Required.** Defines absolute for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 2].schema.tolerance.relative` | `number; ≥ 0` | **Required.** Defines relative for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 2].schema.unit` | `closed object OR closed object` | **Required.** Defines unit for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 2].schema.unit.[kind=dimensionless].kind` | `"dimensionless"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 3].[variant 2].schema.unit.[kind=unit].kind` | `"unit"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 3].[variant 2].schema.unit.[kind=unit].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 3].[variant 3].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 3].[variant 3].type` | `"choice"` | **Required.** Defines type for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 3].required` | `true \| false` | **Required.** Whether a value is required by this declaration. |
| `parameters[].[variant 3].[variant 3].schema` | `closed object` | **Required.** Defines schema for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 3].schema.kind` | `"choice"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters[].[variant 3].[variant 3].schema.labelLocale` | `string; min length 2; max length 100; /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*(?![\s\S])/u` | **Required.** Defines label Locale for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 3].schema.choices` | `Array<closed object>; min length 1; max length 1000` | **Required.** Defines choices for this object. Observe the type, variants and bounds in the Options column. |
| `parameters[].[variant 3].[variant 3].schema.choices[].key` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*(?![\s\S])/u` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `parameters[].[variant 3].[variant 3].schema.choices[].labels` | `Record<string; min length 2; max length 100; /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*(?![\s\S])/u, string; min length 1; max length 4000>` | **Required.** Defines labels for this object. Observe the type, variants and bounds in the Options column. |
| `predicates` | `Array<closed object>; max length 30` | **Required.** Typed conditions restricting objects within the declared scope. |
| `predicates[].fieldKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Key of a Field declared on the referenced Surface definition. |
| `predicates[].operator` | `"eq" \| "ne" \| "lt" \| "lte" \| "gt" \| "gte" \| "in" \| "exists"` | **Required.** Variant comparison or operation; its value must match the expected type. |
| `predicates[].parameterKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u; null` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `predicates[].value` | `string; max length 4000 OR number OR true \| false OR null OR Array<string; max length 4000 OR number OR true \| false OR null>; max length 100` | **Required.** Effective value interpreted according to the enclosing type and discriminant. |
| `relations` | `Array<closed object>; max length 8` | **Required.** Relation traversal restricting or expanding read results. |
| `relations[].linkTypePath` | `string; min length 1; max length 4000` | **Required.** Defines link Type Path for this object. Observe the type, variants and bounds in the Options column. |
| `relations[].direction` | `"incoming" \| "outgoing"` | **Required.** Traversal or presentation direction using this contract’s closed values. |
| `relations[].parameterKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `relations[].distinct` | `true \| false` | **Required.** Removes repeated identities where the operation admits this option. |
| `orderBy` | `Array<closed object>; max length 5` | **Required.** Declared sort order using keys within the authorized scope. |
| `orderBy[].fieldKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Key of a Field declared on the referenced Surface definition. |
| `orderBy[].direction` | `"ascending" \| "descending"` | **Required.** Traversal or presentation direction using this contract’s closed values. |
| `aggregate` | `"none" \| "count" \| "count-distinct"` | **Required.** Reduction across the complete Query scope, distinct from the displayed page. |
| `pageSize` | `integer; ≥ 1; ≤ 100` | **Required.** Requested items per page within Query limits. |
| `maximumDepth` | `integer; ≥ 0; ≤ 8` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `traversal` | `closed object; semantic validation; optional` | Optional. Defines traversal for this object. Observe the type, variants and bounds in the Options column. |
| `traversal.contract` | `"WorkspaceQueryTraversal@1" \| "WorkspaceQueryTraversal@2"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `traversal.sourceParameterKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `traversal.sourceDefinitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Exact path of the relevant definition type; each reference must exist in the Model and respect declared scope. |
| `traversal.within` | `closed object; optional` | Optional. Defines within for this object. Observe the type, variants and bounds in the Options column. |
| `traversal.within.parameterKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u OR string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `traversal.within.definitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Defines definition Paths for this object. Observe the type, variants and bounds in the Options column. |
| `traversal.within.maximumDepth` | `integer; ≥ 1; ≤ 8` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `traversal.paths` | `Array<closed object>; min length 1; max length 8` | **Required.** Defines paths for this object. Observe the type, variants and bounds in the Options column. |
| `traversal.paths[].steps` | `Array<closed object OR closed object>; min length 1; max length 8` | **Required.** Composition steps in their declared organization. |
| `traversal.paths[].steps[].[kind=links].kind` | `"links"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `traversal.paths[].steps[].[kind=links].direction` | `"incoming" \| "outgoing"` | **Required.** Traversal or presentation direction using this contract’s closed values. |
| `traversal.paths[].steps[].[kind=links].linkTypePaths` | `Array<string; min length 1; max length 4000>; min length 1; max length 20` | **Required.** Defines link Type Paths for this object. Observe the type, variants and bounds in the Options column. |
| `traversal.paths[].steps[].[kind=links].definitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Defines definition Paths for this object. Observe the type, variants and bounds in the Options column. |
| `traversal.paths[].steps[].[variant 2].kind` | `"parent" \| "children"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `traversal.paths[].steps[].[variant 2].definitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; min length 1; max length 100` | **Required.** Defines definition Paths for this object. Observe the type, variants and bounds in the Options column. |
| `nativeReview` | `closed object; optional` | Optional. Canonical review configuration with decision Fields and references. |
| `nativeReview.contract` | `"WorkspaceQueryNativeReview@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `nativeReview.lifecycleKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `nativeReview.stateValue` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u` | **Required.** Defines state Value for this object. Observe the type, variants and bounds in the Options column. |
| `controls` | `closed object; optional` | Optional. Search, filter and sorting controls connected to declared parameters. |
| `controls.contract` | `"WorkspaceQueryControls@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `controls.filters` | `Array<closed object OR closed object>; max length 20` | **Required.** Defines filters for this object. Observe the type, variants and bounds in the Options column. |
| `controls.filters[].[variant 1].parameterKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9-]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `controls.filters[].[variant 1].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `controls.filters[].[variant 1].input` | `"choice"` | **Required.** Control or input selected by the variant; must remain compatible with its binding. |
| `controls.filters[].[variant 1].options` | `Array<closed object>; min length 1; max length 100` | **Required.** Suggested and admitted values for a declared choice. |
| `controls.filters[].[variant 1].options[].value` | `string; max length 4000 OR number OR true \| false` | **Required.** Effective value interpreted according to the enclosing type and discriminant. |
| `controls.filters[].[variant 1].options[].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `controls.filters[].[variant 2].parameterKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9-]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `controls.filters[].[variant 2].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `controls.filters[].[variant 2].input` | `"text" \| "number" \| "decimal" \| "integer" \| "real"` | **Required.** Control or input selected by the variant; must remain compatible with its binding. |
| `controls.sort` | `closed object; null` | **Required.** Defines sort for this object. Observe the type, variants and bounds in the Options column. |
| `controls.sort.parameterKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9-]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `controls.sort.label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `controls.sort.options` | `Array<closed object>; min length 1; max length 30` | **Required.** Suggested and admitted values for a declared choice. |
| `controls.sort.options[].value` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9-]*$/u` | **Required.** Effective value interpreted according to the enclosing type and discriminant. |
| `controls.sort.options[].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `controls.sort.options[].orderBy` | `Array<closed object>; min length 1; max length 5` | **Required.** Declared sort order using keys within the authorized scope. |
| `controls.sort.options[].orderBy[].fieldKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Key of a Field declared on the referenced Surface definition. |
| `controls.sort.options[].orderBy[].direction` | `"ascending" \| "descending"` | **Required.** Traversal or presentation direction using this contract’s closed values. |
| `contract` | `"WorkspaceQuery@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |

## Reading the contract

A path ending in `[]` describes each list item; `{key}` describes each dictionary value. The `↻` marker refers to the same recursive expression. Closed objects reject additional properties. Semantic validation denotes an additional check: matching a type does not make a reference, permission or transition valid. References must resolve in the Model and the current user context.

An older variant cannot accept properties belonging to a newer variant. The compiler checks the version and consistency of the complete Model.

## Structural example

This fragment passes the schema for this section. Its business references must be defined in the enclosing Model.

```json
{
  "key": "context-step-work",
  "label": "Travail parent de l’étape",
  "spaceKeys": [
    "work"
  ],
  "definitionPaths": [
    "workspace/workshop/surface/work"
  ],
  "parameters": [
    {
      "key": "selectedId",
      "type": "node-id",
      "required": true
    }
  ],
  "predicates": [],
  "relations": [],
  "orderBy": [
    {
      "fieldKey": "title",
      "direction": "ascending"
    }
  ],
  "aggregate": "none",
  "pageSize": 30,
  "maximumDepth": 1,
  "traversal": {
    "contract": "WorkspaceQueryTraversal@2",
    "sourceParameterKey": "selectedId",
    "sourceDefinitionPaths": [
      "workspace/workshop/surface/work/surface/step"
    ],
    "paths": [
      {
        "steps": [
          {
            "kind": "parent",
            "definitionPaths": [
              "workspace/workshop/surface/work"
            ]
          }
        ]
      }
    ]
  },
  "contract": "WorkspaceQuery@1"
}
```

## Related references

[Complete Model index](https://developers.dagio.ai/reference/) · [Build a Model](https://developers.dagio.ai/models/)

<!-- surface-examples:start -->

## Applied examples : Quotes for the current client

The Query declares clientId; the binding supplies the identity of the open record.

### Configuration

Contract object `workspaceQuery`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-query/).

```json
{
  "key": "context-step-work",
  "label": "Travail parent de l’étape",
  "spaceKeys": [
    "work"
  ],
  "definitionPaths": [
    "workspace/workshop/surface/work"
  ],
  "parameters": [
    {
      "key": "selectedId",
      "type": "node-id",
      "required": true
    }
  ],
  "predicates": [],
  "relations": [],
  "orderBy": [
    {
      "fieldKey": "title",
      "direction": "ascending"
    }
  ],
  "aggregate": "none",
  "pageSize": 30,
  "maximumDepth": 1,
  "traversal": {
    "contract": "WorkspaceQueryTraversal@2",
    "sourceParameterKey": "selectedId",
    "sourceDefinitionPaths": [
      "workspace/workshop/surface/work/surface/step"
    ],
    "paths": [
      {
        "steps": [
          {
            "kind": "parent",
            "definitionPaths": [
              "workspace/workshop/surface/work"
            ]
          }
        ]
      }
    ]
  },
  "contract": "WorkspaceQuery@1"
}
```

### Variation and connection

Fragment placed in `presentation.recordProfiles[].queryBindings[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-record-query-binding/).

```json
{
  "key": "client-quotes",
  "queryKey": "client-quotes",
  "parameters": {
    "clientId": {
      "kind": "entity-id",
      "definitionPath": "workspace/clients/surface/client"
    }
  }
}
```

### UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Number
2. Status
3. Amount
4. Last updated

<!-- surface-examples:end -->