시스템 속성 (sys)
최종 수정: 2026년 7월 3일
WEEGLOO의 모든 리소스 응답은 두 갈래로 나뉩니다. fields처럼 그 리소스의 본문 데이터가 한쪽이고, 시스템이 관리하는 메타데이터가 다른 한쪽입니다. 이 메타데이터는 모두 sys 객체에 담깁니다.
sys에는 리소스의 식별자(id), 종류(type), 생성·수정 시각, 버전, 다른 리소스와의 관계가 들어갑니다. 이 페이지는 모든 리소스가 공통으로 갖는 sys의 구조와 리소스 종류별 차이를 한곳에 정리합니다. 개별 리소스 레퍼런스는 그 리소스 고유의 sys 키만 따로 설명하고, 공통 부분은 이 페이지를 참조합니다.
공통 필드
거의 모든 리소스의 sys는 다음 필드를 가집니다. createdBy·updatedBy와 space는 다른 리소스를 가리키는 Refer 모양({ "sys": { "id", "type": "Refer", "targetType" } })으로 들어갑니다. 자세한 모양은 아래 Refer 모양에서 다룹니다.
| 속성 | 타입 | 설명 |
|---|---|---|
id | string | 리소스 고유 식별자. 단일 조회·수정·삭제 경로의 {...Id} 자리에 들어갑니다. |
type | string | 리소스 종류. 그 리소스의 종류 이름이 값입니다(예: "Content"·"Media"·"Tag"). |
createdBy | Refer<User> | 만든 사용자. |
updatedBy | Refer<User> | 마지막으로 수정한 사용자. |
createdAt | string (date-time) | 생성 시각. |
updatedAt | string (date-time) | 마지막 수정 시각. |
version | integer (≥1) | 현재 버전. 리소스를 수정할 때마다 1씩 올라갑니다. |
space | Refer<Space> | 이 리소스가 속한 Space. Space 하위 리소스만 가집니다. |
version은 동시 수정 충돌을 막는 데도 쓰입니다. 수정·발행 같은 변경 계열 요청에는 현재 version 값을 X-Weegloo-Version 헤더에 실어 보내야 합니다. 자세한 규칙은 규약을 참조하세요.
Organization은 Space 하위가 아니므로 space를 갖지 않습니다. 대신 소속 요금제를 가리키는 plan(Refer<Plan>)과 공식 여부 isOfficial(boolean)을 가집니다. Space는 상위 Organization을 가리키는 organization(Refer<Organization>)과 plan을 가집니다.
Refer 모양
sys 안에서 다른 리소스를 가리키는 참조는 언제나 같은 모양을 씁니다. type이 "Refer"로 고정되고, targetType이 가리키는 리소스의 종류를 알려 줍니다.
{
"sys": {
"id": "HnQ32YiH",
"type": "Refer",
"targetType": "Space"
}
}targetType에는 가리키는 리소스의 종류 이름이 들어갑니다. 예를 들어 space는 targetType이 "Space"이고, createdBy·updatedBy는 "User", Content의 contentType은 "ContentType"입니다. 즉 Refer<User>·Refer<Space>로 적는 타입은 모두 이 모양이며, targetType만 달라집니다.
리소스 종류별 차이
공통 필드 위에 리소스 종류에 따라 추가 속성이 붙습니다. 크게 세 갈래로 나뉩니다.
발행 라이프사이클 리소스 (Content·Media)
Content와 Media는 작성·발행·보관이라는 라이프사이클을 가집니다. 그래서 sys에 발행 상태를 나타내는 속성이 더해집니다.
| 속성 | 타입 | 설명 |
|---|---|---|
status | string (enum) | 발행 상태. Draft·Changed·Published·Archived 중 하나. |
publish | object | 발행 상태 포인터. 아래 키 참조. |
archive | object | 보관 정보. 보관 중일 때만 존재하며, 아니면 키가 없습니다. |
status는 다음 4가지 중 하나입니다.
status | 의미 |
|---|---|
Draft | 작성 중이며 아직 발행되지 않은 상태. |
Changed | 발행된 적이 있으나 그 뒤 수정되어 아직 발행되지 않은 변경분이 있는 상태. |
Published | 발행되어 있고 미발행 변경분이 없는 상태. |
Archived | 보관된 상태. |
publish 객체는 발행 상태를 가리키는 포인터입니다. 발행 중일 때는 다음 키를 모두 가집니다.
| 키 | 타입 | 설명 |
|---|---|---|
version | integer | 발행된 시점의 sys.version. |
at | string (date-time) | 마지막 발행 시각. |
firstAt | string (date-time) | 최초 발행 시각. 발행취소해도 보존됩니다. |
counter | integer | 누적 발행 횟수. |
by | Refer<User> | 마지막으로 발행한 사용자. |
발행취소하면 publish에서 version·at·by가 빠지고 firstAt·counter만 남습니다. 한 번도 발행한 적이 없으면 publish는 { "counter": 0 }입니다.
archive 객체는 보관 중일 때만 존재하며, 보관 시점의 version·보관 시각 at·보관한 사용자 by를 가집니다. 보관 상태가 아니면 archive 키 자체가 없습니다.
여기서 sys.version은 작업 중 버전(생성·수정·발행 등 모든 변경마다 오름)이고, publish.version은 마지막으로 발행된 버전입니다. 둘은 다를 수 있습니다.
다음은 발행 중인 Content의 sys 예시입니다.
{
"id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
"type": "Content",
"space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
"contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
"publish": {
"version": 1,
"at": "2026-06-18T09:51:44.128Z",
"firstAt": "2026-06-18T09:51:44.128Z",
"counter": 1,
"by": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }
},
"createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
"createdAt": "2026-06-18T09:51:14.597Z",
"updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
"updatedAt": "2026-06-18T09:51:44.128Z",
"version": 2,
"status": "Published"
}발행 라이프사이클의 상태 전환 순서와 각 단계의 응답은 Content와 Media에서 다룹니다.
설정 리소스 (Tag·Locale·Organization·Space 등)
Tag·Locale·Organization·Space·SpaceRole·ServiceUserRole·Webhook·ServiceLogin 같은 리소스는 발행 개념이 없습니다. 만들면 곧바로 적용되고, 발행해서 전달 경로에 올리는 단계가 없습니다.
따라서 이들의 sys에는 status·publish·archive가 없고, 공통 필드와 함께 version만 가집니다. version은 수정할 때마다 1씩 올라가며, 변경 요청 시 X-Weegloo-Version 헤더에 싣습니다.
SpaceRole은 여기에 더해 isLocked(boolean)를 가집니다. true면 WEEGLOO가 기본으로 제공하는 역할이라는 뜻입니다.
특수 리소스 (ServiceUser·WebHosting)
일부 리소스는 위 두 갈래에 들어맞지 않는 sys를 가집니다.
ServiceUser는 제품의 회원 가입으로 생기는 리소스입니다. 사람이 콘텐츠 스튜디오에서 만들고 고치는 리소스가 아니므로, sys에 createdBy·updatedBy·version이 없습니다. 대신 로그인 수단 provider(string)와 email(string)을 가집니다. version이 없으므로 ServiceUser를 수정할 때는 X-Weegloo-Version 헤더가 필요 없습니다.
WebHosting은 배포물을 호스팅하는 리소스입니다. 공통 필드와 version을 가지며, 여기에 배포 처리 상태 state(enum)가 더해집니다. 이것은 발행 상태가 아니라 업로드한 배포물을 처리하는 진행 상태입니다.
state | 의미 |
|---|---|
PENDING | 처리 대기 중. |
PROCESSING | 처리 중. |
COMPLETED | 처리 완료. |
FAILED | 처리 실패. |
CMA와 CDA의 차이: version vs revision
같은 Content·Media라도 어느 API에서 받는지에 따라 sys의 모양이 다릅니다.
CMA(관리)에서 받는 Content·Media는 작업 중인 리소스입니다. 그래서 version·status·publish(와 보관 중이면 archive)를 모두 담아, 현재 작업 상태와 발행 상태를 함께 알려 줍니다.
CDA(전달)는 발행된 스냅샷만 전달합니다. 작업 중 상태라는 개념이 없으므로 sys에 version·status·publish·archive를 담지 않습니다. 대신 발행된 스냅샷의 번호를 가리키는 revision(integer) 하나를 씁니다. revision은 발행할 때마다 그 시점의 버전이 담깁니다.
{
"id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
"type": "Content",
"space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
"contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
"createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
"createdAt": "2026-06-18T09:51:14.597Z",
"updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
"updatedAt": "2026-06-18T09:51:44.128Z",
"revision": 3
}발행 전달 모델(발행된 것만 전달됨·발행 스냅샷·revision)은 CDA 개요에서 자세히 다룹니다.
관련 문서
- 공통 쿼리 파라미터: 목록 조회·페이지네이션.
- 규약: 미디어 타입·JSON Patch·동시성(
X-Weegloo-Version). - 에러: 오류 응답 형식과 공통 코드.
- CDA 개요: 발행 스냅샷(
revision) 전달 모델.