# Resources: data as files

The data layer: file-backed records, the .meta file that describes them, and the conventions every resource follows.

## 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.

```json
{
  "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