JSON Schema 조건부 필드 검수, 자동 모드의 필드가 왜 거절될까요

2026년 11월 기준, 공통 스키마가 자동 전용 필드를 막으면 그 제한을 빼고 결합 위치에 unevaluatedProperties: false를 둡니다.

자동 모드에서만 작업 ID를 받는 가상 API를 생각해 보겠습니다. 공통 스키마에 ID와 모드를 적고, 자동 모드 조건에 작업 ID를 넣었습니다. 그런데 공통 스키마에서 등록되지 않은 속성을 거절하면 자동 모드에 필요한 작업 ID까지 막힙니다.

공통 스키마에서 허용한 속성만 보면 어떻게 되나요?#

additionalProperties는 같은 스키마 객체의 properties와 patternProperties에서 처리하지 않은 속성에 적용합니다. 공통 스키마 안에서 이 값을 false로 두면 바깥 조건이 작업 ID를 허용해도 그 공통 스키마는 입력을 거절합니다. allOf는 각 하위 스키마를 모두 통과해야 하므로 다른 조건이 이 거절을 취소하지 않습니다. JSON Schema Core 추가 속성 규칙

공통 스키마의 제한을 제거하고 결합한 객체에 unevaluatedProperties: false를 둘 수 있습니다. 이 키워드는 같은 입력 객체에서 인접한 규칙과 그 하위 스키마가 성공적으로 평가한 속성을 모아, 남은 속성을 거절합니다. 예시에서 자동 모드일 때는 then이 작업 ID를 검사하고, 수동 모드에서는 그 분기가 적용되지 않아 작업 ID가 남은 속성이 됩니다. JSON Schema Core 미평가 속성 규칙

어떤 입력을 통과시켜야 하나요?#

두 스키마 모두 공통 ID와 모드, 자동 모드의 문자열 jobId를 요구합니다. 차이는 추가 속성 제한을 공통 스키마 내부에 두는지, 결합 위치에 두는지입니다.

다음은 결합 위치에서 제한한 예시입니다. 공통 스키마의 추가 속성 제한을 적용한 비교본에서는 결합 위치의 제한을 빼고 공통 스키마에 additionalProperties: false를 둡니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
    "base": {
      "properties": {
        "id": { "type": "string" },
        "mode": { "enum": ["manual", "auto"] }
      },
      "required": ["id", "mode"]
    }
  },
  "allOf": [
    { "$ref": "#/$defs/base" },
    {
      "if": {
        "properties": { "mode": { "const": "auto" } },
        "required": ["mode"]
      },
      "then": {
        "properties": { "jobId": { "type": "string" } },
        "required": ["jobId"]
      }
    }
  ],
  "unevaluatedProperties": false
}

대표 입력 {"id":"B","mode":"auto","jobId":"J"}는 공통 스키마에서 제한한 비교본에서 거절되고 결합 위치에서 제한하면 통과합니다. 인수표에는 모드, 필수 속성, 허용 속성, 기대 판정, 실제 판정을 기록합니다. 자동 모드의 정상 입력이 거절되거나 수동 모드에서 작업 ID가 통과하면 연동 인수를 보류하고 적용 스키마와 도구 버전을 확인합니다.

모드마다 스키마를 따로 두어도 되나요?#

모드가 적고 도구가 결합 검사를 지원하지 않으면, 각 모드의 전체 속성을 선언한 별도 스키마에서 추가 속성을 제한할 수 있습니다. 서로 다른 규칙의 공통 필드가 바뀔 때 두 스키마를 함께 갱신할 책임을 정합니다.

OpenAPI 3.2.1의 Schema Object는 JSON Schema Draft 2020-12의 어휘를 바탕으로 합니다. 사용하는 검증기와 생성 도구에서 같은 입력을 직접 시험합니다. 검증기 버전이나 스키마 방언이 바뀌면 표의 8개 입력을 다시 확인합니다. 부분 수정에서 값의 누락을 해석하는 기준은 SCM 부분 수정 검수, 항목과 전체의 검수 차이는 OpenAPI NDJSON 검수에서 다룹니다.

기준과 시험은 어디에서 확인했나요?#

• JSON Schema Core Draft 2020-12 2022년 6월 16일 공개본에서 속성·조건·결합 규칙을 확인했습니다.
• OpenAPI 3.2.1 Schema Object 2026년 9월 10일 공개본에서 기본 방언의 범위를 확인했습니다.
• 알파카랩스 업무 자동화·API 연동 서비스는 API 입력, 예외와 재처리, 운영 인수 조건의 협의 범위를 안내합니다.

공개 문서는 2026년 11월 13일 확인했습니다. 표는 합성 데이터와 로컬 검증기의 결과입니다. 실제 HTTP 요청, SDK 생성, 데이터 적재는 검수 범위에 포함하지 않았습니다.

자주 묻는 질문#

모드별 입력의 인수 기준을 정할 때#