---
title: "Build a Model"
url: https://developers.dagio.ai/models/
---

# Build a Model

   
                      
                                                                       
              
              
         
   

## Start with your activity

A Model describes what an app organizes and lets people do. For Clients, begin with record information, useful collections and meaningful Actions. Tools handle packaging and technical contract versions; those details are not the starting point for business design.

Compose the Model in Studio or ask AI to propose a structure. AI changes the same definitions you do. Inspect added objects, Fields, views and operations before applying a proposal.

| Model area | Expected values or content | Purpose |
| --- | --- | --- |
| Objects | Client, Quote, Contact | Define record types |
| Fields | Typed values and constraints | Describe record data |
| Views | Record, table, graph or composition | Present information |
| Queries | Sources, parameters, filters and aggregates | Define what is retrieved |
| Actions | Operation, context and optional Form | Define what users can do |
| Flows | Steps, dependencies and results | Organize durable work |
| Rules | Admitted conditions and effects | Control validation and transitions |
| Publication | Identity, dependencies and migration | Distribute and evolve the app |

## Build progressively

1. Define Client with Company, Email, Status and Notes.
2. Place content Fields in the Surface and configuration in Settings.
3. Define Active clients and select table columns.
4. Add New client and its creation Form.
5. Try creation, editing and search in the preview.
6. Add Quotes and configure its link to Client.

Keep everyday views in the main navigation. Other collections remain accessible in **Other views** without crowding the sidebar: for example, Clients and Quotes at the first level, with records needing another review in the menu. Their placement changes neither their content nor the access required to read them. A count shows the authorized total for its declared selection, independently of the list filters; an unavailable read is not a total of zero.

## Validate before publishing

In a private preview, open a record to inspect its document and Fields. If the Model declares an edit Form, use that Form to review and confirm your changes in the same record editor. The preview does not add a separate Save operation that the Model has not declared. Unsaved input can be resumed in the original preview after a fresh access check; a changed record is not silently merged or rebased. External providers and triggers remain blocked during this isolated test.

In preview collections, browse groups and their records using the grouping choices declared by the Model. Form selectors verify the chosen record within that same test, without opening another account’s data.

Your column, width and density choices stay personal to that preview table; they change neither the Model nor its record values.

The AI context identifies the private destination and record you are viewing, along with its saved version and whether you have unsaved input. It does not automatically include the whole document. An explicit document read uses that exact saved version and respects the Model’s AI-disclosure rules, including for effective Fields and their references. Unsaved input is not presented as saved content. This private preview does not publish your Model source or switch your account to the test environment.

For an archived or logically deleted record, authorized consultation reads the inactive version currently displayed. An older source citation remains distinct and does not silently select its former active body. This read does not authorize editing or restoration.

An archived source in this preview can be consulted read-only. Its cited reference stays separate
from the current archived version being viewed; opening the record does not reactivate it or permit
Save or restore. A changed version or access stops this read.

If preparation remains unacknowledged, you can request closure of its original reservation. Surface closes it this way only if it was never admitted, then prevents that same preparation from starting later. This gesture does not delete an already prepared preview: resume its original request. A confirmed closure whose local cleanup failed does not resend the native operation.

Validation checks types and references: displayed Fields must exist, views must use declared Queries, and Actions must target recognized operations. UI composition does not create a separate data engine or bypass permissions.

When the Model declares a Work experience, use its own steps, collections, criteria and destination
inside the private preview. Inspect the Flow and review an available manual intervention before
confirming it. Sources keep the original citation distinct from the version displayed; opening a
record is not a replacement for comparing an older cited version. A missing comparison or external
execution capability is reported explicitly. Resuming a retained review opens its original preview
and preserves its original request; it does not silently prepare or submit a new one.

## Sources and advanced reference

When the publisher permits it and you have the required access, create a private adaptation of a Model’s source without replacing the current app or its content. Review the chosen name and publisher’s terms before confirming. Creating the private source is distinct from compiling, publishing, activating or migrating it; public redistribution is not granted by this step. If creation is confirmed but opening the source fails, resume only opening it. If the outcome is unknown, [resume the original request](https://developers.dagio.ai/retries/) rather than create another adaptation.

Account erasure includes cleaning up private previews attached to its authoring scope before removing their registrations and private sources. A closed label or a removed directory entry does not replace confirmation that the content was cleaned up. Without that confirmation, finalization remains blocked; it grants no access to previews belonging to another account.

Models can be stored as structured sources. The [complete reference](https://developers.dagio.ai/reference/) describes exact contracts and variants. Names such as `ManagedModelSource@1` identify a source format: they belong to integration and compilation, rather than information an end user fills in on a record.
## Declare a complete Gantt view

A Gantt view declares five mandatory mappings to scalar Fields: `start` and `end` dates, numeric `duration` and
`progress`, and the `milestone` boolean. Its `schedule` declares `durationUnit` (`millisecond`,
`hour` or `day`), `progressScale` (`ratio` or `percent`), and a `dependencies` list. Each dependency
names the exact `linkTypePath` and whether its `predecessor` is the `source` or `target` endpoint.
The compiler rejects incomplete mappings; titles never determine a Field, milestone or Link direction.
The Fields themselves may remain optional: a Task does not need scheduling data to be created.

The view displays progress, milestones and directed dependencies alongside the recorded dates.
Its critical path uses finish-to-start dependencies and the declared elapsed durations across the
complete authorized Query scope, not just the visible page. It does not move dates or infer a
working-day calendar. A cycle, an uncovered endpoint or an incomplete snapshot is an explicit
refusal, not a partial critical path. The same permissions and source protections apply to every
item and both ends of each dependency; human viewing and AI disclosure remain distinct.
Unscheduled items keep their known dates and values and explicitly list their missing Fields.
The critical path remains non-evaluable while any item lacks scheduling facts; no zero progress,
duration or milestone is invented to complete it.

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

## Applied examples : Assemble a coherent definition

The Form and record profile reference the same company, status and notes Fields.

### Configuration

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

```json
{
  "contract": "WorkspaceForm@2",
  "key": "new-client",
  "label": "New client",
  "actionKey": "create-client",
  "targetDefinitionPath": "workspace/clients/surface/client",
  "mode": "create",
  "fields": [
    {
      "contract": "WorkspaceFormControl@2",
      "repeatable": false,
      "key": "company",
      "label": "Company",
      "input": "text",
      "binding": {
        "kind": "field",
        "fieldKey": "company"
      },
      "required": true,
      "ruleKeys": [],
      "options": []
    },
    {
      "contract": "WorkspaceFormControl@2",
      "repeatable": false,
      "key": "status",
      "label": "Status",
      "input": "choice",
      "binding": {
        "kind": "field",
        "fieldKey": "status"
      },
      "required": true,
      "ruleKeys": [],
      "options": [
        "prospect",
        "active"
      ]
    }
  ],
  "ruleKeys": []
}
```

### Variation and connection

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

```json
{
  "key": "client",
  "definitionPaths": [
    "workspace/clients/surface/client"
  ],
  "editActionKey": "edit-client",
  "identity": {
    "title": {
      "kind": "field",
      "fieldPath": "fields/company"
    },
    "avatar": {
      "kind": "initials",
      "maximumLetters": 2
    },
    "subtitle": {
      "kind": "field",
      "fieldPath": "fields/status"
    }
  },
  "valueLabels": [
    {
      "fieldPath": "fields/status",
      "values": [
        {
          "value": "prospect",
          "label": "Prospect"
        },
        {
          "value": "active",
          "label": "Active"
        }
      ]
    }
  ],
  "card": {
    "summary": {
      "kind": "field",
      "fieldPath": "fields/notes"
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "metricKeys": [],
    "openLabel": "Open client"
  },
  "queryBindings": [],
  "metrics": [],
  "detail": {
    "primaryActionKey": null,
    "creationActionKeys": [],
    "actionKeys": [],
    "sections": [
      {
        "kind": "fields",
        "key": "follow-up",
        "label": "Client follow-up",
        "fieldPaths": [
          "fields/notes",
          "fields/status"
        ]
      }
    ],
    "settings": {
      "fieldPaths": [
        "fields/email"
      ]
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "relatedGroups": [],
    "primaryActionLabel": null
  }
}
```

### 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. Clients · Data
2. References · Knowledge
3. Preparation · Work
4. Quotes · Product

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