데이터 필드 표준

dataware의 모든 데이터는 schema.org 국제 표준을 기반으로 정규화되어 있습니다. 별도의 필드 매핑 없이 바로 사용할 수 있는 데이터를 제공합니다.

필드 체계

dataware API가 반환하는 데이터 필드는 세 가지 계층으로 구분됩니다.

API 응답의 meta.schemaVersion 필드에서 현재 스키마 버전을 확인할 수 있습니다.

---

Tier 1: 공통 필드

모든 데이터셋의 아이템에 포함되는 기본 필드입니다.

식별/분류

연락처

위치/주소

운영

---

Tier 2: 준공통 필드

여러 데이터셋에서 공통으로 사용되는 필드입니다. API 응답의 extraAttributes 안에 포함됩니다.

infoSections 구조

[
  { "title": "대표메뉴", "content": "돼지갈비" },
  { "title": "이용안내", "content": "11:00-21:00, 매주 월요일 휴무" }
]

---

Tier 3: 도메인 특화 필드

특정 데이터셋 유형에서만 사용되는 필드입니다. 데이터셋마다 어떤 Tier 3 키를 사용하는지는 데이터셋 정보에서 확인할 수 있습니다.

숙박 (LodgingBusiness)

음식점 (FoodEstablishment)

축제/행사 (Event)

상품 (Product)

지역 농수산품, 특산품 등 판매 가능한 상품 데이터입니다.

productOptions 구조:

[
  { "name": "1kg", "additionalPrice": 0 },
  { "name": "3kg", "additionalPrice": 25000 },
  { "name": "선물세트 5kg", "additionalPrice": 50000, "description": "고급 포장" }
]

체험상품 (Experience)

농촌체험, 공방체험 등 예약 기반 체험 상품 데이터입니다.

pricingTiers 구조:

[
  { "type": "adult", "label": "성인", "price": 10000 },
  { "type": "youth", "label": "청소년", "price": 8000 },
  { "type": "child", "label": "소아", "price": 3000 }
]

캠핑/글램핑 (Campground)

---

상품/체험 데이터 활용 가이드

dataware API는 상품/체험의 카탈로그(레퍼런스) 데이터를 제공합니다. 실시간 재고, 예약 상태, 결제 처리 등 트랜잭션 데이터는 API 소비자 서비스에서 관리합니다.

dataware가 제공하는 것

dataware가 제공하지 않는 것

연동 패턴

상품 연동 시:

• basePrice와 productOptions는 레퍼런스 가격입니다. 소비자 서비스는 이를 기반으로 실제 판매가를 설정할 수 있습니다.
• 상품 옵션 구조가 변경될 수 있으므로, 주기적으로 API를 조회하여 동기화하는 것을 권장합니다.

체험상품 연동 시:

• pricingTiers는 가격 유형(성인/청소년/소아)과 기준 단가를 정의합니다. 소비자 서비스는 이를 기반으로 실제 판매가를 설정합니다.
• operatingTimeSlots과 capacityPerSlot은 기본 운영 패턴입니다. 소비자 서비스는 이를 참고하여 특정 날짜에 예약 가능한 슬롯을 생성합니다.
• 잔여 인원 관리, 예약 차감, 매진 처리는 소비자 서비스에서 구현합니다.

레이어 분리

소비자 서비스는 dataware item의 id를 외래키로 참조하여 자체 상품/재고 테이블과 연결하는 것을 권장합니다.

---

하위호환 정책

dataware API는 Immutable Key Rule을 따릅니다.

• 한번 발행된 필드 키는 이름이 변경되거나 삭제되지 않습니다.
• 새로운 필드는 추가될 수 있지만, 기존 필드는 항상 동일한 이름과 타입으로 유지됩니다.
• API URL은 /v1/으로 고정됩니다. 스키마 진화 시에도 엔드포인트 URL은 변경되지 않습니다.
• 응답의 meta.schemaVersion으로 현재 스키마 버전을 확인할 수 있습니다.

{
  "meta": {
    "schemaVersion": "1.0.0"
  },
  "data": [...]
}