hwp_ir_v1.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://danmeon.github.io/rhwp-python/schema/hwp_ir/v1/schema.json",
  "$defs": {
    "CaptionBlock": {
      "additionalProperties": false,
      "description": "캡션 블록 — 그림/표 등에 부착되는 보조 설명.\n\nHWP 는 ``Picture.caption: Option<Caption>`` / ``Table.caption: Option<Caption>``\n으로 항상 1:1 부착 관계 — 캡션은 부모 블록의 필드로 컨테인먼트 (ref-id 미도입).\nAzure DI / Docling 의 string-ref 패턴은 1:N 주소가 가능하지만 HWP 사용처에서\n이점이 없고 소비자가 JSON-Pointer resolver 를 구현해야 하므로 거부 (spec § 5).\n\n``blocks`` 가 재귀 ``Block`` 리스트 — 캡션 안의 인라인 수식·필드도 자연스럽게\n표현 (예: ``\"<그림 1> 회로도 ${}^{2}$\"`` 같은 캡션).\n\n``direction`` 은 캡션 배치 방향. 상류 ``CaptionDirection`` (Left/Right/Top/Bottom)\n을 lowercase Literal 로 매핑. 기본값 ``\"bottom\"`` 은 HWP 기본 + Docling 관례\n일치.",
      "properties": {
        "kind": {
          "const": "caption",
          "default": "caption",
          "title": "Kind",
          "type": "string"
        },
        "blocks": {
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/ParagraphBlock"
              },
              {
                "$ref": "#/$defs/TableBlock"
              },
              {
                "$ref": "#/$defs/PictureBlock"
              },
              {
                "$ref": "#/$defs/FormulaBlock"
              },
              {
                "$ref": "#/$defs/FootnoteBlock"
              },
              {
                "$ref": "#/$defs/EndnoteBlock"
              },
              {
                "$ref": "#/$defs/ListItemBlock"
              },
              {
                "$ref": "#/$defs/CaptionBlock"
              },
              {
                "$ref": "#/$defs/TocBlock"
              },
              {
                "$ref": "#/$defs/FieldBlock"
              },
              {
                "$ref": "#/$defs/UnknownBlock"
              }
            ]
          },
          "title": "Blocks",
          "type": "array"
        },
        "direction": {
          "default": "bottom",
          "enum": [
            "top",
            "bottom",
            "left",
            "right"
          ],
          "title": "Direction",
          "type": "string"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "prov"
      ],
      "title": "CaptionBlock",
      "type": "object"
    },
    "DocumentMetadata": {
      "additionalProperties": false,
      "description": "문서 레벨 메타데이터. 시각은 ISO 8601 문자열로 출고한다.",
      "properties": {
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Title"
        },
        "author": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Author"
        },
        "creation_time": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Creation Time"
        },
        "modification_time": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Modification Time"
        }
      },
      "title": "DocumentMetadata",
      "type": "object"
    },
    "DocumentSource": {
      "additionalProperties": false,
      "description": "문서 출처 — RAG 응답 역추적 시 \"이 답이 어느 파일에서 나왔나\" 에 응답한다.\n\n스키마는 ``uri`` 형식을 강제하지 않으므로 소비자가 file://, https://, 혹은\n``mem://{hash}`` 같은 custom 스킴으로 정규화할 수 있다. 향후 ``format``,\n``bytes_size``, ``sha256`` 등 재현성 필드는 기본값 있는 옵셔널로만 추가 —\n이 경로는 기존 JSON 과 MINOR 호환 유지.",
      "properties": {
        "uri": {
          "description": "파일 시스템 경로, URL, 혹은 소비자 정의 식별자. RFC 3986 URI reference 로 해석 가능한 문자열이면 충분하다.",
          "title": "Uri",
          "type": "string"
        }
      },
      "required": [
        "uri"
      ],
      "title": "DocumentSource",
      "type": "object"
    },
    "EndnoteBlock": {
      "additionalProperties": false,
      "description": "미주 블록 — HWP ``Control::Endnote``.\n\n각주와 같은 구조지만 배치가 다르다 (각주: 페이지 하단, 미주: 문서/구역 끝).\nHWP 가 별도 struct 로 분리하므로 IR 도 분리 — 통합 시 정보 손실.",
      "properties": {
        "kind": {
          "const": "endnote",
          "default": "endnote",
          "title": "Kind",
          "type": "string"
        },
        "number": {
          "title": "Number",
          "type": "integer"
        },
        "blocks": {
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/ParagraphBlock"
              },
              {
                "$ref": "#/$defs/TableBlock"
              },
              {
                "$ref": "#/$defs/PictureBlock"
              },
              {
                "$ref": "#/$defs/FormulaBlock"
              },
              {
                "$ref": "#/$defs/FootnoteBlock"
              },
              {
                "$ref": "#/$defs/EndnoteBlock"
              },
              {
                "$ref": "#/$defs/ListItemBlock"
              },
              {
                "$ref": "#/$defs/CaptionBlock"
              },
              {
                "$ref": "#/$defs/TocBlock"
              },
              {
                "$ref": "#/$defs/FieldBlock"
              },
              {
                "$ref": "#/$defs/UnknownBlock"
              }
            ]
          },
          "title": "Blocks",
          "type": "array"
        },
        "marker_prov": {
          "$ref": "#/$defs/Provenance"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "number",
        "marker_prov",
        "prov"
      ],
      "title": "EndnoteBlock",
      "type": "object"
    },
    "FieldBlock": {
      "additionalProperties": false,
      "description": "필드 컨트롤 — HWP ``Control::Field`` (TOC 제외 13 종 + Unknown).\n\n상류 ``FieldType`` 14 종 → 닫힌 ``FieldKind`` Literal 매핑. ``TableOfContents``\n는 별도 ``TocBlock`` 으로 라우팅되므로 ``FieldBlock`` 에는 ``\"toc\"`` 가\n원칙적으로 등장 안 함 — Literal 로 보존만 하고 (사용자가 직접 구성 시 호환).\n\n``InlineRun.href`` 와의 중복: HWP ``Hyperlink`` / ``Bookmark`` Field 는 본문\nInlineRun 의 ``href`` 로 표현될 수도 있지만 v0.3.0 은 모든 Field control 을\n별도 FieldBlock 으로 emit 한다 — InlineRun.href 자동 채움 path 는 미구현.\n\n``raw_instruction`` 은 round-trip 보존용 — Word ``<w:instrText>`` 와 같은 raw\n명령 문자열. v0.3.0 소비자는 보통 ``cached_value`` 만 사용하지만, 미래\nwriteback 시 raw 가 필요.\n\n``field_type_code`` 는 forward-compat — 상류가 새 FieldType 을 추가하면\n매퍼는 ``field_kind=\"unknown\"`` + ``field_type_code=<raw>`` 로 출고하고,\n다음 MINOR (v0.4.0) 에서 Literal 확장.",
      "properties": {
        "kind": {
          "const": "field",
          "default": "field",
          "title": "Kind",
          "type": "string"
        },
        "field_kind": {
          "default": "unknown",
          "enum": [
            "date",
            "doc_date",
            "path",
            "bookmark",
            "mailmerge",
            "crossref",
            "calc",
            "clickhere",
            "summary",
            "userinfo",
            "hyperlink",
            "memo",
            "private_info",
            "toc",
            "unknown"
          ],
          "title": "Field Kind",
          "type": "string"
        },
        "cached_value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "저장 시점 표시 값 (예: ``\"2026-04-26\"``). 동적 필드는 stale 가능.",
          "title": "Cached Value"
        },
        "raw_instruction": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "HWP field command (Word ``<w:instrText>`` 대응) — round-trip 보존.",
          "title": "Raw Instruction"
        },
        "field_type_code": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "미지의 raw 코드 — 상류 FieldType 추가 시 forward-compat.",
          "title": "Field Type Code"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "prov"
      ],
      "title": "FieldBlock",
      "type": "object"
    },
    "FootnoteBlock": {
      "additionalProperties": false,
      "description": "각주 블록 — HWP ``Control::Footnote``.\n\n각주 본문은 ``furniture.footnotes`` 로 라우팅되어 RAG 의 body 검색을 오염시키지\n않는다. ``marker_prov`` 는 본문 인용 마커 (``…기존 연구[3]…`` 의 ``[3]`` 위치) 의\nparent paragraph (section_idx, para_idx) 를 가리킨다 — 정확한 char_offset 까지는\n상류 ``field_ranges`` 매핑이 필요해 v0.4.0+ 검토. ``prov`` 는 각주 본문 자체의\n위치 = 마커가 등장한 paragraph 와 동일 (각주는 그 paragraph 에서 파생).\n\n``blocks`` 가 재귀 ``Block`` 리스트라 각주 본문 안의 표·그림·수식도 자연 지원.",
      "properties": {
        "kind": {
          "const": "footnote",
          "default": "footnote",
          "title": "Kind",
          "type": "string"
        },
        "number": {
          "description": "표시 번호 (1, 2, 3, ...).",
          "title": "Number",
          "type": "integer"
        },
        "blocks": {
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/ParagraphBlock"
              },
              {
                "$ref": "#/$defs/TableBlock"
              },
              {
                "$ref": "#/$defs/PictureBlock"
              },
              {
                "$ref": "#/$defs/FormulaBlock"
              },
              {
                "$ref": "#/$defs/FootnoteBlock"
              },
              {
                "$ref": "#/$defs/EndnoteBlock"
              },
              {
                "$ref": "#/$defs/ListItemBlock"
              },
              {
                "$ref": "#/$defs/CaptionBlock"
              },
              {
                "$ref": "#/$defs/TocBlock"
              },
              {
                "$ref": "#/$defs/FieldBlock"
              },
              {
                "$ref": "#/$defs/UnknownBlock"
              }
            ]
          },
          "title": "Blocks",
          "type": "array"
        },
        "marker_prov": {
          "$ref": "#/$defs/Provenance",
          "description": "본문 인용 마커 위치 — RAG 가 각주가 어디서 인용됐는지 역추적."
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "number",
        "marker_prov",
        "prov"
      ],
      "title": "FootnoteBlock",
      "type": "object"
    },
    "FormulaBlock": {
      "additionalProperties": false,
      "description": "수식 블록 — HWP ``Control::Equation``.\n\nHWP 수식은 자체 스크립트 (``script``) 로 저장된다 (예: ``\"1 over 2 + sqrt{x^2}\"``).\nHWP equation script → LaTeX/MathML 자동 변환은 공개 도구 부재로 v0.3.0 미제공\n(spec § 비목표). ``script_kind=\"hwp_eq\"`` 로 raw 출고 → 사용자가 외부 변환 후\n``model_copy(update={\"script\": tex, \"script_kind\": \"latex\"})`` 로 재구성 가능.\n\n``text_alt`` 는 RAG 폴백 — 단순 정규화 (``over`` → ``/``, ``sqrt{...}`` → ``√(...)``)\n까지만 적용. 실패 시 None.",
      "properties": {
        "kind": {
          "const": "formula",
          "default": "formula",
          "title": "Kind",
          "type": "string"
        },
        "script": {
          "title": "Script",
          "type": "string"
        },
        "script_kind": {
          "default": "hwp_eq",
          "enum": [
            "hwp_eq",
            "latex",
            "mathml"
          ],
          "title": "Script Kind",
          "type": "string"
        },
        "text_alt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "평문 근사 — RAG fallback. ``script`` 의 사람이 읽을 수 있는 형태 (``over`` → ``/`` 등) 를 단순 정규화. 실패 시 None.",
          "title": "Text Alt"
        },
        "inline": {
          "default": false,
          "description": "True: 본문 인라인 수식, False: 별도 디스플레이 수식.",
          "title": "Inline",
          "type": "boolean"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "script",
        "prov"
      ],
      "title": "FormulaBlock",
      "type": "object"
    },
    "Furniture": {
      "additionalProperties": false,
      "description": "장식 노드 컨테이너 — RAG 가 임베딩에서 필터링 가능.\n\nv0.3.0 S1 부터 ``page_headers`` / ``page_footers`` 가 실제 채워진다.\nv0.3.0 S2 부터 ``footnotes`` / ``endnotes`` 도 실제 채워지며 타입이\n``list[FootnoteBlock]`` / ``list[EndnoteBlock]`` 으로 강화된다.\n\niter_blocks(scope=\"furniture\") 순서: page_headers → page_footers →\nfootnotes → endnotes (spec § 8 furniture 순서 계약).",
      "properties": {
        "page_headers": {
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/ParagraphBlock"
              },
              {
                "$ref": "#/$defs/TableBlock"
              },
              {
                "$ref": "#/$defs/PictureBlock"
              },
              {
                "$ref": "#/$defs/FormulaBlock"
              },
              {
                "$ref": "#/$defs/FootnoteBlock"
              },
              {
                "$ref": "#/$defs/EndnoteBlock"
              },
              {
                "$ref": "#/$defs/ListItemBlock"
              },
              {
                "$ref": "#/$defs/CaptionBlock"
              },
              {
                "$ref": "#/$defs/TocBlock"
              },
              {
                "$ref": "#/$defs/FieldBlock"
              },
              {
                "$ref": "#/$defs/UnknownBlock"
              }
            ]
          },
          "title": "Page Headers",
          "type": "array"
        },
        "page_footers": {
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/ParagraphBlock"
              },
              {
                "$ref": "#/$defs/TableBlock"
              },
              {
                "$ref": "#/$defs/PictureBlock"
              },
              {
                "$ref": "#/$defs/FormulaBlock"
              },
              {
                "$ref": "#/$defs/FootnoteBlock"
              },
              {
                "$ref": "#/$defs/EndnoteBlock"
              },
              {
                "$ref": "#/$defs/ListItemBlock"
              },
              {
                "$ref": "#/$defs/CaptionBlock"
              },
              {
                "$ref": "#/$defs/TocBlock"
              },
              {
                "$ref": "#/$defs/FieldBlock"
              },
              {
                "$ref": "#/$defs/UnknownBlock"
              }
            ]
          },
          "title": "Page Footers",
          "type": "array"
        },
        "footnotes": {
          "items": {
            "$ref": "#/$defs/FootnoteBlock"
          },
          "title": "Footnotes",
          "type": "array"
        },
        "endnotes": {
          "items": {
            "$ref": "#/$defs/EndnoteBlock"
          },
          "title": "Endnotes",
          "type": "array"
        }
      },
      "title": "Furniture",
      "type": "object"
    },
    "ImageRef": {
      "additionalProperties": false,
      "description": "이미지 참조 — binary 자체는 IR JSON 에 inline 되지 않는다.\n\nURI 스킴:\n\n- ``bin://<bin_data_id>`` (기본): 상류 ``Picture.image_attr.bin_data_id`` 그대로.\n  ``Document.bytes_for_image(picture)`` 로 raw bytes 해석.\n- ``data:image/...;base64,...``: embedded 모드 (v0.4.0+ opt-in 검토)\n- ``file://path``: external 모드 (v0.4.0+ opt-in 검토)\n\n``uri`` 는 strict 검증 회피를 위해 plain ``str`` — JSON Schema strict mode 가\n``format: uri`` 를 거부하는 경우가 있고, ``bin://`` / ``data:`` 모두 허용해야 하므로.\nURL 검증은 사용자 책임.\n\nwidth/height/dpi 는 v0.3.0 S1 에서 항상 ``None`` — 상류 Picture 가 픽셀\ndimension 을 직접 노출하지 않으며 (border 좌표만 노출) HWPUNIT 계산은\nv0.4.0+ 에서 검토.",
      "properties": {
        "uri": {
          "title": "Uri",
          "type": "string"
        },
        "mime_type": {
          "title": "Mime Type",
          "type": "string"
        },
        "width": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Width"
        },
        "height": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Height"
        },
        "dpi": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Dpi"
        }
      },
      "required": [
        "uri",
        "mime_type"
      ],
      "title": "ImageRef",
      "type": "object"
    },
    "InlineRun": {
      "additionalProperties": false,
      "description": "서식이 동일한 연속 문자 런.\n\nbold/italic/underline/strikethrough/href/ruby 외의 서식 속성 (폰트, 크기,\n색상 등) 은 ``raw_style_id`` 로 escape 된다 — 상류 ``doc_info`` 스타일 인덱스.",
      "properties": {
        "text": {
          "title": "Text",
          "type": "string"
        },
        "bold": {
          "default": false,
          "title": "Bold",
          "type": "boolean"
        },
        "italic": {
          "default": false,
          "title": "Italic",
          "type": "boolean"
        },
        "underline": {
          "default": false,
          "title": "Underline",
          "type": "boolean"
        },
        "strikethrough": {
          "default": false,
          "title": "Strikethrough",
          "type": "boolean"
        },
        "href": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Href"
        },
        "ruby": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Ruby"
        },
        "raw_style_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Upstream doc_info 스타일 인덱스. 폰트/크기/색상 등 non-binary 서식을 escape 한다. None 은 char_shape 레코드가 없는 손상/비정상 입력 방어 경로 — 정상 HWP 는 모든 런이 char_shape 에 대응되어 항상 값이 채워진다.",
          "title": "Raw Style Id"
        }
      },
      "required": [
        "text"
      ],
      "title": "InlineRun",
      "type": "object"
    },
    "ListItemBlock": {
      "additionalProperties": false,
      "description": "목록 항목 — HWP ``ParaShape`` 의 ``head_type`` 가 비-None 인 단락.\n\nHWP 상류는 list group 컨테이너가 없다 (``ParaShape.head_type`` 가\nNumber/Bullet/Outline 인 단락이 곧 list item) — group container 는 도입하지\n않고 평면 (``level + marker + enumerated``) 으로 표현. RAG 청킹 시 항목 단위\n검색에 그대로 매핑.\n\n``marker`` 는 v0.3.0 단순 정책: ``\"•\"`` (bullet) / ``\"1.\"`` (number/outline).\n상류 ``Numbering.level_formats`` lookup 으로 정확한 마커 (예: ``\"가.\"``,\n``\"(a)\"``) 추출은 v0.4.0+ 에서 검토 — 현 시점은 placeholder 만.\n\n``text`` 는 마커 제외 본문 (``ParagraphBlock`` 과 동일) — 마커는\n``marker`` 필드로 별도. ``\"1. 제목\"`` 이 아니라 ``marker=\"1.\"``,\n``text=\"제목\"`` 형태.",
      "properties": {
        "kind": {
          "const": "list_item",
          "default": "list_item",
          "title": "Kind",
          "type": "string"
        },
        "text": {
          "default": "",
          "title": "Text",
          "type": "string"
        },
        "inlines": {
          "items": {
            "$ref": "#/$defs/InlineRun"
          },
          "title": "Inlines",
          "type": "array"
        },
        "enumerated": {
          "default": false,
          "description": "True: 번호 매김 (1./가./i. 등), False: 글머리표 (•/■/▶ 등).",
          "title": "Enumerated",
          "type": "boolean"
        },
        "marker": {
          "default": "-",
          "description": "표시 마커 placeholder. v0.3.0 은 ``\"•\"`` / ``\"1.\"`` 만 출고 — 정확 마커는 상류 Numbering lookup 필요해 v0.4.0+ 검토.",
          "title": "Marker",
          "type": "string"
        },
        "level": {
          "default": 0,
          "description": "0-indexed nesting depth. 상류 ``ParaShape.para_level`` (0~6, 1~7 수준 표시) 를 그대로 매핑.",
          "title": "Level",
          "type": "integer"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "prov"
      ],
      "title": "ListItemBlock",
      "type": "object"
    },
    "ParagraphBlock": {
      "additionalProperties": false,
      "description": "단락 블록. 서식 런 리스트 + 평탄 텍스트 파생 필드를 병기한다.\n\n``text`` 는 ``inlines`` 의 ``text`` 필드를 이어붙인 결과 — LLM 에 넘기는\n평문화 경로. 원본 서식 보존이 필요한 소비자만 ``inlines`` 를 직접 순회한다.",
      "properties": {
        "kind": {
          "const": "paragraph",
          "default": "paragraph",
          "title": "Kind",
          "type": "string"
        },
        "text": {
          "default": "",
          "title": "Text",
          "type": "string"
        },
        "inlines": {
          "items": {
            "$ref": "#/$defs/InlineRun"
          },
          "title": "Inlines",
          "type": "array"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "prov"
      ],
      "title": "ParagraphBlock",
      "type": "object"
    },
    "PictureBlock": {
      "additionalProperties": false,
      "description": "그림 블록 — HWP ``Control::Picture``.\n\n``image is None`` 은 명시적 broken reference — 상류 ``Picture.image_attr.bin_data_id``\n가 0 (미할당) 인 케이스만 해당. ``bin_data_id`` 가 0 이 아니어도 실제 binary\nlookup 이 실패할 수 있다 (Link 타입이거나 bin_data_content 누락) — 이 경우\nImageRef 는 ``mime_type=\"application/octet-stream\"`` 으로 출고되고 실패는\n``Document.bytes_for_image`` 호출 시점에 ValueError 로 표면화된다 (forensics\n위해 bin_data_id 자체는 URI 에 보존).\n\n``caption`` 은 v0.3.0 S3 부터 채워지는 구조화 캡션 — 부모 ``PictureBlock`` 의\n필드로 컨테인먼트 (ref-id 없이 직접 연결, spec § 5).\n\n``description`` 은 HWP 의 alt-text 슬롯 — caption paragraph 의 평문 fallback\n(S1 호환 보존). v0.4.0+ 에서 caption 충실하게 채워지면 description 은 deprecate\n검토.",
      "properties": {
        "kind": {
          "const": "picture",
          "default": "picture",
          "title": "Kind",
          "type": "string"
        },
        "image": {
          "anyOf": [
            {
              "$ref": "#/$defs/ImageRef"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "caption": {
          "anyOf": [
            {
              "$ref": "#/$defs/CaptionBlock"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "구조화 캡션 — v0.3.0 S3 부터 채워짐. ``blocks`` 안에 표/수식/필드도 재귀 표현. None 은 캡션 부재 (HWP Picture.caption == None)."
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "HWP 의 alt-text — 상류 caption paragraph 평문 fallback (S1 보존). 구조화 캡션이 필요하면 ``caption`` 필드 사용.",
          "title": "Description"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "prov"
      ],
      "title": "PictureBlock",
      "type": "object"
    },
    "Provenance": {
      "additionalProperties": false,
      "description": "블록의 원본 문서 내 위치. 다운스트림 청커가 원본을 역추적 가능하게 한다.",
      "properties": {
        "section_idx": {
          "title": "Section Idx",
          "type": "integer"
        },
        "para_idx": {
          "title": "Para Idx",
          "type": "integer"
        },
        "char_start": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Start character index (Unicode codepoints, 0-indexed). Compatible with Python str slicing: text[char_start:char_end].",
          "title": "Char Start"
        },
        "char_end": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "End character index (Unicode codepoints, 0-indexed, exclusive).",
          "title": "Char End"
        },
        "page_range": {
          "anyOf": [
            {
              "maxItems": 2,
              "minItems": 2,
              "prefixItems": [
                {
                  "type": "integer"
                },
                {
                  "type": "integer"
                }
              ],
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive (start_page, end_page). 렌더 단계에서만 계산되므로 파싱 경로는 None 을 출고한다.",
          "title": "Page Range"
        }
      },
      "required": [
        "section_idx",
        "para_idx"
      ],
      "title": "Provenance",
      "type": "object"
    },
    "Section": {
      "additionalProperties": false,
      "description": "HWP 구역 식별자. 용지·단·헤더 레퍼런스 등 상세 속성은 향후 추가된다.",
      "properties": {
        "section_idx": {
          "title": "Section Idx",
          "type": "integer"
        }
      },
      "required": [
        "section_idx"
      ],
      "title": "Section",
      "type": "object"
    },
    "TableBlock": {
      "additionalProperties": false,
      "description": "표 블록. 단일 표현으로 RAG 품질 최대화 불가 → 3중 표현 병기.\n\n- ``cells`` : 프로그래매틱 접근 (SQL 생성, 셀 순회)\n- ``html``  : LLM 에 제공, rowspan/colspan 보존 (HtmlRAG 호환)\n- ``text``  : 단순 검색·diff 용 폴백 (행은 개행, 셀은 탭 구분)\n\n``caption`` (str) 은 v0.2.0 호환 평문 슬롯 — caption_block 의 첫 paragraph\n텍스트 fallback. 구조화 캡션이 필요하면 ``caption_block`` 사용.",
      "properties": {
        "kind": {
          "const": "table",
          "default": "table",
          "title": "Kind",
          "type": "string"
        },
        "rows": {
          "title": "Rows",
          "type": "integer"
        },
        "cols": {
          "title": "Cols",
          "type": "integer"
        },
        "cells": {
          "items": {
            "$ref": "#/$defs/TableCell"
          },
          "title": "Cells",
          "type": "array"
        },
        "html": {
          "default": "",
          "title": "Html",
          "type": "string"
        },
        "text": {
          "default": "",
          "title": "Text",
          "type": "string"
        },
        "caption": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "v0.2.0 호환 평문 캡션 — ``caption_block.blocks`` 첫 ParagraphBlock 의 평문이면 일관성 유지. 구조화 캡션은 ``caption_block`` 사용.",
          "title": "Caption"
        },
        "caption_block": {
          "anyOf": [
            {
              "$ref": "#/$defs/CaptionBlock"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "v0.3.0 S3 신규 — 구조화 캡션. v0.2.0 ``caption: str`` 필드는 그대로 유지하고 옵셔널 신설."
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "rows",
        "cols",
        "prov"
      ],
      "title": "TableBlock",
      "type": "object"
    },
    "TableCell": {
      "additionalProperties": false,
      "description": "표 셀. ``blocks`` 가 재귀 ``Block`` 리스트라 중첩 표를 자연 지원한다.\n\n``role`` 어휘는 DocLayNet 파생. ``\"layout\"`` 은 구조 유지용 비의미 셀\n(병합된 빈 영역 등) — LLM 이 \"데이터 없음이 아닌 레이아웃 요소\" 로 인식하도록 태깅한다.",
      "properties": {
        "row": {
          "title": "Row",
          "type": "integer"
        },
        "col": {
          "title": "Col",
          "type": "integer"
        },
        "row_span": {
          "default": 1,
          "title": "Row Span",
          "type": "integer"
        },
        "col_span": {
          "default": 1,
          "title": "Col Span",
          "type": "integer"
        },
        "grid_index": {
          "description": "Anchor cell position in row-major flat index (row * table.cols + col). Not a reverse-lookup key; span-covered positions do not appear as separate cells.",
          "title": "Grid Index",
          "type": "integer"
        },
        "role": {
          "default": "data",
          "description": "DocLayNet-derived cell role. Current producer maps HWP 'is_header' to 'column_header' and tags merged-empty cells as 'layout'; 'row_header' is reserved for producers that can distinguish row vs column headers.",
          "enum": [
            "data",
            "column_header",
            "row_header",
            "layout"
          ],
          "title": "Role",
          "type": "string"
        },
        "blocks": {
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/ParagraphBlock"
              },
              {
                "$ref": "#/$defs/TableBlock"
              },
              {
                "$ref": "#/$defs/PictureBlock"
              },
              {
                "$ref": "#/$defs/FormulaBlock"
              },
              {
                "$ref": "#/$defs/FootnoteBlock"
              },
              {
                "$ref": "#/$defs/EndnoteBlock"
              },
              {
                "$ref": "#/$defs/ListItemBlock"
              },
              {
                "$ref": "#/$defs/CaptionBlock"
              },
              {
                "$ref": "#/$defs/TocBlock"
              },
              {
                "$ref": "#/$defs/FieldBlock"
              },
              {
                "$ref": "#/$defs/UnknownBlock"
              }
            ]
          },
          "title": "Blocks",
          "type": "array"
        }
      },
      "required": [
        "row",
        "col",
        "grid_index"
      ],
      "title": "TableCell",
      "type": "object"
    },
    "TocBlock": {
      "additionalProperties": false,
      "description": "목차 블록 — HWP ``Control::Field`` with ``FieldType::TableOfContents``.\n\nHWP TOC 는 frozen at save time — 소비자가 신뢰할 수 있는 navigation 은\n(있다면) heading hierarchy 쪽이며 TOC 는 사람이 마지막에 본 표시 그대로의\n스냅샷이다.\n\nv0.3.0 S3 매퍼는 TOC field 검출만 수행 — 항목 추출은 v0.4.0+ 에서 검토\n(spec § 6 결정). 따라서 v0.3.0 출고 시 ``entries`` 는 빈 리스트가 일반적.",
      "properties": {
        "kind": {
          "const": "toc",
          "default": "toc",
          "title": "Kind",
          "type": "string"
        },
        "entries": {
          "items": {
            "$ref": "#/$defs/TocEntryBlock"
          },
          "title": "Entries",
          "type": "array"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "prov"
      ],
      "title": "TocBlock",
      "type": "object"
    },
    "TocEntryBlock": {
      "additionalProperties": false,
      "description": "목차 항목 — ``TocBlock.entries`` 안에서만 살아 있는 leaf type.\n\nBlock 유니온 멤버가 아니다 (``TableCell`` 과 같은 패턴) — ``iter_blocks`` 는\n``TocBlock`` 만 yield 하고, 항목 순회는 ``toc.entries`` 직접 접근.\n\n``cached_page`` 는 HWP 가 저장 시점에 박제한 페이지 번호 — 문서가 편집된 후에\nheading 이 이동하면 stale 가능 (`is_stale=True`). ``is_stale`` 정확 검출은\nheading hierarchy 와 cached text 비교 + bookmark resolution 필요 — v0.3.0 은\ncached value 만 노출하고 stale 검출은 v0.4.0+ 에 위임 (spec § 6 결정).\n\n``target_section_idx`` 는 raw bookmark 이름 → section 인덱스 resolution 결과.\n상류 bookmark resolver 가 필요해 v0.3.0 은 항상 None — raw\n``target_bookmark_name`` 만 보존.",
      "properties": {
        "kind": {
          "const": "toc_entry",
          "default": "toc_entry",
          "title": "Kind",
          "type": "string"
        },
        "text": {
          "title": "Text",
          "type": "string"
        },
        "level": {
          "default": 1,
          "description": "1-indexed (h1, h2, h3, ...) — TOC 표시 레벨.",
          "title": "Level",
          "type": "integer"
        },
        "target_bookmark_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "HWP bookmark 이름 (raw) — v0.4.0+ 의 resolver 입력.",
          "title": "Target Bookmark Name"
        },
        "target_section_idx": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "resolved section idx — v0.3.0 은 항상 None (resolver 미도입).",
          "title": "Target Section Idx"
        },
        "cached_page": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "저장 시점 페이지 번호 (HWP frozen at save). 편집 후 heading 이 이동하면 stale 가능. 정확 navigation 은 heading hierarchy 쪽.",
          "title": "Cached Page"
        },
        "is_stale": {
          "default": false,
          "description": "cached info ≠ 현재 heading 일치 여부. v0.3.0 은 항상 False — 정확 검출은 v0.4.0+ 에서 (spec § 6).",
          "title": "Is Stale",
          "type": "boolean"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "text",
        "prov"
      ],
      "title": "TocEntryBlock",
      "type": "object"
    },
    "UnknownBlock": {
      "additionalProperties": true,
      "description": "Forward-compatibility catch-all.\n\nPydantic V2 의 기본 string discriminator 는 미지의 ``kind`` 를 만나면\n``union_tag_invalid`` 로 문서 전체 파싱을 거부한다. callable Discriminator\n로 미지 ``kind`` 를 본 variant 로 라우팅하여, 나중에 새로운 블록 타입이\n추가되어도 구 버전 소비자가 읽기-불가 상태가 되지 않게 한다.\n\n소비자는 ``case UnknownBlock(): skip`` 패턴을 사용한다. ``assert_never``\n패턴은 새 variant 추가 시 빌드가 깨지므로 **사용 금지**.",
      "properties": {
        "kind": {
          "description": "Unknown block kind — must NOT match any known block kind. callable Discriminator (`_block_discriminator`) 가 미지 kind 만 본 variant 로 라우팅하므로 SSOT 와 정합.",
          "not": {
            "enum": [
              "caption",
              "endnote",
              "field",
              "footnote",
              "formula",
              "list_item",
              "paragraph",
              "picture",
              "table",
              "toc"
            ]
          },
          "title": "Kind",
          "type": "string"
        },
        "prov": {
          "$ref": "#/$defs/Provenance"
        }
      },
      "required": [
        "kind",
        "prov"
      ],
      "title": "UnknownBlock",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Document IR 루트.\n\n``schema_name`` / ``schema_version`` 으로 인스턴스 자기-기술. body 와\nfurniture 를 분리해 RAG 가 장식 노드를 필터링할 수 있다.",
  "properties": {
    "schema_name": {
      "default": "HwpDocument",
      "pattern": "^HwpDocument$",
      "title": "Schema Name",
      "type": "string"
    },
    "schema_version": {
      "default": "1.1",
      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
      "title": "Schema Version",
      "type": "string"
    },
    "source": {
      "anyOf": [
        {
          "$ref": "#/$defs/DocumentSource"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "metadata": {
      "$ref": "#/$defs/DocumentMetadata"
    },
    "sections": {
      "items": {
        "$ref": "#/$defs/Section"
      },
      "title": "Sections",
      "type": "array"
    },
    "body": {
      "items": {
        "oneOf": [
          {
            "$ref": "#/$defs/ParagraphBlock"
          },
          {
            "$ref": "#/$defs/TableBlock"
          },
          {
            "$ref": "#/$defs/PictureBlock"
          },
          {
            "$ref": "#/$defs/FormulaBlock"
          },
          {
            "$ref": "#/$defs/FootnoteBlock"
          },
          {
            "$ref": "#/$defs/EndnoteBlock"
          },
          {
            "$ref": "#/$defs/ListItemBlock"
          },
          {
            "$ref": "#/$defs/CaptionBlock"
          },
          {
            "$ref": "#/$defs/TocBlock"
          },
          {
            "$ref": "#/$defs/FieldBlock"
          },
          {
            "$ref": "#/$defs/UnknownBlock"
          }
        ]
      },
      "title": "Body",
      "type": "array"
    },
    "furniture": {
      "$ref": "#/$defs/Furniture"
    }
  },
  "title": "HwpDocument",
  "type": "object"
}