Site contract

The site contract is the agreement between your website’s code and Atlas. It lists what exists on your site and what editors may change. It contains no executable code: only descriptions and typed fields.

Keep it in your repository (for example atlas/contract.bundle.json) and version it with your code.

Lifecycle

1. A developer, or an AI agent over MCP, validates the bundle and proposes it.
2. A site admin reviews and activates (or rejects) it in Studio under Site setup.
3. Your website reports the digest of the bundle it renders (POST /deployments). Studio shows whether code and contract are in sync.

The digest is a SHA-256 hash of the bundle’s canonical JSON, so the bundle in your repository must match the one you proposed exactly.

Top-level structure

Key	Contents
contractVersion	Always 1.0.0 for this format
bundleVersion	Your own version for this bundle, such as 1.4.0
site	key, displayName, runtimes (node, cloudflare-workers), locales (default, supported, right-to-left), staticRoutes your code owns
tokens	Colours, type styles and spacing editors may choose from
motion	Named animation presets your code implements, with reduced-motion behaviour
mediaProfiles	Allowed image sizes, ratios and renditions
components	Up to 300 components, each with a qualified id, version, kind and fields
collections	Repeating content types, with fields, title and slug fields, and uniqueness rules
pageTypes	Up to 100 page types: route pattern, optional bound collection, regions and SEO rules
globals	Shared content such as site-header and site-footer

A component (abbreviated)

{
  "id": "acme.home.hero",
  "version": "1.0.0",
  "kind": "section",
  "label": "Home hero",
  "fields": [
    { "key": "heading", "type": "text", "label": "Heading", "required": true, "maxLength": 80 },
    { "key": "intro", "type": "longText", "label": "Intro", "maxLength": 400 },
    { "key": "image", "type": "asset", "label": "Image", "profile": "hero" },
    { "key": "cta", "type": "link", "label": "Button" }
  ]
}

A page type (abbreviated)

{
  "key": "industry-landing",
  "version": "1.0.0",
  "label": "Industry landing",
  "route": { "pattern": "/industries/{entry.slug}" },
  "entry": { "collection": "industries", "mode": "one-page-per-entry" },
  "regions": [
    {
      "key": "hero",
      "reorder": "locked",
      "sections": [
        {
          "key": "hero",
          "component": { "id": "acme.industry.hero", "versionRange": "^1.0.0" },
          "presence": "required",
          "bind": { "headline": "entry.headline", "image": "entry.image" }
        }
      ]
    },
    {
      "key": "body",
      "reorder": "within-region",
      "min": 1,
      "max": 20,
      "insertable": ["acme.text", "acme.faq"]
    }
  ]
}

Regions decide what editors can do: sections can be required, default or optional; regions can be locked or reorderable, with a minimum and maximum number of sections and a list of insertable components. Fields can be bound to the page’s entry, so one page per product or industry is created from the collection.

Field types

Type	Use	Limits
text	Short single-line text	up to 500 characters
longText	Paragraphs, no formatting	up to 10,000 characters
richText	Formatted text, basic or article profile	Structured, never raw HTML
number	Numbers with optional range
boolean	On/off
select	One of a fixed list	up to 100 options
date	A date
link	Internal route or, if allowed, an external URL
asset	Image(s) in a media profile	up to 50 per field
reference	Link to entries of a collection	up to 200 per field
list	Repeating group of fields	up to 200 items, 40 fields each
group	Fields kept together	up to 40 fields
table	Rows and typed columns	up to 12 columns, 200 rows
token	One of your design tokens (colour, type style, spacing)
icon	One of a named icon set your code provides	up to 200 options

Fields can be marked required and localized. A component or collection can have up to 80 fields.