サイトコントラクト

ウェブサイトのコンポーネント、ページタイプ、コレクション、グローバル、メディアプロファイル、デザイントークンを記述する JSON バンドルです。

このページは英語から翻訳されたものです。内容に相違がある場合は、英語版が優先されます。英語版を読む

サイトコントラクトは、ウェブサイトのコードと Atlas の間の取り決めです。サイトに何が存在し、編集者が何を変更できるかを一覧にします。実行可能なコードは含まれず、記述と型付きフィールドだけで構成されます。

リポジトリ（たとえば atlas/contract.bundle.json）に保管し、コードと一緒にバージョン管理してください。

ライフサイクル

開発者、または MCP 経由の AI エージェントが、バンドルを検証して提案します。
サイト管理者が Studio の Site setup で、それを確認して有効化（または却下）します。
ウェブサイトが、表示に使うバンドルのダイジェストを報告します（POST /deployments）。Studio は、コードとコントラクトが同期しているかを表示します。

ダイジェストはバンドルの正規化された JSON の SHA-256 ハッシュであるため、リポジトリ内のバンドルは、提案したものと完全に一致していなければなりません。

トップレベルの構造

キー	内容
`contractVersion`	この形式では常に `1.0.0`
`bundleVersion`	このバンドル用のお客様独自のバージョン（例: `1.4.0`）
`site`	`key`、`displayName`、`runtimes`（`node`、`cloudflare-workers`）、`locales`（デフォルト、対応、右から左）、コードが管理する `staticRoutes`
`tokens`	編集者が選べる色、文字スタイル、余白
`motion`	コードが実装する、名前付きのアニメーションプリセット（動きを抑える設定（reduced-motion）時の動作を含む）
`mediaProfiles`	許可される画像サイズ、比率、レンディション
`components`	最大 300 件のコンポーネント。それぞれ修飾付き ID、バージョン、種別、フィールドを持つ
`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"]
    }
  ]
}

リージョンが、編集者にできることを決めます。セクションは必須、デフォルト、任意にでき、リージョンは固定にも並べ替え可能にもできます。セクション数の最小値と最大値、挿入可能なコンポーネントの一覧も指定します。フィールドはページのエントリーに紐づけることができ、コレクションから商品や業種ごとに 1 ページずつ作成されます。

フィールドタイプ

タイプ	用途	制限
`text`	短い 1 行のテキスト	500 文字まで
`longText`	段落、書式なし	10,000 文字まで
`richText`	書式付きテキスト、`basic` または `article` プロファイル	構造化されたもので、生の HTML は不可
`number`	範囲を任意で指定できる数値
`boolean`	オン／オフ
`select`	固定リストの中から 1 つ	100 個の選択肢まで
`date`	日付
`link`	内部ルート、または許可されている場合は外部 URL
`asset`	メディアプロファイル内の画像	1 フィールドあたり 50 個まで
`reference`	コレクションのエントリーへのリンク	1 フィールドあたり 200 個まで
`list`	フィールドの繰り返しグループ	200 項目まで、各 40 フィールドまで
`group`	まとめて保持するフィールド	40 フィールドまで
`table`	行と型付きの列	12 列、200 行まで
`token`	デザイントークンの 1 つ（色、文字スタイル、余白）
`icon`	コードが提供する名前付きアイコンセットの 1 つ	200 個の選択肢まで

フィールドには required と localized を指定できます。1 つのコンポーネントまたはコレクションは、最大 80 フィールドまで持てます。