스키마 설계하기

스키마란 무엇인가요

Ztract에서 스키마는 돌려받고 싶은 데이터의 형태입니다. 이름, 타입, 그리고 선택적인 구조(예: “라인 아이템”은 객체의 배열이며, 각각 설명, 수량, 단가를 가짐)를 갖춘 필드의 목록이지요. 엔진은 업로드된 각 문서를 스키마에 비추어 읽어, 해당하는 값들을 원본 페이지의 어디에 있었는지에 고정한 채 돌려드립니다.

스키마는 프로젝트 안에 있습니다. 하나의 프로젝트 = 하나의 스키마 = 그 프로젝트의 모든 문서에 걸친 하나의 일관된 출력 형태입니다. 문서 유형이 여러 가지라면, 보통 유형별로 프로젝트를 하나씩 만드시게 됩니다.

필드 타입과 구조

각 필드는 여섯 가지 타입 중 하나를 가집니다.

• string — 자유 텍스트. 이름, 주소, 자유 형식의 설명.
• number — 소수 값. 금액, 백분율, 치수.
• integer — 정수. 수량, 개수.
• enum — 여러분이 정의한 고정된 목록에서만 와야 하는 문자열입니다. 주문 상태, 결제 수단, 통화 코드처럼 범주적으로 제한된 값에 사용하세요.
• object — 중첩된 필드의 묶음. 어떤 항목이 본래 하위 속성을 가질 때 사용하세요(street / city / zip을 가진 address).
• array — 반복되는 목록. 항목은 기본형(이력서의 “skills”)이거나 객체(송장의 “line items”)일 수 있습니다.

객체와 배열 구조는 3단계 깊이까지 중첩할 수 있습니다. 실제 문서 대부분은 두 단계로 충분합니다 — 송장의 라인 아이템, 계약서의 서명자 — 그리고 세 단계는 정말로 필요한 드문 경우의 상한선입니다.

방법 1 — 템플릿에서 시작하기

Ztract는 송장, 영수증, 계약서, 신분증 같은 자주 쓰이는 문서 유형에 대해 바로 쓸 수 있는 템플릿을 제공합니다. 각 템플릿은 필드 이름, 타입, 그리고 (해당하는 경우) 중첩 구조를 갖춘 동작하는 스키마입니다. 교과서적 이상이 아니라 실제 사례에서 만들어진 것들이지요. 정확한 카탈로그는 현지화되어 있습니다 — 대시보드 언어가 English로 설정되어 있으면 영어 이름의 템플릿이 보이고, 中文, 日本語 등으로 바꾸면 목록이 그에 맞춰 갱신됩니다.

이 방법이 가장 잘 어울리는 때. 문서 유형이 잘 정의된 범주에 들어맞고, 다운스트림 도구가 표준 형태를 기대하는 경우 — 예를 들어 “송장을 NetSuite로”, “경비 영수증을 Concur로” 같은 상황이지요. 두 번의 클릭으로 동작하는 스키마를 얻으실 수 있습니다.

커스터마이즈하는 법. 템플릿을 열어 팀의 용어에 맞게 필드 이름을 바꾸고, 필요 없는 필드는 삭제하고, 업무 흐름에 특화된 필드를 추가하세요. 스키마를 저장하면 업로드할 준비가 됩니다.

방법 2 — 일상 언어로 설명하기

템플릿이 맞지 않는다면, 원하시는 바를 적어 주세요. 필드를 설명하는 한두 문장을 입력하시면 됩니다. Ztract가 그 설명으로부터 완전한 스키마 초안을 만들어 드립니다. 저장하시기 전에 확인하거나 다듬으시면 됩니다.

예시 프롬프트. “각 구매 주문서에 대해 PO 번호, 공급처 이름과 주소, 발행일, 납기일, SKU·설명·수량·단가가 포함된 라인 아이템, 그리고 주문 합계를 추출. PO가 긴급 주문으로 표시되어 있는지도 표시.”

엔진이 다음과 같은 결과를 만들어 냅니다.

• po_number — string
• vendor — { name, address }
• issue_date — date
• delivery_date — date
• line_items — array of { sku, description, quantity, unit_price }
• order_total — number
• rush_order — boolean

이 방법이 가장 잘 어울리는 때. 필요한 것에 대한 머릿속 모형은 명확한데 업로드할 정전(正典) 같은 예시가 없을 때입니다. 또는 문서 유형이 충분히 틈새여서 어떤 템플릿도 들어맞지 않을 때이지요.

방법 3 — 샘플 문서로부터 추론하기

예시 문서를 하나 업로드하시면, 엔진이 그것을 읽고 찾아낸 필드 이름, 타입, 중첩 구조를 갖춘 스키마를 제안합니다. 그런 다음 조정하시면 됩니다. 관심 없는 필드는 제거하고, 샘플에 포함되지 않은 것은 추가하고, 타입을 더 엄격하게 만드시면 됩니다.

이 방법이 가장 잘 어울리는 때. 하나를 보기 전까지는 어떤 필드가 존재하는지 모를 때입니다 — 의료 보고서(검사실마다 패널을 다르게 인쇄합니다), 맞춤 작성된 계약서, 일회성 공급처 양식에서 흔합니다. 문서의 필드 이름이 특이해서 엔진이 정규화된 이름을 제안해 주길 원하실 때도 유용합니다.

만든 뒤에 스키마 다듬기

스키마는 언제든 편집하실 수 있습니다 — 필드 이름 변경, 새 필드 추가, 타입 변경, 중첩 재구성. 편집은 이미 처리된 문서에 영향을 주지 않습니다. 갱신된 형태를 얻으시려면 새 스키마로 다시 돌려야 합니다. 재실행은 과금됩니다(결제, 패키지, 환불 참고). 그래서 대부분의 팀은 본격적으로 처리하시기 전에 작은 배치에서 스키마를 먼저 확정합니다.

까다로운 필드를 위한 팁

• 날짜. 문서가 어떻게 인쇄했든 — DD/MM/YYYY, Jun 5 2026, “Q2 2026” — Ztract는 그것을 스키마에서 지정하신 날짜 형식으로 변환합니다. 형식을 지정하지 않으시면, 날짜는 인쇄된 그대로 반환됩니다.
• 금액과 통화. 통화는 원래 형태로 유지됩니다(€, $, ¥, ₩ 등). 무음 변환은 하지 않습니다. 라인별 세율은 해당하는 행에 그대로 붙어 있습니다.
• 중첩 구조. 문서가 본래 하위 객체를 가지고 있다면(계약서의 당사자들, 공급처 계약서 안의 결제 조건), 스키마에서 중첩을 사용하세요. 출력 JSON은 중첩을 그대로 반영합니다. CSV / Excel은 점 표기 경로로 평탄화합니다.
• 단순 문자열의 배열. 이력서의 “skills”나 여권의 “endorsements” 같은 필드는 문자열의 배열로 돌아옵니다. 대시보드는 병렬 뷰어에서 배열을 표로 렌더링합니다 — 항목당 한 행, 원본 영역으로 다시 연결된 채로요.
• enum 필드. 어휘가 제한된 필드(상태, 통화 코드, 문서 분류)는 enum이 가장 잘 어울립니다. 허용되는 값들을 한 번 제공해 두시면 엔진이 “Paid”, “paid”, “PAID”, “Settled” 같은 변형을 만들어 내지 않고 그 목록을 지킵니다.