Контракт сайта

JSON-пакет, описывающий компоненты, типы страниц, коллекции, глобальные блоки, медиапрофили и дизайн-токены вашего сайта.

Эта страница переведена с английского. При любых расхождениях действует английская версия. Читать на английском

Контракт сайта — это соглашение между кодом вашего сайта и Atlas. В нём перечислено, что есть на вашем сайте и что могут менять редакторы. Он не содержит исполняемого кода: только описания и типизированные поля.

Храните его в своём репозитории (например, atlas/contract.bundle.json) и ведите его версии вместе с кодом.

Жизненный цикл

Разработчик или ИИ-агент через MCP проверяет пакет и предлагает его.
Администратор сайта просматривает и активирует (или отклоняет) его в Studio в разделе Site setup.
Ваш сайт сообщает дайджест пакета, который он отображает (POST /deployments). Studio показывает, синхронизированы ли код и контракт.

Дайджест — это хеш SHA-256 канонического JSON пакета, поэтому пакет в вашем репозитории должен в точности совпадать с тем, который вы предложили.

Структура верхнего уровня

Ключ	Содержимое
`contractVersion`	Для этого формата всегда `1.0.0`
`bundleVersion`	Ваша собственная версия этого пакета, например `1.4.0`
`site`	`key`, `displayName`, `runtimes` (`node`, `cloudflare-workers`), `locales` (по умолчанию, поддерживаемые, справа налево), `staticRoutes`, за которые отвечает ваш код
`tokens`	Цвета, стили шрифтов и отступы, из которых могут выбирать редакторы
`motion`	Именованные пресеты анимации, которые реализует ваш код, с поведением при пониженной анимации (reduced motion)
`mediaProfiles`	Допустимые размеры, пропорции и варианты изображений
`components`	До 300 компонентов, у каждого — полный идентификатор, версия, вид и поля
`collections`	Типы повторяющегося контента с полями, полями заголовка и слага и правилами уникальности
`pageTypes`	До 100 типов страниц: шаблон маршрута, необязательная привязанная коллекция, регионы и SEO-правила
`globals`	Общий контент, такой как `site-header` и `site-footer`

Компонент (сокращённо)

{
  "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" }
  ]
}

Тип страницы (сокращённо)

{
  "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"]
    }
  ]
}

Регионы определяют, что могут делать редакторы: секции могут быть обязательными (required), по умолчанию (default) или необязательными (optional); регионы могут быть заблокированными или допускать изменение порядка, с минимальным и максимальным числом секций и списком компонентов, которые можно вставлять. Поля можно привязывать к записи страницы, тогда по странице на каждый товар или отрасль создаётся из коллекции.

Типы полей

Тип	Назначение	Ограничения
`text`	Короткий однострочный текст	до 500 символов
`longText`	Абзацы без форматирования	до 10 000 символов
`richText`	Форматированный текст, профиль `basic` или `article`	Структурированный, никогда не сырой HTML
`number`	Числа с необязательным диапазоном
`boolean`	Вкл/выкл
`select`	Один вариант из фиксированного списка	до 100 вариантов
`date`	Дата
`link`	Внутренний маршрут или, если разрешено, внешний URL
`asset`	Изображение(я) в медиапрофиле	до 50 на поле
`reference`	Ссылка на записи коллекции	до 200 на поле
`list`	Повторяющаяся группа полей	до 200 элементов, по 40 полей в каждом
`group`	Поля, объединённые вместе	до 40 полей
`table`	Строки и типизированные столбцы	до 12 столбцов, 200 строк
`token`	Один из ваших дизайн-токенов (цвет, стиль шрифта, отступ)
`icon`	Один значок из именованного набора, который предоставляет ваш код	до 200 вариантов

Поля можно помечать как required и localized. В компоненте или коллекции может быть до 80 полей.