BroadRouter
시작하기

JSON Schema(JSON 스키마)

업데이트

JSON Schema는 JSON으로 작성하는 어휘로, 타입, 필수 필드, 허용 값, 중첩 같은 JSON 데이터의 구조를 기술하고 검증합니다. 현재 버전은 2020-12입니다. LLM API는 이를 사용해 도구 파라미터와 구조화된 출력이 따라야 할 정확한 형태를 정의합니다.

다른 이름: JSON 스키마, 제이슨 스키마, JSON 스키마 검증, json_schema, JSON Schema draft 2020-12

“JSON으로 답해 줘”라는 프롬프트는 구조를 운에 맡깁니다. JSON Schema는 그 구조를 글로 적어 기계가 확인할 수 있게 합니다.

작동 방식

명세는 크게 두 부분입니다. Core는 “defines the basic foundation of JSON Schema”(번역: JSON Schema의 기본 토대를 정의한다)이고, Validation은 “defines the validation keywords”(번역: 검증 키워드를 정의한다)입니다. 현재 버전은 2020-12이고, 그 전 버전은 2019-09였습니다.

{
  "type": "object",
  "properties": {
    "name":    {"type": "string"},
    "amount":  {"type": "number", "minimum": 0},
    "currency": {"type": "string", "enum": ["SAR", "AED", "USD"]},
    "note":    {"type": ["string", "null"]}
  },
  "required": ["name", "amount", "currency", "note"],
  "additionalProperties": false
}

LLM API는 두 곳에서 스키마를 씁니다. 도구 정의는 인자를 설명하려고 parameters에 스키마를 넣습니다. 구조화된 출력은 response_format에 {"type": "json_schema", "json_schema": {...}} 형태로 스키마를 보내며, OpenAI는 이것이 “ensures the model will match your supplied JSON schema”(번역: 모델이 제공한 JSON 스키마와 일치하도록 보장한다)라고 설명합니다.

OpenAI의 strict 모드는 일부만 받아들입니다. 지원 스키마 섹션의 내용은 다음과 같습니다.

  • 타입: string, number, boolean, integer, object, array, enum, anyOf.
  • 루트는 객체여야 하며 anyOf를 쓸 수 없습니다.
  • additionalProperties: false이고 모든 필드가 required에 들어 있어야 합니다. 선택 필드로 만들려면 위의 note처럼 null을 허용하세요.
  • 객체 속성은 최대 5000개, 중첩은 최대 10단계, enum 값은 전체 합쳐 최대 1000개입니다.
  • 지원되지 않음: allOf, not, dependentRequired, dependentSchemas, if, then, else.

왜 중요한가

  • 검증. 모델을 안내하는 바로 그 스키마로 코드에서 응답을 검사합니다. 검사가 실패하면 그대로 되돌려 보낼 수 있는 정확한 오류가 나옵니다.
  • 이식성. strict 하위 집합에 맞춰 작성한 스키마는 모든 키워드를 쓴 스키마보다 더 많은 제공업체에서 작동합니다.
  • 토큰. 도구 정의에 들어간 스키마는 매 요청마다 입력으로 전송됩니다. 설명이 길면 턴마다 토큰 비용이 듭니다.

BroadNet Inference에서는

BroadNet의 API 레퍼런스는 GLM 5.3과 Qwen3.8 27B에 대해 도구 호출과 구조화된 출력을 문서화하지만, 어떤 스키마 키워드를 강제하는지는 밝히지 않습니다. 스키마는 위의 단순한 하위 집합으로 유지하고 모든 응답을 검증하세요. 스키마는 JSON Schema 생성기로 만들고, 응답은 LLM JSON 출력 검증기로 확인하세요. 전체 예시는 구조화된 출력 글에 있습니다. 다른 모델에서는 프롬프트로 JSON을 요청하고 응답을 검증하세요. JSON 모드는 BroadNet이 문서화하지 않았으므로 의존하기 전에 테스트하세요.

흔한 실수

  • allOf나 조건부 키워드를 쓰고 서버가 이를 강제한다고 가정하는 것.
  • strict 모드에서 null을 허용하는 대신 required에서 빼는 방식으로 필드를 선택 사항으로 만드는 것.

자주 묻는 질문

LLM API는 JSON Schema를 전부 지원하나요?

아니요. OpenAI는 일부만 지원합니다. 예를 들어 루트는 객체여야 하고, 모든 필드가 required여야 하며, additionalProperties는 false여야 하고, allOf, not, if/then/else 같은 키워드는 지원하지 않습니다.

JSON Schema와 JSON 모드는 무엇이 다른가요?

JSON 모드는 유효한 JSON만 약속합니다. JSON Schema는 그 JSON에 어떤 필드와 타입이 있어야 하는지를 모델과 검증기에 알려 줍니다.

BroadNet Inference에서 JSON Schema를 쓸 수 있나요?

둘 다 스키마를 쓰는 도구 파라미터와 구조화된 출력이 GLM 5.3과 Qwen3.8 27B에 문서화되어 있습니다. BroadNet은 어떤 스키마 키워드를 강제하는지 밝히지 않으므로 모든 응답을 검증하세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기