---
title: "surfaceContextPolicyV4"
url: https://developers.dagio.ai/reference/surface-context-policy-v4/
---

# surfaceContextPolicyV4

   
                               
                                                                                 
                                           
                  
           
          
   

This reference describes the full structure of `surfaceContextPolicyV4`. 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. |
| `targetDefinitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; max length 100` | **Required.** Exact path of the relevant definition type; each reference must exist in the Model and respect declared scope. |
| `sources` | `Array<closed object OR closed object>; max length 100` | **Required.** Defines sources for this object. Observe the type, variants and bounds in the Options column. |
| `sources[].[variant 1].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. |
| `sources[].[variant 1].kind` | `"target" \| "relation" \| "query" \| "knowledge"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `sources[].[variant 1].definitionPaths` | `Array<string; min length 1; max length 600; /^workspace\/[a-z0-9-]+(?:\/surface\/[a-z0-9-]+)*$/u>; max length 100` | **Required.** Defines definition Paths for this object. Observe the type, variants and bounds in the Options column. |
| `sources[].[variant 1].linkTypePaths` | `Array<string; min length 1; max length 4000>; max length 100` | **Required.** Defines link Type Paths for this object. Observe the type, variants and bounds in the Options column. |
| `sources[].[variant 1].queryKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u; null` | **Required.** Reference to a declared Query; scope and authorization remain enforced by the data engine. |
| `sources[].[variant 1].required` | `true \| false` | **Required.** Whether a value is required by this declaration. |
| `sources[].[variant 1].revision` | `"current" \| "captured"` | **Required.** Defines revision for this object. Observe the type, variants and bounds in the Options column. |
| `sources[].[variant 1].priority` | `integer; ≥ 0; ≤ 1000` | **Required.** Defines priority for this object. Observe the type, variants and bounds in the Options column. |
| `sources[].[variant 1].maximumItems` | `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. |
| `sources[].[variant 1].maximumCharacters` | `integer; ≥ 1; ≤ 100000` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `sources[].[variant 1].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>` | **Required.** Named operation or Query parameters and their associated values. |
| `sources[].[variant 1].parameters{key}.[kind=entity-id].kind` | `"entity-id"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `sources[].[variant 1].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. |
| `sources[].[variant 1].parameters{key}.[kind=field].kind` | `"field"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `sources[].[variant 1].parameters{key}.[kind=field].field` | `closed object` | **Required.** Defines field for this object. Observe the type, variants and bounds in the Options column. |
| `sources[].[variant 1].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. |
| `sources[].[variant 1].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. |
| `sources[].[variant 1].parameters{key}.[kind=literal].kind` | `"literal"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `sources[].[variant 1].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. |
| `sources[].[kind=flow-reference].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. |
| `sources[].[kind=flow-reference].kind` | `"flow-reference"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `sources[].[kind=flow-reference].source` | `closed object OR closed object` | **Required.** Defines source for this object. Observe the type, variants and bounds in the Options column. |
| `sources[].[kind=flow-reference].source.[kind=input].kind` | `"input"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `sources[].[kind=flow-reference].source.[kind=input].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. |
| `sources[].[kind=flow-reference].source.[kind=step-output].kind` | `"step-output"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `sources[].[kind=flow-reference].source.[kind=step-output].stepKey` | `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. |
| `sources[].[kind=flow-reference].source.[kind=step-output].outputKey` | `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. |
| `sources[].[kind=flow-reference].required` | `true \| false` | **Required.** Whether a value is required by this declaration. |
| `sources[].[kind=flow-reference].revision` | `"captured"` | **Required.** Defines revision for this object. Observe the type, variants and bounds in the Options column. |
| `sources[].[kind=flow-reference].priority` | `integer; ≥ 0; ≤ 1000` | **Required.** Defines priority for this object. Observe the type, variants and bounds in the Options column. |
| `sources[].[kind=flow-reference].maximumItems` | `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. |
| `sources[].[kind=flow-reference].maximumCharacters` | `integer; ≥ 1; ≤ 100000` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `maximumCharacters` | `integer; ≥ 1; ≤ 500000` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `contract` | `"SurfaceContextPolicy@4"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `executionBindings` | `Array<closed object>; max length 100` | **Required.** Defines execution Bindings for this object. Observe the type, variants and bounds in the Options column. |
| `executionBindings[].taskActionKey` | `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. |
| `executionBindings[].applicationActionKey` | `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. |
| `executionBindings[].selection` | `"task-parent"` | **Required.** Defines selection for this object. Observe the type, variants and bounds in the Options column. |
| `executionBindings[].blueprintKey` | `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. |
| `executionBindings[].taskStepKey` | `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. |

## 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": "verification-context",
  "targetDefinitionPaths": [
    "workspace/workshop/surface/work/surface/step"
  ],
  "sources": [
    {
      "key": "target",
      "kind": "target",
      "definitionPaths": [
        "workspace/workshop/surface/work/surface/step"
      ],
      "linkTypePaths": [],
      "queryKey": null,
      "required": true,
      "revision": "current",
      "priority": 0,
      "maximumItems": 1,
      "maximumCharacters": 20000,
      "parameters": {}
    },
    {
      "key": "work-root",
      "kind": "query",
      "definitionPaths": [
        "workspace/workshop/surface/work"
      ],
      "linkTypePaths": [],
      "queryKey": "context-step-work",
      "required": true,
      "revision": "captured",
      "priority": 1,
      "maximumItems": 1,
      "maximumCharacters": 20000,
      "parameters": {
        "selectedId": {
          "kind": "entity-id",
          "definitionPath": "workspace/workshop/surface/work/surface/step"
        }
      }
    },
    {
      "key": "feature",
      "kind": "flow-reference",
      "source": {
        "kind": "input",
        "key": "feature"
      },
      "required": true,
      "revision": "captured",
      "priority": 2,
      "maximumItems": 1,
      "maximumCharacters": 20000
    },
    {
      "key": "scenarios",
      "kind": "flow-reference",
      "source": {
        "kind": "step-output",
        "stepKey": "select-scenarios",
        "outputKey": "scenarios"
      },
      "required": true,
      "revision": "captured",
      "priority": 3,
      "maximumItems": 100,
      "maximumCharacters": 80000
    }
  ],
  "maximumCharacters": 140000,
  "contract": "SurfaceContextPolicy@4",
  "executionBindings": [
    {
      "taskActionKey": "verify-feature-scenarios",
      "applicationActionKey": "execute-feature-verification",
      "selection": "task-parent",
      "blueprintKey": "prepare-feature-verification",
      "taskStepKey": "verify"
    }
  ]
}
```

## Related references

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

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

## Applied examples : A proposal grounded in context

AI receives the client and required sources within the Model policy’s bounds.

### Configuration

Contract object `surfaceContextPolicyV4`. [Properties and accepted values](https://developers.dagio.ai/reference/surface-context-policy-v4/).

```json
{
  "key": "verification-context",
  "targetDefinitionPaths": [
    "workspace/workshop/surface/work/surface/step"
  ],
  "sources": [
    {
      "key": "target",
      "kind": "target",
      "definitionPaths": [
        "workspace/workshop/surface/work/surface/step"
      ],
      "linkTypePaths": [],
      "queryKey": null,
      "required": true,
      "revision": "current",
      "priority": 0,
      "maximumItems": 1,
      "maximumCharacters": 20000,
      "parameters": {}
    },
    {
      "key": "work-root",
      "kind": "query",
      "definitionPaths": [
        "workspace/workshop/surface/work"
      ],
      "linkTypePaths": [],
      "queryKey": "context-step-work",
      "required": true,
      "revision": "captured",
      "priority": 1,
      "maximumItems": 1,
      "maximumCharacters": 20000,
      "parameters": {
        "selectedId": {
          "kind": "entity-id",
          "definitionPath": "workspace/workshop/surface/work/surface/step"
        }
      }
    },
    {
      "key": "feature",
      "kind": "flow-reference",
      "source": {
        "kind": "input",
        "key": "feature"
      },
      "required": true,
      "revision": "captured",
      "priority": 2,
      "maximumItems": 1,
      "maximumCharacters": 20000
    },
    {
      "key": "scenarios",
      "kind": "flow-reference",
      "source": {
        "kind": "step-output",
        "stepKey": "select-scenarios",
        "outputKey": "scenarios"
      },
      "required": true,
      "revision": "captured",
      "priority": 3,
      "maximumItems": 100,
      "maximumCharacters": 80000
    }
  ],
  "maximumCharacters": 140000,
  "contract": "SurfaceContextPolicy@4",
  "executionBindings": [
    {
      "taskActionKey": "verify-feature-scenarios",
      "applicationActionKey": "execute-feature-verification",
      "selection": "task-parent",
      "blueprintKey": "prepare-feature-verification",
      "taskStepKey": "verify"
    }
  ]
}
```

### Variation and connection

Fragment placed in `contextPolicies[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-model-foundation/).

```json
{
  "key": "quote-knowledge",
  "targetDefinitionPaths": [
    "workspace/quotes/surface/quote"
  ],
  "sources": [
    {
      "key": "pricing",
      "kind": "knowledge",
      "definitionPaths": [
        "workspace/knowledge/surface/pricing"
      ],
      "linkTypePaths": [],
      "queryKey": null,
      "required": true,
      "revision": "current",
      "priority": 1,
      "maximumItems": 3,
      "maximumCharacters": 12000
    }
  ],
  "maximumCharacters": 16000
}
```

### 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. Target object
2. Proposed change
3. Checks
4. Confirm

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