Contrat de site

Le bundle JSON qui décrit les composants, types de pages, collections, éléments globaux, profils de médias et design tokens de votre site web.

Cette page a été traduite de l'anglais. En cas de divergence, la version anglaise fait foi. Lire en anglais

Le contrat de site est l’accord entre le code de votre site web et Atlas. Il liste ce qui existe sur votre site et ce que les éditeurs peuvent modifier. Il ne contient aucun code exécutable : uniquement des descriptions et des champs typés.

Conservez-le dans votre dépôt (par exemple atlas/contract.bundle.json) et versionnez-le avec votre code.

Cycle de vie

Un développeur, ou un agent IA via MCP, valide le bundle et le propose.
Un administrateur du site l’examine et l’active (ou le rejette) dans Studio sous Site setup.
Votre site web signale l’empreinte du bundle dont il produit le rendu (POST /deployments). Studio indique si le code et le contrat sont synchronisés.

L’empreinte est un hachage SHA-256 du JSON canonique du bundle ; le bundle de votre dépôt doit donc correspondre exactement à celui que vous avez proposé.

Structure de premier niveau

Clé	Contenu
`contractVersion`	Toujours `1.0.0` pour ce format
`bundleVersion`	Votre propre version de ce bundle, par exemple `1.4.0`
`site`	`key`, `displayName`, `runtimes` (`node`, `cloudflare-workers`), `locales` (par défaut, prises en charge, de droite à gauche), `staticRoutes` dont votre code est propriétaire
`tokens`	Couleurs, styles typographiques et espacements parmi lesquels les éditeurs peuvent choisir
`motion`	Préréglages d’animation nommés que votre code implémente, avec le comportement en cas de mouvement réduit
`mediaProfiles`	Tailles, ratios et déclinaisons d’images autorisés
`components`	Jusqu’à 300 composants, chacun avec un identifiant qualifié, une version, un type et des champs
`collections`	Types de contenu répétitifs, avec champs, champs de titre et de slug, et règles d’unicité
`pageTypes`	Jusqu’à 100 types de pages : modèle de route, collection liée facultative, régions et règles SEO
`globals`	Contenu partagé tel que `site-header` et `site-footer`

Un composant (abrégé)

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

Un type de page (abrégé)

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

Les régions déterminent ce que les éditeurs peuvent faire : les sections peuvent être required, default ou optional ; les régions peuvent être verrouillées ou réordonnables, avec un nombre minimal et maximal de sections et une liste de composants insérables. Les champs peuvent être liés à l’entrée de la page, de sorte qu’une page par produit ou par secteur est créée à partir de la collection.

Types de champs

Type	Usage	Limites
`text`	Texte court sur une ligne	jusqu’à 500 caractères
`longText`	Paragraphes, sans mise en forme	jusqu’à 10 000 caractères
`richText`	Texte mis en forme, profil `basic` ou `article`	Structuré, jamais du HTML brut
`number`	Nombres avec plage facultative
`boolean`	Activé/désactivé
`select`	Un choix dans une liste fixe	jusqu’à 100 options
`date`	Une date
`link`	Route interne ou, si autorisé, URL externe
`asset`	Image(s) dans un profil de média	jusqu’à 50 par champ
`reference`	Lien vers des entrées d’une collection	jusqu’à 200 par champ
`list`	Groupe de champs répétable	jusqu’à 200 éléments, 40 champs chacun
`group`	Champs regroupés	jusqu’à 40 champs
`table`	Lignes et colonnes typées	jusqu’à 12 colonnes, 200 lignes
`token`	L’un de vos design tokens (couleur, style typographique, espacement)
`icon`	L’une des icônes d’un jeu nommé fourni par votre code	jusqu’à 200 options

Les champs peuvent être marqués required et localized. Un composant ou une collection peut avoir jusqu’à 80 champs.