Model reference

Every Surface Model contract, field, variant and value.

A Model describes the structure, data, behavior and interfaces of a Surface app. Use this reference to verify a property, explore a variant or generate sources with a tool. To learn app composition, start with the Models guide.

Reading the reference

Tables separate the exact field name, admitted values and purpose. Versions discriminate contracts; they are not business parameters to ask an end user to enter. Studio and authoring tools handle technical structure; integrators use this reference for sources and artifacts.

Validated structures

Named types and native formats

Using the reference with AI

Each page has a Markdown version and a Copy button. /llms.txt lists the pages and their addresses. Give AI the sections relevant to a change, then validate the complete Model before publication.

Applied examples : Read a complete profile and view

Compare properties with the linked contracts before inserting each fragment into the Model.

Configuration

Fragment placed in presentation.recordProfiles[]. Properties and accepted values.

{
  "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
  }
}

Variation and connection

Fragment placed in presentation.tableViews[]. Properties and accepted values.

{
  "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.

Property
Value
Reference
Validation

ILLUSTRATIVE LAYOUTClients / Quotes app

Model referenceRead a complete profile and view

Clients

MODEL CONTEXTNorth StudioDeclarative configuration

key: client
definitionPaths: 1 item
editActionKey: edit-client
identity: Declared object
valueLabels: 1 item

Values above follow the configuration fragment; references resolve in the complete Model.