# 카드 프로토콜
Graph Card 컬렉션은 카드와 관계, 이미지 자산을 담는 JSON 문서입니다. 현재 프로토콜 버전은 **2**입니다.

## 먼저 하나 가져와 보기
[검증된 예제 다운로드](/downloads/collection.json) · [JSON Schema 다운로드](/downloads/collection.schema.json)

예제는 평균 → 분산 → 표준편차를 설명합니다. 관계의 실제 저장 방향은 표준편차 → 분산 → 평균이며, 각 화살표는 **이해에 필요한 선수 지식**을 뜻합니다.

## 컬렉션의 필수 필드
| 필드 | 의미 |
| --- | --- |
| protocolVersion | 숫자 2 |
| collectionId | 컬렉션의 고유 ID. 기기 가져오기에는 영문·숫자·밑줄·하이픈, 최대 128자 |
| title, description | 제목과 설명 |
| publishedAt | 시간대가 포함된 ISO 8601 일시 |
| contentVersion | 비어 있지 않은 콘텐츠 버전 문자열 |
| assets | 이미지 자산 배열. 없으면 빈 배열 |
| cards | 카드 배열 |

`viewMode`는 `flashcard`, `graph`, `both` 중 선택합니다. `tags`는 활용 유형, `topics`는 자유로운 주제, `customRelations`는 컬렉션 전용 관계 정의입니다. 언어별 내용은 `localization`에 넣습니다.

## 카드 구조
```json
{
  "cardId": "variance",
  "role": "class",
  "title": "분산",
  "description": "값들이 평균에서 얼마나 흩어져 있는지 나타냅니다.",
  "descriptionFormat": "plain",
  "images": [],
  "relations": [{ "type": "prerequisite", "targetCardId": "mean" }]
}
```

이 카드는 같은 컬렉션에 cardId가 `mean`인 카드를 필요로 합니다. 단독으로 가져올 수 있는 전체 컬렉션이 아니라 카드 구조 예시입니다.

## 역할
| role | 앱의 표현 | 쓰는 경우 |
| --- | --- | --- |
| none | 역할 없음 | 단어, 질문·답변 등 역할 구분이 필요 없는 카드 |
| class | 분류 | 개념, 범주, 종류 |
| instance | 개체 | 구체적인 대상이나 사례 |
| property | 속성 | 대상이 갖는 특징이나 값의 항목 |

role이 none인 카드는 사용자 정의 관계로 연결할 수 있습니다. 기본 관계의 역할 규칙을 피하려고 엉뚱한 역할로 바꾸지는 마세요.

## 자세히 보기
- [관계·값·방향](/ko/docs/protocol/relations/)
- [본문·이미지·다국어](/ko/docs/protocol/media/)
- [검증과 한도](/ko/docs/protocol/validation/)

이 문서의 JSON Schema와 관계 역할 표는 앱의 공유 도메인 코드에서 사이트를 빌드할 때 생성합니다. JSON Schema를 통과한 뒤에도 참조·역할·순환 같은 의미 구조 검증이 필요합니다.