definition.json: fields and defaults

This file describes what content the owner can change: field names, types, limits and starting values. Think of it as the shape of the content object your components receive.

The following complete example is reused throughout these guides. Its owner edits an opening section, up to six service cards, and shared business details. The labels are examples: write labels in the language your owners use.

definition.json

{
  "contractVersion": 1,
  "presentationId": "studio",
  "version": 1,
  "name": "Studio website",
  "routes": ["/"],
  "fields": [
    {
      "id": "hero",
      "label": "Opening section",
      "type": "group",
      "required": true,
      "fields": [
        {
          "id": "title",
          "label": "Main headline",
          "type": "text",
          "required": true,
          "maxLength": 120
        },
        {
          "id": "summary",
          "label": "Short introduction",
          "type": "text",
          "maxLength": 600
        },
        {
          "id": "image",
          "label": "Cover image",
          "type": "asset"
        }
      ]
    },
    {
      "id": "showServices",
      "label": "Show services",
      "type": "boolean"
    },
    {
      "id": "services",
      "label": "Services",
      "type": "list",
      "required": true,
      "minItems": 1,
      "maxItems": 6,
      "fields": [
        {
          "id": "title",
          "label": "Service name",
          "type": "text",
          "required": true,
          "maxLength": 80
        },
        {
          "id": "summary",
          "label": "Description",
          "type": "text",
          "maxLength": 500
        },
        {
          "id": "image",
          "label": "Service image",
          "type": "asset"
        },
        {
          "id": "href",
          "label": "Read more link",
          "type": "link"
        }
      ]
    },
    {
      "id": "business",
      "label": "Business details",
      "type": "group",
      "required": true,
      "fields": [
        {
          "id": "name",
          "label": "Business name",
          "type": "text",
          "required": true,
          "maxLength": 120
        },
        {
          "id": "phone",
          "label": "Phone number",
          "type": "text",
          "maxLength": 40
        }
      ]
    }
  ],
  "defaults": {
    "hero": {
      "title": "Design that moves your business forward",
      "summary": "Meet the studio and explore our work."
    },
    "showServices": true,
    "services": [
      {
        "title": "Brand design",
        "summary": "A visual identity built around your business.",
        "href": "/contact-us"
      }
    ],
    "business": {
      "name": "Studio",
      "phone": "+972501234567"
    }
  }
}

Identity and versions

• presentationId identifies this presentation; keep it stable across its releases.
• name is a human-readable name.
• version is your content-definition version. When changing an existing content shape, plan how saved values move to the next version in migrations.json.
• contractVersion: 1 identifies the file format. It is unrelated to version, the npm SDK version, or the CLI version.
• routes is a required contract field and must include /. Use ["/"] for this presentation; you do not need to list the platform’s managed routes.

Blog routes belong to the platform

The SDK generates blog listing, pagination and article routes automatically from the platform’s blogs and content. You do not register /blogs/:blogSlug or /blogs/:blogSlug/:slug in this file. The platform also supplies managed editorial-page and contact routes.

routes is not a switch for enabling or disabling those pages: omitting their paths does not remove them. Adding a custom path here does not create an Astro page either.

Separately, data.json can request articles to display in your homepage components. That request reads platform content; it does not register blog routes or require you to build a blog.

Fields become values

A field id is a machine-readable key; its label is what the owner sees. A group creates a nested object. A list creates an array of objects. In the example:

Definition	Value in a component
hero → title	content.hero.title
showServices	content.showServices
services → item → title	content.services[0].title
business → phone	content.business.phone

Use the field-type guide to choose types and see their dashboard controls. IDs start with a lowercase letter and contain letters, digits, underscores or hyphens. IDs must be unique among siblings.

Defaults are starting values

defaults mirrors the field tree. Strings stay strings, booleans stay booleans, groups are objects, and lists are arrays. A default is not an instruction to overwrite existing owner edits. Valid fixture edits are preserved during generation; existing saved content has its own lifecycle.

Asset fields contain asset ID strings, not image URLs. The example deliberately omits image IDs: assets.json supplies a bundled image and binds it to hero.image.

required and minItems matter when publishing. Draft editing can remain unfinished. maxLength and maxItems also protect ordinary edits. Changing labels or arranging the editor is different from renaming IDs: an ID rename changes the content shape and may require migration.

After editing, regenerate types and validate. Unknown properties are errors; do not add imagined keys such as placeholder, help, or visibleWhen.