JSON Schema 동반 필드 검수dependentRequired 단방향JSON Schema 필수 키 null

JSON Schema 동반 필드 검수, 예외 코드에 근거 키를 요구하는 법

JSON Schema dependentRequired로 예외 코드가 있을 때 검토 티켓 키를 요구합니다. 단방향 의존성과 null·빈 문자열의 차이를 가상 입력으로 검수합니다.

이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스

발행 ·알파카랩스

예외 코드가 있을 때만 검토 티켓을 요구하려면 dependentRequired를 씁니다. null과 빈 문자열은 값 제약으로 검사합니다.

2026년 11월 16일 확인 기준입니다. 문서 처리 에이전트가 정상 결과에는 기존 검토 티켓을 붙일 수 있고, 예외 코드를 내보낼 때는 반드시 검토 티켓을 붙인다고 가정합니다. 두 방향의 정책을 나누면 정상 결과의 기존 참조를 유지하면서 예외의 근거 누락을 잡을 수 있습니다.

키가 있을 때만 다른 키를 요구하려면?#

dependentRequired는 같은 객체에서 지정 키가 있으면 함께 있어야 할 키를 검사합니다. 예를 들어 exceptionCode가 오면 reviewTicketId를 요구합니다. 검토 티켓만 있어도 허용하는 정책이라면 역방향 규칙을 추가하지 않습니다. JSON Schema Validation 6.5.4 · 단방향과 역방향 예시

가상 예시는 다음 스키마를 사용합니다. type은 값이 문자열인지, minLength는 문자열 길이가 최소 1인지 검사합니다.

{
  "type": "object",
  "properties": {
    "exceptionCode": { "type": "string", "minLength": 1 },
    "reviewTicketId": { "type": "string", "minLength": 1 }
  },
  "dependentRequired": {
    "exceptionCode": ["reviewTicketId"]
  }
}

누락과 null, 빈 문자열을 어떻게 검수하나요?#

키의 존재와 값의 유효성을 각각 대조합니다. 예외 코드의 값이 null이어도 키는 존재합니다. 따라서 티켓을 빠뜨리면 동반 키 위반과 코드의 타입 위반이 함께 발생합니다. JSON Schema Validation의 type과 required

가상 입력관찰할 조건검증 결과
둘 다 빠짐선택 키가 모두 없음적합
티켓만 있음예외 코드가 없음적합
둘 다 유효예외 코드와 티켓이 문자열적합
예외 코드만 있음티켓 키 빠짐dependentRequired
예외 코드가 null코드가 null이고 티켓 키도 빠짐dependentRequired와 type
티켓이 빈 문자열두 키 존재, 티켓 길이 0minLength
티켓이 null두 키 존재, 티켓이 nulltype
티켓만 있고 역방향 추가티켓 쪽에도 반대 키 요구dependentRequired
알파카랩스가 2026년 11월 16일 Python jsonschema 4.26.0으로 가상 입력 8건을 검증한 결과입니다. 마지막 행에서만 역방향 규칙을 추가했습니다.

예외 코드의 값에 따라 다르게 요구하려면?#

키가 있고 값이 특정 코드일 때만 티켓을 요구한다면 if와 then으로 조건을 나눕니다. if에 properties로 값만 검사하면 키가 없을 때도 그 부분은 적합할 수 있습니다. 키가 반드시 있는 경우에만 분기하려면 if에 그 키의 required도 넣습니다. JSON Schema 조건부 검증 안내

최소 길이 1은 공백만 있는 문자열도 허용합니다. 공백만 있는 값을 막으려면 별도 값 규칙을 정합니다. 티켓이 실제로 존재하고 해당 예외에 속하는지는 저장소의 레코드와 대조합니다. 모드마다 허용할 속성의 범위는 JSON Schema 미평가 속성 검수에서 다룹니다.

어떤 버전과 검증 범위를 확인했나요?#

2026년 11월 16일에 2022년 6월 16일자 JSON Schema Draft 2020-12 Validation 문서와 2026년 9월 10일 공개된 OpenAPI 3.2.1을 확인했습니다. OpenAPI 3.2.1의 기본 Schema Object는 Draft 2020-12를 바탕으로 합니다. 연동에 적용할 때는 사용하는 스키마 방언과 실제 요청 검증기에 같은 표본을 넣어 결과를 확인합니다. OpenAPI 3.2.1 Schema Object

알파카랩스는 업무 자동화 공개 서비스에서 입력과 계산 규칙, 누락·실패의 후속 확인, 운영 인수 조건을 협의한다고 안내합니다. 글의 표는 동반 필드를 합의할 때 쓸 설계 예시입니다. 업무 자동화·API 연동 시스템 개발

자주 묻는 질문#

dependentRequired는 양방향인가요?

한 방향씩 적용됩니다. 두 키를 항상 함께 요구하려면 각 키에서 상대 키를 요구하는 규칙을 각각 씁니다.

티켓 값이 null이면 동반 키 위반인가요?

티켓 키가 존재하므로 동반 키 조건을 만족합니다. 예시 스키마에서는 문자열 타입 검사로 null을 거절합니다.

정상 결과에 티켓만 보내도 되나요?

예외 코드에서 티켓으로만 의존성을 설정하면 티켓만 있어도 적합합니다. 티켓 값이 있을 때 적용할 타입과 길이 제약은 지켜야 합니다.

예외 코드가 없는 요청에도 검토 티켓이 필요한가요?

모든 요청에서 필수라면 객체의 required에 검토 티켓 키를 넣습니다. 예외 코드가 있을 때만 필수라면 dependentRequired를 사용합니다.

OpenAPI 문서에 쓰면 실제 요청도 차단되나요?

요청을 검사하는 서버나 게이트웨이의 설정에 따라 달라집니다. 계약 문서와 실제 요청 검증 단계에 같은 입력을 넣어 오류 응답을 비교합니다.

동반 필드 인수표를 어떻게 준비하나요?#

예외가 없는 요청, 예외 코드만 있는 요청, 근거 키에 빈 값이 있는 요청의 비식별 예시를 준비합니다. 각 행에 기대 오류와 발생 지점을 적으면 구현과 API 계약을 같은 조건으로 확인할 수 있습니다. API 연동 개발 가이드

동반 필드의 인수 기준을 정리합니다

첫 범위 협의에서 비식별 요청 표본과 기대 판정으로 동반 필드 인수표 초안을 정리합니다. 소요 시간은 검증 환경과 표본 범위를 확인한 뒤 협의합니다.

동반 필드 인수표 초안 협의