Croct 콘텐츠 모델링은(는) 무엇을 하나요?

컴포넌트와 슬롯을 설계하고, 스키마를 작성하며, 모델이 진화해도 유효성을 유지하는 콘텐츠 정의를 채웁니다. 스키마로 표현할 수 있는 모든 것은 대시보드 시각적 에디터에도 존재합니다. JSON은 동일한 모델을 수동으로 작성한 것입니다.

개념 모델

개념	설명	범위
컴포넌트	이름이 있는 재사용 가능한 스키마. `structure`와 `union`만 컴포넌트(최상위 스키마)가 될 수 있습니다.	슬롯 및 다른 컴포넌트에서 재사용 가능
정규 컴포넌트	고정된 속성 집합을 가진 `structure`입니다.
유니온 컴포넌트	최대 10개의 정규 컴포넌트로 구성된 `union`입니다. 에디터가 콘텐츠별로 하나의 변형을 선택합니다.
슬롯	하나의 컴포넌트에 연결된 앱 내 자리 표시자(히어로, 공지 표시줄)입니다. 로케일별 기본 콘텐츠를 보유합니다.	컨텍스트에 종속됨. 하나의 컴포넌트가 여러 슬롯을 지원할 수 있음
콘텐츠 정의	스키마의 실제 값을 담고 있는 JSON으로, 정적 값 또는 동적(CQL) 값을 가집니다.

콘텐츠 레이어(아래에서 위): 슬롯 기본 콘텐츠(경험이나 실험이 일치하지 않을 때, 봇 필터링에 제외된 봇, 정적 렌더링, 오류 발생 시 표시됨) → 경험 콘텐츠(대상별) → 실험 콘텐츠(변형별, 최소 2개 변형) → 콘텐츠 그룹(경험이나 실험 변형 내 하위 세그먼트를 위한 추가 변형)입니다. 폴백 콘텐츠는 앱의 소스 코드에 있으며, 가져오기 실패 또는 서비스 중단 시 렌더링됩니다. CLI가 슬롯 기본 콘텐츠를 폴백으로 다운로드합니다.

형태 결정하기

필요한 경우...	사용
하나의 고정된 레이아웃(모든 곳에서 동일한 필드)	정규 컴포넌트 (`structure`)
에디터가 선택하는 변형(텍스트 배너 vs 이미지 배너 vs 양식 배너)	정규 컴포넌트를 참조하는 유니온 컴포넌트
여러 곳에서 일관성 유지(모든 곳에서 사용되는 CTA 버튼)	`{"type": "reference", "id": "..."}`로 포함된 별도의 컴포넌트
한 곳에서의 유연성(제목 + 이미지 쌍)	새 컴포넌트가 아닌 중첩된 `structure` 속성 또는 원시 타입
여러 독립적인 섹션이 있는 페이지	하나의 거대한 컴포넌트가 아닌 섹션별로 하나의 컴포넌트와 하나의 슬롯
미리 정의된 옵션 집합	`choices`가 있는 `text` (열거형)
이미지, 비디오, 오디오 또는 문서 업로드	`@croct/file`에 대한 `reference` (파일은 5MB로 제한됨. 긴 비디오는 대신 `url` 텍스트 속성 고려)
툴바 에디터에서 편집된 서식 있는 텍스트	`@croct/richText`에 대한 `reference`
일반 텍스트 필드의 간단한 서식	`text` + 앱 내 마크다운 파서 (아래 마크다운 참조)
다른 값을 계산하는 데만 사용되는 값(예: 동적 변수)	`"private": true` 속성

문서의 경험 법칙: "유연성 또는 일관성이 필요한가?"를 묻습니다. 유연성 → 구조 속성. 일관성 → 새 컴포넌트.

워크플로우

페이지의 섹션을 나열합니다. 독립적으로 배치되는 각 섹션은 슬롯이 됩니다.
각 슬롯에 대해 정규 컴포넌트 또는 유니온 컴포넌트를 선택합니다. 구조가 일관되게 유지되어야 하는 경우 기존 컴포넌트를 재사용합니다.
스키마를 작성합니다: type, label, description, position, optional 속성을 사용합니다. 실제 UI 제약 조건에서 검증(maximumLength, minimum, pattern, allowedTypes, 목록의 maximumLength)을 추가합니다.
중첩을 추가하기 전에 한계(아래)를 확인합니다. 복잡도 점수를 계산합니다.
각 슬롯과 지원되는 각 로케일에 대한 기본 콘텐츠 정의를 작성합니다.
컴포넌트가 이미 사용 중인 경우, 변경 사항이 호환성을 깨뜨리면 새 버전을 예상합니다. 영향을 받는 콘텐츠를 업데이트한 후 앱에서 슬롯 버전을 올립니다(버전 관리 참조).

스키마 기본 구조

정규 컴포넌트는 structure입니다. 각 속성은 type으로 스키마를 감쌉니다:

{
  "type": "structure",
  "title": "CTA Button",
  "description": "페이지로 연결되는 클릭 유도 버튼입니다.",
  "attributes": {
    "label": {
      "label": "레이블",
      "description": "버튼에 표시되는 텍스트입니다.",
      "position": 0,
      "type": {
        "type": "text"
      }
    },
    "link": {
      "label": "링크",
      "description": "연결할 페이지의 URL입니다.",
      "position": 1,
      "type": {
        "type": "text"
      }
    }
  }
}

유니온 컴포넌트는 컴포넌트 ID를 참조에 매핑합니다. 키는 참조된 ID와 동일해야 합니다:

{
  "type": "union",
  "types": {
    "text-hero": {"type": "reference", "id": "text-hero"},
    "image-hero": {"type": "reference", "id": "image-hero"}
  }
}

앱에서 유니온 슬롯 콘텐츠는 판별 유니온(discriminated union)입니다. 각 변형에는 컴포넌트 ID(text-hero 또는 image-hero)로 설정된 _type 속성이 있습니다. _type으로 분기하여 렌더링합니다. croct-integrate-sdk 스킬을 참조하세요.

속성 유형 요약

대시보드 유형	스키마 JSON
텍스트	`{"type": "text"}` (+ `minimumLength`, `maximumLength`, `pattern`)
여러 줄 텍스트	`{"type": "text", "format": "multiline"}`
URL	`{"type": "text", "format": "url"}`
색상	`{"type": "text", "format": "color"}`
날짜/시간	`{"type": "text", "format": "instant"}` (`local-date`, `local-time`, `local-date-time`, `zoned-date-time`도 가능)
열거형	`{"type": "text", "choices": {"left": {"label": "왼쪽"}}}`
서식 있는 텍스트	`{"type": "reference", "id": "@croct/richText", "properties": {}}`
파일	`{"type": "reference", "id": "@croct/file", "properties": {}}`
숫자	`{"type": "number"}` (+ `integer`, `minimum`, `maximum`)
불리언	`{"type": "boolean"}` (+ `label.true`, `label.false`, `default`)
목록	`{"type": "list", "items": {...}}` (+ `itemLabel`, `minimumLength`, `maximumLength`)
구조체	`{"type": "structure", "attributes": {...}}`
컴포넌트	`{"type": "reference", "id": "<component-id>"}`

format과 choices는 type을 제외한 다른 텍스트 속성과 함께 사용할 수 없습니다. 전체 속성 목록, 기본값 및 한계: references/schema.md.

스키마 한계

한계	값
구조체당 속성 수	30
중첩 깊이	6레벨
유니온 내 컴포넌트 수	10
스키마 복잡도 점수	50
목록 항목 (스키마 기본 `maximumLength`)	30
텍스트 `maximumLength`	300 (한 줄); 1000 (여러 줄 및 URL) (암시적 제한: 일반 `text`는 `format`과 `maximumLength`를 결합할 수 없음. 서식 있는 텍스트는 가능)
텍스트 `choices`	20
파일 크기	5MB (5242880 바이트)
레이블 / 설명	60 / 160자

복잡도 점수: 구조체 = 1 + 속성 수; 목록 = 1 + 항목 유형; 원시 타입 = 1; 유니온 = 가장 복잡한 멤버; 참조 = 참조된 컴포넌트. 제목, 이미지, 가격이 있는 제품 목록은 5점입니다.

콘텐츠 정의 기본 구조

모든 값은 {"type": "<콘텐츠 유형>", "value": {"type": "static" | "dynamic", ...}}입니다. 구조체는 attributes를 중첩하고; 목록은 items를 보유하며; 유니온 콘텐츠는 name이 유니온 키로 설정된 구조체입니다.

{
  "type": "structure",
  "attributes": {
    "message": {
      "type": "text",
      "value": {"type": "static", "value": "환영합니다, {{variable}}!"}
    },
    "variable": {
      "type": "text",
      "value": {
        "type": "dynamic",
        "expression": "user's name",
        "nullable": true,
        "default": "guest"
      }
    }
  }
}

expression은 CQL입니다(croct-cql 스킬 참조). default는 평가 실패 시, null 반환 시, 또는 호환되지 않는 유형 반환 시 사용됩니다.
nullable은 스키마의 optional 플래그와 일치해야 합니다.
variable과 같은 도우미 속성은 스키마에서 "private": true로 표시하여 앱에 전달되는 콘텐츠에서 제외합니다.
콘텐츠 한계: 최대 30개 목록 항목, 최대 10개 동적 값, 복잡도 점수 50.
동적 값은 Scale 플랜 기능입니다. 로컬라이제이션은 애드온입니다.

플레이스홀더, 상대 경로, 폴백 및 모든 콘텐츠 유형: references/definition.md.

로컬라이제이션

로케일은 워크스페이스별로 구성됩니다. 로컬라이제이션은 애드온입니다.
각 슬롯에 지원되는 각 로케일별 기본 콘텐츠를 제공합니다. 기본 콘텐츠가 없는 로케일은 기본 로케일의 콘텐츠를 사용합니다. 경험과 실험도 로케일별로 콘텐츠를 보유합니다. 로케일에 대한 콘텐츠가 없는 경험은 슬롯의 기본 콘텐츠를 제공합니다.
요청된 로케일이 없는 경우의 폴백: SDK 문서는 워크스페이스의 기본 로케일을 말합니다. Content API 문서는 슬롯의 기본 로케일을 말합니다. 문서가 서로 다르므로 하나를 선택하기보다는 그렇게 말하십시오.
코드에서 로케일 요청은 preferredLocale(가져오기별) 또는 defaultPreferredLocale(앱 전체), 또는 Next.js/Hydrogen의 localeResolver를 사용합니다. croct-integrate-sdk 스킬을 참조하세요.
croct.json은 defaultLocale과 locales를 보유합니다. croct install은 슬롯, 버전 및 로케일별로 폴백 콘텐츠를 다운로드합니다. croct-use-cli 스킬을 참조하세요.

버전 관리 및 호환성을 깨뜨리는 변경

컴포넌트 스키마를 변경합니다(예: 속성 추가 또는 기존 속성 변경).
변경 사항이 앱을 손상시킬 수 있는 방식으로 콘텐츠 구조에 영향을 미치는 경우 Croct는 새 버전을 생성하고 앱에 이전 버전을 계속 제공합니다.
영향을 받는 모든 슬롯과 경험의 콘텐츠를 업데이트합니다(대시보드가 표시합니다).
앱 코드에서 슬롯 버전을 올립니다(예: fetchContent('home-hero@2')).

해야 할 일:

앱 코드에서 슬롯 버전을 고정합니다(home-hero@1). 버전이 없는 ID는 최신 버전을 사용하므로 호환성을 깨뜨리는 변경이 즉시 적용되어 앱을 손상시킬 수 있습니다.
슬롯 기본 콘텐츠뿐만 아니라 경험 및 실험 콘텐츠도 업데이트합니다.
변경 후 폴백 콘텐츠를 동기화 상태로 유지합니다(croct-use-cli 스킬에서 동기화를 다룹니다).

하지 말아야 할 일:

어떤 편집이 호환성을 깨뜨리는지 추측하지 마십시오. 문서에 나열되어 있지 않습니다. 대시보드의 슬롯 영향 알림에 의존하십시오.

리팩토링

상황	기법
변경 사항이 대부분의 사용에는 적용되지만 일부에는 적용되지 않아야 함	복제 후 수정: 컴포넌트를 복제하고, 몇 가지 예외를 복사본으로 지정한 다음 원본을 변경합니다
변경 사항이 소수의 사용에만 적용되어야 함	복제 후 교체: 컴포넌트를 복제하고, 복사본을 변경한 다음 해당 사용을 복사본으로 지정합니다
컴포넌트가 최대 중첩 수준에 도달함	평탄화 후 병합: 중첩된 구조체의 속성을 부모로 병합한 다음 사용되는 모든 곳에서 콘텐츠를 업데이트합니다
컴포넌트가 복잡도 한계에 근접함	별도의 슬롯으로 렌더링되는 더 작은 컴포넌트로 분할합니다
구조체가 30개 속성 한계에 도달함	지침(문서에 이에 대한 가이드는 없음): 관련 속성을 중첩된 구조체로 그룹화하되 6레벨 중첩을 유지하거나, 별도의 컴포넌트와 슬롯으로 분할합니다. 고정된 슬롯 버전(`home-hero@1`)은 마이그레이션하는 동안 라이브 앱을 이전 스키마로 유지합니다

세부 사항, 단계 및 모범 사례: references/design-and-refactoring.md.

텍스트 속성의 마크다운

서식 있는 텍스트(@croct/richText)는 툴바 에디터에서 생성된 마크다운을 저장합니다. allowedFormatting으로 제한할 수 있습니다.
일반 text 속성은 원시 문자열을 저장합니다. 거기서 마크다운을 지원하려면 앱에서 구문 분석합니다(예: @croct/md-lite 사용: 굵게, 기울임꼴, 취소선, 코드, 링크, 이미지, 문단).
간단한 서식으로 유지하십시오. CTA 레이블, URL 및 제품 데이터는 별도의 속성으로 모델링하십시오.
지원되는 구문을 속성 description에 명시하십시오(예: "bold, italic, links에 대한 마크다운 구문을 지원합니다.").

렌더링 코드: references/design-and-refactoring.md.

함정

단일 제목이나 이미지에 대한 컴포넌트 생성. 원시 타입 또는 구조체를 사용하십시오.
일반적인 이름("제품 카드"). 목적에 맞는 이름("제품 기능 목록")을 선호하십시오.
유니온 types 키가 참조된 컴포넌트 ID와 다른 경우: 스키마가 유효하지 않습니다.
"default": true인 choices 항목이 두 개 이상 있는 경우: 스키마가 유효하지 않습니다.
초가 없는 날짜/시간 값: 10:15는 유효하지 않으며, 10:15:00은 유효합니다.
nullable이 스키마 optional 플래그와 일치하지 않는 동적 값.
경험의 슬롯 버전이 앱의 버전과 다를 때 미리보기가 오래된 콘텐츠를 표시합니다.

실시간 문서

색인: https://docs.croct.com/llms.txt
모든 페이지를 마크다운으로: https://docs.croct.com/reference/content/schema/introduction.md
검색: https://docs.croct.com/api/search.md?term=<terms>

Croct 콘텐츠 모델링