---
title: "surfaceWorkQueryBinding"
url: https://developers.dagio.ai/reference/surface-work-query-binding/
---

# surfaceWorkQueryBinding

   
                                
                                                                                  
                                            
                  
           
          
   

This reference describes the full structure of `surfaceWorkQueryBinding`. 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. |
| `scope` | `"rootWork" \| "selectedStage" \| "retainedTarget"` | **Required.** Defines scope for this object. Observe the type, variants and bounds in the Options column. |
| `queryKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u` | **Required.** Reference to a declared Query; scope and authorization remain enforced by the data engine. |
| `parameters` | `Record<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, closed object OR closed object OR closed object>; semantic validation` | **Required.** Named operation or Query parameters and their associated values. |
| `parameters{key}.[kind=entity-id].kind` | `"entity-id"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters{key}.[kind=entity-id].definitionPath` | `string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u` | **Required.** Exact path of a definition in the Model; this is not a record instance ID. |
| `parameters{key}.[kind=field].kind` | `"field"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters{key}.[kind=field].field` | `closed object` | **Required.** Defines field for this object. Observe the type, variants and bounds in the Options column. |
| `parameters{key}.[kind=field].field.definitionPath` | `string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u` | **Required.** Exact path of a definition in the Model; this is not a record instance ID. |
| `parameters{key}.[kind=field].field.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. |
| `parameters{key}.[kind=literal].kind` | `"literal"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `parameters{key}.[kind=literal].value` | `string; max length 4000 OR number OR true \| false OR null` | **Required.** Effective value interpreted according to the enclosing type and discriminant. |

## 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": "destination",
  "scope": "rootWork",
  "queryKey": "work-destination",
  "parameters": {
    "workId": {
      "kind": "entity-id",
      "definitionPath": "workspace/workshop/surface/work"
    }
  }
}
```

## 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 `surfaceWorkQueryBinding`. [Properties and accepted values](https://developers.dagio.ai/reference/surface-work-query-binding/).

```json
{
  "key": "destination",
  "scope": "rootWork",
  "queryKey": "work-destination",
  "parameters": {
    "workId": {
      "kind": "entity-id",
      "definitionPath": "workspace/workshop/surface/work"
    }
  }
}
```

### 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 -->