Page Metadata

A Page defines a custom UI layout using components, regions, and variables. Unlike Views which are bound to a single Object, Pages are flexible containers that can combine multiple components, embed views, and manage local state.

Basic Structure

const homePage = {
  name: 'sales_home',
  label: 'Sales Home',
  type: 'home',
  regions: [
    {
      name: 'header',
      width: 'full',
      components: [
        {
          type: 'metric_card',
          id: 'total_revenue',
          label: 'Total Revenue',
          properties: {
            object: 'opportunity',
            field: 'amount',
            aggregate: 'sum',
            format: 'currency',
          },
        },
      ],
    },
    {
      name: 'main',
      width: 'large',
      components: [
        {
          type: 'list_view',
          id: 'recent_deals',
          label: 'Recent Deals',
          properties: {
            object: 'opportunity',
            view: 'recent_open',
            limit: 10,
          },
        },
      ],
    },
  ],
};

Page Properties

Page Types

Earlier roadmap types (dashboard, form, record_detail, record_review, overview, blank) were removed from the schema because they never shipped a renderer (ADR-0049 enforce-or-remove); only the five types above are valid.

Authoring modes

A page's kind selects how the body is authored. Three modes ship, and the rest of this page describes the first one:

The two source tiers set source instead of regions. source is authoritative over regions: when both are present the source wins, and regions holds at most a derived cache of it. A page whose kind is html, react or jsx with no non-empty source is rejected by the schema rather than rendering empty.

'jsx' is a deprecated alias for 'html', still accepted and converted at load time.

Because kind: 'react' executes author JavaScript, it is gated by a host capability that defaults ON and is disabled server-side per deployment with OS_PAGE_REACT=off. The html tier is unaffected by that switch — it is never executed.

Both tiers are checked at author time — block props, field bindings and source syntax — by os validate, os lint and os build alike. See React Pages for the full authoring guide and Validating metadata for the rules.

Regions

Regions define layout zones on the page. Each region contains components.

regions: [
  {
    name: 'sidebar',
    width: 'small',
    components: [/* ... */],
  },
  {
    name: 'content',
    width: 'large',
    components: [/* ... */],
  },
]

Components

Components are the building blocks placed inside regions.

{
  type: 'chart',
  id: 'revenue_chart',
  label: 'Revenue Trend',
  properties: {
    chartType: 'line',
    object: 'opportunity',
    categoryField: 'close_date',
    valueField: 'amount',
  },
  events: {
    onClick: "navigate_to('opportunity_detail', { id: $event.id })",
  },
  visibleWhen: "'sales_manager' in current_user.positions",
  style: { height: '400px' },
}

The type field is a union of the standard PageComponentType enum and any custom string. The standard (namespaced) component types include:

• Structure: page:header, page:footer, page:sidebar, page:tabs, page:accordion, page:card, page:section
• Record context: record:details, record:highlights, record:related_list, record:activity, record:chatter, record:path, record:alert, record:quick_actions, record:reference_rail, record:history — each renders from the record context a record page mounts, so they belong on a type:'record' page. A kind:'react' page mounts no such context and os validate rejects them there (see Validating metadata §10b)
• Navigation: app:launcher, nav:menu, nav:breadcrumb
• Utility: global:search, global:notifications, user:profile
• AI: ai:chat_window, ai:suggestion
• Elements: element:text, element:number, element:image, element:divider, element:button, element:record_picker, element:text_input (element:filter and element:form were retired in v17.x — no renderer ever shipped for either. List surfaces own their filtering via a view's userFilters quick-filter bar or the list toolbar's filter builder; for forms use the object-bound object-form block, which is rendered and designer-publishable)

Components may also carry dataSource (per-element object binding for multi-object pages), responsiveStyles (per-breakpoint scoped CSS, ADR-0065), and aria configuration. Custom string types are also accepted for project-specific widgets. (The former responsive layout block was retired in v17.x — no renderer ever applied it; see the upgrade guide.)

Variables

Pages can define local variables for managing state across components.

variables: [
  {
    name: 'selected_tab',
    type: 'string',
    defaultValue: 'overview',
  },
  {
    name: 'date_range',
    type: 'object',
    defaultValue: { start: null, end: null },
  },
]

Variable type accepts 'string' (default), 'number', 'boolean', 'object', 'array', or 'record_id'.

Complete Example

const accountRecordPage = {
  name: 'account_detail',
  label: 'Account Detail',
  type: 'record',
  object: 'account',
  variables: [
    { name: 'active_tab', type: 'string', defaultValue: 'details' },
  ],
  regions: [
    {
      name: 'header',
      width: 'full',
      components: [
        {
          type: 'record:highlights',
          id: 'header',
          properties: {
            fields: ['name', 'type', 'industry', 'owner'],
          },
        },
        // Record actions are their own component — `record:highlights` renders
        // field chips and nothing else.
        {
          type: 'record:quick_actions',
          properties: {
            actionNames: ['edit', 'delete', 'clone'],
          },
        },
      ],
    },
    {
      name: 'sidebar',
      width: 'small',
      components: [
        {
          type: 'record:details',
          id: 'key_fields',
          label: 'Key Fields',
          properties: {
            fields: ['annual_revenue', 'employees', 'website', 'phone'],
          },
        },
        {
          type: 'record:activity',
          id: 'activities',
          label: 'Activity',
        },
      ],
    },
    {
      name: 'main',
      width: 'large',
      components: [
        {
          type: 'record:related_list',
          id: 'contacts',
          label: 'Contacts',
          // `objectName` is the RELATED (child) object being listed;
          // `relationshipField` is the child's field pointing back at this record.
          properties: { objectName: 'contact', relationshipField: 'account' },
        },
        {
          type: 'record:related_list',
          id: 'opportunities',
          label: 'Opportunities',
          properties: { objectName: 'opportunity', relationshipField: 'account' },
        },
      ],
    },
  ],
};

Related

• View Metadata — List views and form views for record display
• Dashboard Metadata — Analytics-focused page layout
• App Metadata — Organize pages into applications
• React Pages — The html and react source-authoring tiers in full
• Validating metadata — Every author-time rule a page is held to