JSON Schema 참조 경로 검수, 같은 $ref가 다른 규칙을 읽는 이유
JSON Schema의 같은 $ref도 기준 $id에 따라 다른 규칙을 가리킵니다. 가상 입력으로 최종 URI와 적용 스키마를 대조하고 데이터 위반·참조 실패·자동 조회 범위를 인수표로 구분합니다.
이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스
JSON Schema 참조 검수는 기준 URI와 실제 등록 규칙을 대조합니다. 2026-11-21 확인 기준, 참조 URL이 있어도 자동 다운로드를 뜻하지 않습니다.
같은 입력과 common.json을 넘겼는데 개발 환경에서는 통과하고 다른 환경에서는 실패할 수 있습니다. 공통 파일의 이름만 확인하면 참조가 어느 주소로 해석됐는지, 그 주소에 어떤 규칙이 등록됐는지를 놓칩니다.
이 글은 API·업무 에이전트의 스키마 묶음을 인수하는 담당자를 위한 가상 검수 예시입니다. 기준 주소·참조 표현만 바꾸고 같은 수량을 검증합니다. 실제 고객 장애나 특정 MCP 제품의 동작을 재현한 글은 아닙니다.
같은 $ref가 왜 다른 규칙을 가리킵니까?#
상대 참조는 현재 기준 URI에 맞춰 해석됩니다. $id가 그 기준을 정하면 같은 common.json도 v1과 v2의 서로 다른 URI를 가리킬 수 있습니다. JSON Schema Core의 식별·참조 규칙이 공식 근거입니다.
예시 루트 스키마는 아래와 같습니다. 같은 JSON을 로컬 파일에서 읽었다는 이유만으로 $ref를 그 파일 옆에서 찾는다고 가정하면 안 됩니다. 이번 예시의 기준은 명시한 $id입니다.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.org/contracts/v1/order.json",
"$ref": "common.json"
}
기준 URI에서 마지막 order.json을 상대 참조 common.json으로 바꾸면 https://example.org/contracts/v1/common.json이 됩니다. 파일을 옮기는 작업과 $id를 바꾸는 작업은 구분해 검수해야 합니다.
참조가 해석되지만 데이터가 거절되면 적용 규칙과 입력을 대조합니다. 규칙을 찾지 못하면 배포한 스키마 묶음과 등록 URI부터 확인합니다. 날짜 문자열의 검사 옵션은 JSON Schema 날짜 형식 검수, 기본값 적용은 MCP 입력 기본값 검수의 별도 문제입니다.
기준 주소를 바꾸면 같은 수량의 판정이 어떻게 달라집니까?#
가상 입력은 모두 {"quantity": 5}입니다. v1 공통 규칙과 루트 /common.json은 수량 최소 1, 나머지 등록 규칙은 최소 10으로 만들었습니다. 이 숫자는 비교를 위한 설계 입력이며 실제 발주·재고 정책이 아닙니다.
‘v1 기준’은 위 코드, ‘v2 기준’은 $id의 v1을 v2로 바꾼 조건입니다. ‘끝에 슬래시’는 $id를 /contracts/v1/order/로 바꿉니다. 나머지는 v1 기준에서 참조를 바꾸되 절대 URI 행만 v2 기준을 사용합니다. 모든 완전한 주소의 앞부분은 https://example.org이며 표에서는 경로만 표시합니다.
| 기준·참조 변경 | 해석된 URI의 경로 | quantity 5 판정 |
|---|---|---|
| v1 기준 | /contracts/v1/common.json | 통과: 최소 1 |
| v2 기준 | /contracts/v2/common.json | 위반: 최소 10 |
| 끝에 슬래시 | /contracts/v1/order/common.json | 위반: 최소 10 |
| 슬래시로 시작 | /common.json | 통과: 최소 1 |
| 절대 URI 참조 | /contracts/v1/common.json | 통과: 최소 1 |
| 미등록 참조 | /contracts/v1/missing.json | 참조 실패 |
| 기준 URI 없음 | common.json | 참조 실패 |
| 상위 경로 참조 | /contracts/common.json | 위반: 최소 10 |
‘슬래시로 시작’은 $ref를 /common.json으로, ‘상위 경로 참조’는 ../common.json으로 바꿨습니다. ‘절대 URI 참조’에는 v1 공통 규칙의 완전한 URI를 넣었습니다. 기준 주소 끝의 슬래시와 참조 앞의 슬래시는 각각 다른 경로를 만드므로 문자열을 생략하지 않고 인수 기록에 남겨야 합니다.
미등록 행은 missing.json이 해석된 주소에 규칙이 없는 경우입니다. 기준 URI 없음 행은 $id 없이 Python dict를 직접 넘기고 외부 기준 URI도 주지 않았습니다. 기준 URI를 호출자가 따로 제공하는 구현까지 모두 실패한다는 뜻은 아닙니다.
URL을 적으면 검증기가 알아서 규칙을 내려받습니까?#
URI 식별과 네트워크 조회는 별개입니다. 이 예시는 규칙을 메모리 Registry에 미리 등록했고, 없는 URI를 조회하면 실패하도록 설정했습니다. 실제 HTTP 요청은 하지 않았습니다.
python-jsonschema 4.26.0의 참조 처리 문서는 Registry를 검증기에 전달하는 방식과 자동 HTTP 조회를 위한 별도 구성을 설명합니다. 이번 실행도 Resource.from_contents로 만든 리소스를 등록하고 Draft202012Validator에 같은 Registry를 전달했습니다. 참조 해석 결과와 데이터 판정을 각각 대조했습니다.
최신 연결 맥락으로 확인한 MCP 2026-07-28의 참조 해석 규칙은 네트워크 URI로 해석되는 $ref를 자동으로 내려받지 못하게 규정합니다. 미해결 외부 참조 때문에 검증할 수 없는 스키마는 무조건 허용으로 취급하기보다 거절하도록 권고합니다. 예시의 오프라인 등록 시험을 실제 MCP 클라이언트의 지원 보장으로 해석하면 안 됩니다.
참조 실패를 일반 데이터 위반과 같은 목록에 넣으면 원인을 잘못 설명할 수 있습니다. 수량이 최소값에 못 미친 경우와 검증 규칙 자체를 찾지 못한 경우를 운영 결과에서 구분합니다.
참조 인수표에 무엇을 고정해야 합니까?#
스키마 판본, 원본 $id·$ref, 해석된 URI, 등록한 리소스 본문과 개정 식별자, 입력·예상 결과를 함께 남깁니다. URI가 같아도 그 주소에 등록한 본문을 바꾸면 판정이 달라질 수 있습니다. 절대 URI로 적는 것만으로 규칙의 버전까지 고정되지는 않습니다.
외부 조회를 허용한 배포라면 조회 조건과 실패 처리도 인수 범위입니다. 이번 가상 시험은 오프라인 Registry만 사용했습니다. 중첩된 $id·재귀적인 $dynamicRef·운영 네트워크 조회는 별도 표본이 필요합니다. 조건부 필드의 허용 범위는 JSON Schema 결합 속성 검수와 구별합니다.
공식 기준은 2022-06-16 공개된 JSON Schema 2020-12 Core이며 문서 형식은 Internet-Draft입니다. 확정 RFC라고 부르지 않습니다. 구현 문서의 판본은 4.26.0, MCP 연결 근거의 판본은 2026-07-28이며 모두 2026-11-21 확인했습니다. 다음 검토는 2026-12-21 또는 판본·엔진·리소스 묶음 변경 시 진행합니다.
알파카랩스는 AX 구축·운영 서비스에서 시스템 구축과 운영 검수 범위를 설명합니다. 이는 자사 제공 방식의 자기표기이며 특정 참조 검증 기능의 납품 실적이나 성과 보장이 아닙니다. 운영 주체는 알파카랩스이며 아래 상담으로 연결될 수 있습니다.
JSON Schema 참조 경로 검수 FAQ#
$ref는 파일 이름으로만 해석합니까?
현재 기준 URI에 맞춰 URI 참조를 해석합니다. 같은 파일 이름도 기준 경로가 다르면 다른 스키마를 가리킬 수 있습니다.
$id가 없으면 상대 참조가 항상 실패합니까?
호출자가 외부 기준 URI를 제공하는 방식도 있으므로 항상 실패한다고 단정할 수 없습니다. 표의 실패는 $id와 외부 기준 URI가 없는 dict 직접 전달 조건입니다.
절대 URI로 바꾸면 검수 결과가 고정됩니까?
주소 해석의 모호함은 줄일 수 있습니다. 그 URI에 등록한 규칙 본문이 바뀌는 상황까지 막지는 않으므로 개정 식별자와 묶음을 함께 보관해야 합니다.
참조 실패는 입력 데이터가 틀렸다는 뜻입니까?
규칙을 찾지 못해 검증을 마치지 못한 상태입니다. 적용 규칙을 찾은 뒤 최소값 등을 위반한 데이터와 구분해 처리해야 합니다.
로컬 실행 통과로 MCP 도구의 호환성을 보장합니까?
이번 결과는 지정한 Python 검증기와 오프라인 리소스 묶음의 결과입니다. 실제 클라이언트·서버의 판본과 참조 지원·배포 구성을 별도로 대조해야 합니다.
스키마 참조 인수표 초안을 정리합니다#
스키마 참조 인수표 초안을 정리합니다
첫 범위 협의에서 비식별 스키마·기준 URI·참조 묶음을 대조해 스키마 참조 인수표 초안을 정리합니다. 소요 시간은 판본·배포 환경·참조 범위를 확인한 뒤 안내합니다.
스키마 참조 인수표 초안 협의