---
id: DOM-PFM-MTD-003
title: Form and Page Layout
realises: CON-PFM-MTD-003
product_area: platform
module: metadata
revision: 1
status: draft
design_intent: confirmed
origin: services-platform:docs/layouts.md (§2 the purpose is the authorization; §4a two console forms, Andrew 2026-10-11);
  R2-ARCH-001 v1.0 §3.3 (Andrew, 2026-10-19); custom objects architecture D-09 (approved 2026-10-18); PLAT-M5 D17
  (forms and record views, docs/milestones/PLAT-M5-custom-records.md#Decisions)
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
owned_by: SVC-PFM-MTD-layouts
readable_by: []
custom_fields: none
identity: A definition has a stable identity, one resource kind and an immutable purpose. The console owns the document
  structure; Platform validates its basic shape and size.
attributes:
- name: kind
  kind: enum
  required: true
  computed: false
  notes: Four separate resources hold console and portal forms and page layouts, allowing assignment references
    to require the correct resource kind.
- name: name
  kind: text
  required: true
  computed: false
  notes: The display name contains one to two hundred characters after whitespace is trimmed.
- name: description
  kind: text
  required: false
  computed: false
  notes: An optional description explains the definition.
- name: purpose
  kind: reference
  required: true
  computed: false
  notes: The immutable purpose identifies the record type and determines access. Registered purposes need the relevant
    presentation capability; custom-object purposes need a local draft or active object.
- name: document
  kind: collection
  required: true
  computed: false
  notes: The console defines document structure. Storage accepts a JSON object up to 256 kibibytes and returns its
    content without interpretation; object key order is not retained.
- name: version, lock and modification facts
  kind: computed
  required: true
  computed: true
  notes: Replacements and patches require the version read. Update locks prevent edits and delete locks prevent
    removal.
- name: assignment
  kind: collection
  required: false
  computed: false
  notes: The record owner selects definitions in its own transaction. Five slots cover console and portal pages,
    separate console create and edit forms, and a portal form, each recorded against a referring record or setting.
relationships:
- to: DOM-PFM-MTD-001
  cardinality: many-to-one
  ownership: The presentation definition owns the purpose reference, subject to the registry's presentation flags.
  cross_service: false
- to: DOM-PFM-MTD-004
  cardinality: many-to-one
  ownership: Custom-object purpose access uses definition administration or record-read keys and becomes unavailable
    while the object is archived.
  cross_service: false
invariants:
- id: INV-DOM-PFM-MTD-003-01
  statement: Replacement and patch cannot move a presentation definition to another purpose.
  enforced_at:
  - service
  provenance: test
  source: services-platform:modules/layouts/tests/integration/services/persistence/console-page-layouts.integration.spec.js#refuses
    a replacement that names another purpo
- id: INV-DOM-PFM-MTD-003-02
  statement: Names contain one to two hundred characters and documents are JSON objects no larger than 256 kibibytes.
  enforced_at:
  - api
  - service
  - database
  provenance: test
  source: services-platform:modules/layouts/tests/integration/services/persistence/console-page-layouts.integration.spec.js#refuses
    a layout larger than the stated maximu
- id: INV-DOM-PFM-MTD-003-03
  statement: Forms require form capability and page layouts require page-layout capability for their purpose.
  enforced_at:
  - service
  provenance: test
  source: services-platform:modules/layouts/tests/integration/services/persistence/purpose-capabilities.integration.spec.js#refuses
    a console form
- id: INV-DOM-PFM-MTD-003-04
  statement: Database assignment references require an existing definition with matching workspace, resource kind
    and purpose.
  enforced_at:
  - database
  provenance: test
  source: services-platform:modules/layouts/tests/integration/db/layout-assignments.table.integration.spec.js#refuses
    an assignment naming a definition of the wrong kind,
- id: INV-DOM-PFM-MTD-003-05
  statement: Assigned definitions cannot be removed, including when assignment and deletion race.
  enforced_at:
  - service
  - database
  provenance: test
  source: services-platform:modules/layouts/tests/integration/services/persistence/console-page-layouts.integration.spec.js#names
    every referring row, in a stable order,
- id: INV-DOM-PFM-MTD-003-06
  statement: Unreadable purposes yield not found for individual definitions and are excluded from lists.
  enforced_at:
  - api
  provenance: test
  source: services-platform:modules/layouts/tests/e2e/console-page-layouts-api.e2e.spec.js#answers 404 for a definition
    of a purpose the caller may not read, rather than
- id: INV-DOM-PFM-MTD-003-07
  statement: Edits and patches apply only at the version the caller read.
  enforced_at:
  - service
  provenance: test
  source: services-platform:modules/layouts/tests/integration/services/persistence/console-page-layouts.integration.spec.js#refuses
    the version the caller did not read
physical:
- platform.console_page_layouts
- platform.portal_page_layouts
- platform.console_forms
- platform.portal_forms
- platform.layout_assignments
evidence:
- 'services-platform at ad3f6a65: modules/layouts/purposes.ts; services/persistence/layout-resources.ts, layout-assignments.ts
  and the four resource files; db/*.table.ts, layout-resource-columns.ts; aws/api/layout-access.ts, purpose-permissions.ts;
  docs/layouts.md'
- 'react-console at baf6dae3: lib/forms/storage/console-forms.ts; lib/layout-designer/persistence.ts; lib/configuration/layout-definitions.ts'
---

# Form and Page Layout

## What It Models

Workspace forms guide entry, and page layouts arrange record presentation. The record owner chooses which definition a record or setting uses.

## Identity and Attributes

A definition has a stable identity, one resource kind and an immutable purpose. The console owns the document structure; Platform validates its basic shape and size.

## Relationships

Purposes connect definitions to eligible record categories. Assignments connect compatible definitions to the owner’s presentation slots.

## Invariants

Composite references enforce workspace, kind and purpose agreement and prevent deletion beneath an assignment. Service checks control purpose changes, capabilities and versioned edits.

## How It Is Stored and Shared

Layouts owns four definition resources. Applications write assignment rows in their own transactions through the dedicated assignment role. Route access and purpose-specific access are separate checks.

## Open Design Questions

The contact page designer still saves locally, and some approved categories lack purposes. The deployed availability of the assignment role remains outside the verified evidence.