Contratto del sito

Il contratto del sito è l’accordo tra il codice del Suo sito web e Atlas. Elenca ciò che esiste sul Suo sito e ciò che i redattori possono modificare. Non contiene alcun codice eseguibile: solo descrizioni e campi tipizzati.

Lo conservi nel Suo repository (per esempio atlas/contract.bundle.json) e lo versioni insieme al Suo codice.

Ciclo di vita

1. Uno sviluppatore, o un agente IA tramite MCP, convalida il bundle e lo propone.
2. Un amministratore del sito lo esamina e lo attiva (o lo rifiuta) in Studio sotto Site setup.
3. Il Suo sito web segnala il digest del bundle che rende (POST /deployments). Studio mostra se codice e contratto sono allineati (in sync).

Il digest è un hash SHA-256 del JSON canonico del bundle, quindi il bundle nel Suo repository deve corrispondere esattamente a quello che ha proposto.

Struttura di primo livello

Chiave	Contenuto
contractVersion	Sempre 1.0.0 per questo formato
bundleVersion	La Sua versione di questo bundle, come 1.4.0
site	key, displayName, runtimes (node, cloudflare-workers), locales (predefinita, supportate, da destra a sinistra), staticRoutes gestiti dal Suo codice
tokens	Colori, stili tipografici e spaziatura tra cui i redattori possono scegliere
motion	Preset di animazione con nome implementati dal Suo codice, con il comportamento a movimento ridotto
mediaProfiles	Dimensioni, proporzioni e versioni delle immagini consentite
components	Fino a 300 componenti, ciascuno con id qualificato, versione, tipo e campi
collections	Tipi di contenuto ripetuti, con campi, campi titolo e slug e regole di unicità
pageTypes	Fino a 100 tipi di pagina: schema del percorso, raccolta associata opzionale, regioni e regole SEO
globals	Contenuti condivisi come site-header e site-footer

Un componente (abbreviato)

{
  "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 tipo di pagina (abbreviato)

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

Le regioni stabiliscono che cosa possono fare i redattori: le sezioni possono essere required (obbligatorie), default (predefinite) od optional (facoltative); le regioni possono essere bloccate o riordinabili, con un numero minimo e massimo di sezioni e un elenco di componenti inseribili. I campi possono essere associati (bound) alla voce della pagina, così da creare una pagina per ogni prodotto o settore a partire dalla raccolta.

Tipi di campo

Tipo	Uso	Limiti
text	Testo breve su una sola riga	fino a 500 caratteri
longText	Paragrafi, senza formattazione	fino a 10.000 caratteri
richText	Testo formattato, profilo basic o article	Strutturato, mai HTML grezzo
number	Numeri con intervallo opzionale
boolean	Attivo/disattivo
select	Una voce di un elenco fisso	fino a 100 opzioni
date	Una data
link	Percorso interno oppure, se consentito, un URL esterno
asset	Immagine/i in un profilo media	fino a 50 per campo
reference	Collegamento a voci di una raccolta	fino a 200 per campo
list	Gruppo ripetuto di campi	fino a 200 elementi, 40 campi ciascuno
group	Campi raggruppati	fino a 40 campi
table	Righe e colonne tipizzate	fino a 12 colonne, 200 righe
token	Uno dei Suoi design token (colore, stile tipografico, spaziatura)
icon	Un’icona di un set con nome fornito dal Suo codice	fino a 200 opzioni

I campi possono essere contrassegnati come required e localized. Un componente o una raccolta può avere fino a 80 campi.