---
title: "workspaceTableLayout"
url: https://developers.dagio.ai/reference/workspace-table-layout/
---

# workspaceTableLayout

   
                             
                                                                               
                                        
                  
           
          
   

This reference describes the full structure of `workspaceTableLayout`. 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 |
| --- | --- | --- |
| `contract` | `"WorkspaceTableLayout@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `columns` | `Array<closed object>; min length 1; max length 40` | **Required.** Ordered columns and their authorized value sources. |
| `columns[].columnKey` | `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. |
| `columns[].visible` | `true \| false` | **Required.** Defines visible for this object. Observe the type, variants and bounds in the Options column. |
| `columns[].width` | `integer; ≥ 80; ≤ 1000; null` | **Required.** Element width in the enclosing contract’s unit. |
| `columns[].frozen` | `true \| false` | **Required.** Keeps the column visible during horizontal scrolling. |
| `columns[].format` | `closed object OR closed object OR closed object OR closed object OR closed object` | **Required.** Presentation format compatible with the value type. |
| `columns[].format.[kind=text].kind` | `"text"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `columns[].format.[kind=number].kind` | `"number"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `columns[].format.[kind=number].maximumFractionDigits` | `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. |
| `columns[].format.[kind=boolean].kind` | `"boolean"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `columns[].format.[kind=boolean].trueLabel` | `string; min length 1; max length 4000` | **Required.** Defines true Label for this object. Observe the type, variants and bounds in the Options column. |
| `columns[].format.[kind=boolean].falseLabel` | `string; min length 1; max length 4000` | **Required.** Defines false Label for this object. Observe the type, variants and bounds in the Options column. |
| `columns[].format.[variant 4].kind` | `"date" \| "datetime"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `columns[].format.[kind=badge].kind` | `"badge"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `columns[].headerFilterParameterKey` | `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. |
| `columnGroups` | `Array<closed object>; max length 20` | **Required.** Visual groups of declared columns. |
| `columnGroups[].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. |
| `columnGroups[].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `columnGroups[].columnKeys` | `Array<string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u>; min length 1; max length 40` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `grouping` | `closed object; null` | **Required.** Defines grouping for this object. Observe the type, variants and bounds in the Options column. |
| `grouping.contract` | `"WorkspaceTableGrouping@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `grouping.options` | `Array<closed object>; min length 1; max length 20` | **Required.** Suggested and admitted values for a declared choice. |
| `grouping.options[].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. |
| `grouping.options[].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `grouping.options[].columnKey` | `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. |
| `grouping.initialOptionKey` | `string; min length 1; max length 120; /^[a-z][a-z0-9-]*$/u; null` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `grouping.maximumGroups` | `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. |

## 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
{
  "contract": "WorkspaceTableLayout@1",
  "columns": [
    {
      "columnKey": "title",
      "visible": true,
      "width": null,
      "frozen": true,
      "format": {
        "kind": "text"
      },
      "headerFilterParameterKey": null
    },
    {
      "columnKey": "status",
      "visible": true,
      "width": null,
      "frozen": false,
      "format": {
        "kind": "badge"
      },
      "headerFilterParameterKey": null
    },
    {
      "columnKey": "language",
      "visible": true,
      "width": null,
      "frozen": false,
      "format": {
        "kind": "text"
      },
      "headerFilterParameterKey": null
    },
    {
      "columnKey": "chapters",
      "visible": true,
      "width": null,
      "frozen": false,
      "format": {
        "kind": "number",
        "maximumFractionDigits": 0
      },
      "headerFilterParameterKey": null
    }
  ],
  "columnGroups": [
    {
      "key": "details",
      "label": "Détails",
      "columnKeys": [
        "status",
        "language",
        "chapters"
      ]
    }
  ],
  "grouping": null
}
```

## Related references

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

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

## Applied examples : Collection columns and formats

Declare each column source before its format, order and filters.

### Configuration

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

```json
{
  "contract": "WorkspaceTableLayout@1",
  "grouping": null,
  "columns": [
    {
      "columnKey": "number",
      "visible": true,
      "width": null,
      "frozen": true,
      "format": {
        "kind": "text"
      },
      "headerFilterParameterKey": null
    },
    {
      "columnKey": "status",
      "visible": true,
      "width": null,
      "frozen": false,
      "format": {
        "kind": "badge"
      },
      "headerFilterParameterKey": null
    },
    {
      "columnKey": "amount",
      "visible": true,
      "width": null,
      "frozen": false,
      "format": {
        "kind": "number",
        "maximumFractionDigits": 2
      },
      "headerFilterParameterKey": null
    }
  ],
  "columnGroups": []
}
```

### Variation and connection

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

```json
{
  "viewKey": "quotes-table",
  "columns": [
    {
      "key": "number",
      "label": "Number",
      "source": {
        "kind": "native",
        "property": "title"
      }
    },
    {
      "key": "status",
      "label": "Status",
      "source": {
        "kind": "field",
        "fieldPath": "fields/status"
      }
    },
    {
      "key": "amount",
      "label": "Amount",
      "source": {
        "kind": "field",
        "fieldPath": "fields/amount"
      }
    }
  ],
  "openLabel": "Open quote"
}
```

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