Resources: data as files

Structure

ext/data/<resource>/
  .meta          → field definitions and configuration (JSON)
  <uuid>         → one record per file (JSON, no extension)

Example:

ext/data/articles/
  ├── .meta
  ├── a1b2c3d4e5f6g7h8
  └── z9y8x7w6v5u4t3s2

.meta file

Defines the structure and behavior of a resource. All fields must be explicitly configured.

{
  "fields": {
    "title": {
      "name": "Title",
      "type": "text",
      "required": true
    },
    "title_slug": {
      "name": "URL slug",
      "type": "slug",
      "source": "title"
    },
    "published": {
      "name": "Published",
      "type": "boolean"
    },
    "body": {
      "name": "Body",
      "type": "html",
      "buttons": "h2,h3,h4,bold,italic,orderedlist,unorderedlist,quote,anchor",
      "media": true,
      "media_sizes": "sm-90,md-70,lg-60,xl-50,xxl-40",
      "admin_col": false
    },
    "sort_order": {
      "name": "Sort order",
      "type": "text",
      "admin_col": false
    }
  },
  "sort": {
    "field": "sort_order",
    "flags": "numeric",
    "order": "asc"
  }
}

System fields (auto-managed)

Every record automatically has: uuid, _created, _modified, _created_by, _modified_by. Never define these in .meta.

Resource conventions (required)

These rules are mandatory for all resources unless explicitly stated otherwise.

Always include:

• "required": true on all name/title fields
• published boolean field on content resources
• sort_order field + sort config on list resources (partners, logos, cards, team members, etc.)
• "admin_col": false on images, html, urls, large text, and technical fields like sort_order

Always consider:

• Does this resource need a published field?
• Does ordering matter? Add sort_order + sort
• Is this linked from a URL? Add a slug field and list it in index
• Does any field need to be unique? Add it to unique; a unique field is indexed by itself
• Does the admin overview need a specific column order? Use admin_columns, including _modified and _created when useful
• Does content need to be translated? Add languages and i18n per field
• Can this be smaller while still fully solving the current requirement?
• Can existing system metadata or a single field index solve this without extra custom fields?

Admin visibility - fields to hide by default:

• images
• html content
• urls
• large text fields
• sort_order and other technical fields