사이트 계약

웹사이트의 컴포넌트, 페이지 유형, 컬렉션, 글로벌, 미디어 프로필, 디자인 토큰을 기술하는 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`	코드가 구현하는, 이름이 붙은 애니메이션 프리셋과 모션 줄이기 동작
`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"]
    }
  ]
}

리전은 편집자가 할 수 있는 일을 결정합니다. 섹션은 필수, 기본, 선택일 수 있고, 리전은 잠금 또는 순서 변경 가능으로 설정할 수 있으며, 섹션의 최소·최대 개수와 삽입 가능한 컴포넌트 목록을 가질 수 있습니다. 필드는 페이지의 항목에 바인딩할 수 있으므로, 컬렉션에서 제품이나 산업별로 페이지가 하나씩 만들어집니다.

필드 유형

유형	용도	제한
`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개의 필드를 둘 수 있습니다.