Site-Contract

Der Site-Contract ist die Vereinbarung zwischen dem Code Ihrer Website und Atlas. Er listet auf, was auf Ihrer Site existiert und was Redakteure ändern dürfen. Er enthält keinen ausführbaren Code: nur Beschreibungen und typisierte Felder.

Halten Sie ihn in Ihrem Repository (zum Beispiel atlas/contract.bundle.json) und versionieren Sie ihn zusammen mit Ihrem Code.

Lebenszyklus

1. Ein Entwickler oder ein KI-Agent über MCP validiert das Bundle und schlägt es vor.
2. Ein Site-Admin prüft es und aktiviert (oder lehnt) es in Studio unter Site setup ab.
3. Ihre Website meldet den Digest des Bundles, das sie rendert (POST /deployments). Studio zeigt, ob Code und Contract synchron sind.

Der Digest ist ein SHA-256-Hash des kanonischen JSON des Bundles, daher muss das Bundle in Ihrem Repository exakt mit dem übereinstimmen, das Sie vorgeschlagen haben.

Struktur der obersten Ebene

Schlüssel	Inhalt
contractVersion	Für dieses Format immer 1.0.0
bundleVersion	Ihre eigene Version für dieses Bundle, etwa 1.4.0
site	key, displayName, runtimes (node, cloudflare-workers), locales (Standard, unterstützt, Rechts-nach-links), staticRoutes, die Ihr Code besitzt
tokens	Farben, Schriftstile und Abstände, aus denen Redakteure wählen dürfen
motion	Benannte Animationsvorgaben, die Ihr Code umsetzt, mit Verhalten bei reduzierter Bewegung
mediaProfiles	Erlaubte Bildgrößen, Seitenverhältnisse und Renditions
components	Bis zu 300 Komponenten, jeweils mit qualifizierter ID, Version, Art und Feldern
collections	Wiederkehrende Inhaltstypen, mit Feldern, Titel- und Slug-Feldern und Eindeutigkeitsregeln
pageTypes	Bis zu 100 Seitentypen: Routenmuster, optionale gebundene Collection, Regionen und SEO-Regeln
globals	Geteilte Inhalte wie site-header und site-footer

Eine Komponente (gekürzt)

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

Ein Seitentyp (gekürzt)

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

Regionen legen fest, was Redakteure tun können: Abschnitte können required (erforderlich), default (Standard) oder optional sein; Regionen können gesperrt oder umsortierbar sein, mit einer Mindest- und Höchstzahl von Abschnitten und einer Liste einfügbarer Komponenten. Felder können an den Eintrag der Seite gebunden werden, sodass pro Produkt oder Branche eine Seite aus der Collection erzeugt wird.

Feldtypen

Typ	Verwendung	Limits
text	Kurzer einzeiliger Text	bis zu 500 Zeichen
longText	Absätze, ohne Formatierung	bis zu 10.000 Zeichen
richText	Formatierter Text, Profil basic oder article	Strukturiert, nie rohes HTML
number	Zahlen mit optionalem Bereich
boolean	An/Aus
select	Eine Auswahl aus einer festen Liste	bis zu 100 Optionen
date	Ein Datum
link	Interne Route oder, falls erlaubt, eine externe URL
asset	Bild(er) in einem Medienprofil	bis zu 50 pro Feld
reference	Verweis auf Einträge einer Collection	bis zu 200 pro Feld
list	Wiederholte Feldgruppe	bis zu 200 Elemente, je 40 Felder
group	Zusammengehaltene Felder	bis zu 40 Felder
table	Zeilen und typisierte Spalten	bis zu 12 Spalten, 200 Zeilen
token	Eines Ihrer Design-Tokens (Farbe, Schriftstil, Abstand)
icon	Eines aus einem benannten Icon-Set, das Ihr Code bereitstellt	bis zu 200 Optionen

Felder können als required und localized markiert werden. Eine Komponente oder Collection kann bis zu 80 Felder haben.