스키마 동결 정책

5.0 갱신. hwpx.document_plan.v1/v2·hwpx.agent-batch/v1· hwpx.mixed-form-plan/v1은 이 표에서 빠졌습니다. 제거된 게 아니라 python-hwpx-automation이 발행 주체가 됐기 때문입니다 — core는 더 이상 그 payload를 만들지 않으므로, 여기서 동결을 약속하는 것은 지키지 못할 약속입니다. 세 스키마의 동결은 python-hwpx-automation의 계약 정책이 이어받습니다.

python-hwpx가 발행하는 versioned contract는 4.0.0에서 required 필드 집합이 동결됩니다. 목적은 한 가지 — 이미 나간 payload가 앞으로도 계속 검증을 통과하게 하는 것입니다.

동결 대상

스키마	동결된 required
hwpx.mutation-report/v1	schemaVersion, ok, path, requestedMode, actualMode, fallbackUsed, changedParts, preservation, verification

규칙 (additive-only)

1. 필드 추가는 허용, 단 Optional이어야 함. 새 필드는 생략 가능해야 하며, 없을 때 기존 동작이 유지돼야 합니다. 옛 payload가 그대로 통과합니다.

2. required 승격 금지. 기존 Optional 필드를 required로 올리거나 새 required 필드를 추가하는 것은 파괴 변경입니다.

3. 파괴 변경은 새 major + 새 스키마 버전 문자열로만. 예: hwpx.document_plan.v3, hwpx.mutation-report/v2. 같은 버전 문자열의 의미를 바꾸지 않습니다.

강제 방법

tests/test_schema_freeze.py가 각 스키마의 최소-유효 fixture(정확히 동결된 키만 가진)를 검증하고, required 키를 하나씩 제거하면 거부됨을 확인합니다. 미래에 required 필드가 추가되면 이 fixture가 검증을 통과하지 못해 테스트가 실패합니다 — 변경을 Optional로 만들거나 스키마 버전을 의도적으로 올리도록 강제합니다.

동결된 스키마는 대부분 닫힌(closed) 형태라 알 수 없는 키도 거부합니다. 따라서 새 Optional 필드도 검증기(또는 JSON 스키마 properties)에 명시적으로 추가해야 하며, 이때 required에는 넣지 않습니다.