모델은 추가 필드를 생성합니다. 직접 표시해야 할까요, 아니면 거부해야 할까요? 먼저 합의가 되었는지 살펴보겠습니다

모델은 구조화된 추출 결과에 하나의 필드를 더 반환하고, 프런트 엔드에서는 이를 유용한 정보로 직접 쉽게 표시할 수 있습니다. 예를 들어 추출 결과에 여분의 confidence가 있는 경우 페이지에 "신뢰도"로 표시됩니다. 문제는 이 필드가 정의되거나 보정되지 않을 수 있다는 것입니다. 추가 필드가 반드시 무해한 것은 아니며 다운스트림 사용자가 합의되지 않은 값을 판단의 기초로 사용할 수 있습니다.

이 기사는 인터페이스 디자인, 프런트엔드 및 백엔드 도킹 또는 문서 처리 프로세스를 담당하는 학생에게 적합합니다. 다음에서는 인터페이스가 열려 있는지 닫혀 있는지 먼저 결정하는 방법, 알 수 없는 필드를 관찰 가능한 오류로 바꾸는 방법, 거부 후 반환해야 하는 정보에 대해 설명합니다. 이를 읽은 후 추가 필드를 거부할지, 무시할지, 아니면 새 버전에 포함할지 결정할 수 있습니다.

이 기사에서는 합성 샘플을 사용하여 처리 방법을 보여줍니다. 코드는 격리된 환경에서 예제로 확인되었으며 모든 실제 파일이나 제품 성능을 보장하지는 않습니다. 중요한 서류를 처리하기 전, 원본을 보관하시고, 본문에 기재된 경계 및 허용 항목에 따라 검토하시기 바랍니다.

모델의 여러 필드를 직접 표시할 수 있나요? 한 문장 결론

먼저 계약에 동의한 다음 이를 수락할지 거부할지 결정하세요. 정의되지 않고 보정된 필드는 신뢰할 수 있는 증거로 직접 표시되어서는 안 됩니다.

당신의 상황	권장 사례	이유
내부 탐색 도구	확장 필드를 허용할 수 있습니다.	탐색 단계에서 유연성을 우선시합니다.
안정적인 전달 인터페이스	`additionalProperties: false`로 각 레이어를 닫습니다.	다운스트림의 잘못된 읽기를 방지하기 위해 정의되지 않은 속성을 거부합니다.
새로운 법률 필드가 나타납니다.	새 버전의 스키마 게시	몰래 이전 버전을 긴장하지 마세요
중복 필드를 무시하도록 선택	원본 결과 및 필터링 동작 기록	소스 데이터에 이 필드가 없는지, 인터페이스 레이어에서 이를 제거했는지 구별하는 것이 편리합니다.

먼저 인터페이스가 열려 있는지 닫혀 있는지 결정하세요.

내부 탐색 도구는 확장된 필드를 허용할 수 있으며 안정적인 전달 인터페이스에는 더 엄격한 경계가 필요한 경우가 많습니다. JSON 스키마의 추가속성가 false로 설정된 경우 현재 개체의 정의되지 않은 속성이 거부될 수 있지만 중첩된 각 개체는 자동으로 반복적으로 덮어쓰여지지 않습니다. 각 수준에서 허용되는 사항이 명확하게 작성되어야 합니다.

이는 모든 인터페이스가 모든 확장을 거부해야 한다는 의미는 아닙니다. 핵심은 선택을 명확하게 하고 업그레이드를 위해 버전 관리 메커니즘을 열어 두는 것입니다. 오늘 같은 이름을 가진 필드를 조용히 무시하고 내일 갑자기 사용하면 과거 데이터에 대한 다른 해석이 쉽게 발생할 수 있습니다.

알 수 없는 필드를 관찰 가능한 오류로 전환

from jsonschema import Draft202012Validator

schema = {"type": "object", "required": ["name", "evidence"],
          "properties": {"name": {"type": "string"},
                         "evidence": {"type": "object", "required": ["page"],
                                      "properties": {"page": {"type": "integer", "minimum": 1}},
                                      "additionalProperties": False}},
          "additionalProperties": False}
validator = Draft202012Validator(schema)
valid = lambda x: not list(validator.iter_errors(x))

assert valid({"name": "Demo", "evidence": {"page": 1}})
assert not valid({"name": "Demo", "confidence": 0.99, "evidence": {"page": 1}})
assert not valid({"name": "Demo", "evidence": {"page": 1, "guess": True}})

예시의 숫자 값 0.99는 거부되어야 하는 합성 입력일 뿐이며 모든 모델에 대한 실제 품질 결과는 아닙니다. 예제에서는 최상위 레이어와 중첩 레이어를 동시에 확인하여 외부 레이어만 닫고 내부 레이어를 임의로 확장하는 누락을 방지합니다.

거절 후 수리 가능한 정보 제공

상태	반품 정보에는 다음이 포함되어야 합니다.	하지 말아야 할 것
최상위 수준 다중 필드	알 수 없는 키 이름, 프로토콜 버전	신뢰할 수 있는 표시로 자동 표시
내부 다중 필드	객체 경로, 미확인 키 이름	JSON 오류는 단 하나만 반환됩니다
새 버전은 법적으로 확장되었습니다	명확한 새로운 도식	몰래 옛 버전은 느슨하게 해.
모델은 반복적으로 중복 키를 출력합니다	임무 실패의 원인을 추출하라	각 삭제 후, 원본 출력이 자격을 갖춘 것처럼 간주합니다

📊 핵심 비교: 오픈 인터페이스 vs. 폐쇄 인터페이스

치수	오픈 인터페이스	폐쇄형 인터페이스
적용 가능한 시나리오	내부 탐색 도구	안정적인 전달 인터페이스
중복 필드 처리	확장 허용	정의되지 않은 속성을 거부합니다
주요 위험	합의되지 않은 값들이 근거로 사용됩니다	모델이 가끔 여러 출력을 내는 경우, 해당 작업은 실패하며 점검이 필요합니다
업그레이드 방법	직접 계속 사용하세요	새로운 스키마 버전을 통한 명시적 확장

필드를 버리는 것도 데이터 처리 결정입니다

"알려진 필드는 읽고, 다른 필드는 무시"가 실제로 사용된다면, 원본 결과와 필터링 동작을 기록해야 합니다. 그렇지 않으면 원본 데이터에 원래 항목이 없었는지, 아니면 인터페이스 계층이 제거했는지 구분하기 어렵습니다. 필드 폐기는 모델 프로토콜 미준수를 은폐하는 데도 사용되어서는 안 됩니다.

번역과 추출 사이에 경계를 남겨라.

문서 번역 출력과 구조화된 필드 출력은 서로 다른 계약입니다. OmniDoc를 사용해 문서를 처리할 때는 필드 리스트를 번역 후 검증에 사용할 수 있지만, 번역이 원활하다고 해서 추가적인 비즈니스 판단이나 신뢰 필드를 자동으로 수락할 수는 없습니다.

🎯 어떤 방법이 당신에게 맞나요?

내부 탐색 도구를 개발 중이라면

필드는 확장할 수 있지만, 표시 전에 반드시 미정의로 표시해야 합니다.

안정적인 전달 인터페이스를 유지한다면

additionalProperties: false를 사용해 각 레이어를 닫고 중첩된 객체의 경계를 별도로 정의하세요.

새로운 분야를 도입하고 싶다면

새로운 버전의 스키마를 출시할 때는 기존 버전을 몰래 완화하지 마세요.

만약 프로세스가 중복 필드를 버려야 한다면,

원본 결과와 필터링 동작을 기록해 나중에 쉽게 추적할 수 있도록 하세요.

❓ 자주 묻는 질문 (FAQ)

1. `additionalProperties: false`가 모든 수준을 커버할 수 있나요?

자동으로 덮어쓸 수 없습니다. 현재 객체에서 정의되지 않은 속성만 거부하며, 각 중첩된 객체는 허용되는 범위에 대해 명확히 명시되어야 합니다.

2. 다중 출력 필드가 반드시 해로운가요?

반드시 그렇지는 않지만, 하류에서 합의되지 않은 값을 기준으로 취급할 수 있으므로, 그 정의와 보정 상태를 먼저 확인해야 합니다.

3. 중복 필드를 거부할 때 무엇을 반환해야 하나요?

단일 JSON 오류가 아니라 알 수 없는 키명, 객체 경로(내부 계층 시 객체 경로), 프로토콜 버전을 포함해야 합니다.

4. 추가 필드는 그냥 무시할 수 있을까요?

네, 하지만 원시 결과와 필터링 동작은 기록되어야 하며, 모델은 프로토콜 비준수를 은폐하기 위해 이를 사용하지 않아야 합니다.

📝 요약

추가 필드는 유용해 보인다고 해서 표시할 수 없습니다; 먼저 인터페이스 경계에 합의한 후, 버전을 수락, 거부, 업그레이드할지 결정하세요. 각 계층에서 규칙을 명확히 하는 것은 과거 데이터를 하위 해석과 일치시키는 데 필수적입니다.

지금 경험해보세요: 원본 형식을 유지하면서 번역을 시작하려면 문서를 업로드하세요