프로젝트에 JSON 스키마가 필요한 정확한 순간을 알 수 있을 만큼 충분한 API 를 출하했습니다. 시작 시점이 아닙니다. 3 주가 지난 지금,두 번째 팀이 엔드포인트를 소비하기 시작하면 누군가가 잘못된 형식의 요청 본문을 보냅니다 null 모두가 항상 문자열이라고 가정하는 필드로 미끄러집니다. 갑자기 계약이 필요합니다 - 기계가 시행 할 수있는 형태로 "이 유효한 페이로드가 어떻게 생겼는지 말하는 문서." 그 문서는 JSON 스키마이며 이미 실제 데이터를 반환하는 엔드 포인트에서 손으로 쓰는 것은 백엔드 작업에서 더 지루한 작업 중 하나입니다.
TL;DR: JSON 샘플을 에 붙여넣습니다 JSON 스키마 생성기, Draft-07 또는 2020-12를 선택하고 스키마 유형을 추론합니다
required필드, 병합된 배열 항목 및 문자열 형식과 같습니다date-time그리고uuid. 그것은 당신의 브라우저에서 완전히 달립니다,그래서 토큰과 개인 자료를 나르는 페이로드는 페이지를 결코 떠나지 않습니다. 산출을 강한 첫번째 초안으로 대우하고십시오,그 후에 당신이서만 알고 있는 제약 조건으로 그것을 조이십시오.
저는 Toolz.dev 를 위해 이 도구를 만들었습니다. 왜냐하면 저는 손으로 같은 일을 계속했기 때문입니다: 응답체를 열고,눈을 가늘게 뜨고,그 모양을 스키마 절로 전사하는 것입니다. 반복적이고,반복적인 전사는 실수가 숨어있는 곳입니다. 이 가이드는 생성기가 하는 일,추론이 신뢰할 수 있는 곳,판단이 필요한 곳,생성된 스키마가 실제 검증 워크플로우에 어떻게 들어맞는지 설명합니다.
JSON 스키마란 무엇이며 데이터에서 JSON 스키마를 생성하는 이유는 무엇입니까?
JSON 스키마는 JSON의 구조를 설명하기 위한 어휘로 다음과 같이 유지됩니다 그 자체로 사양입니다 관례가 아닌. 스키마는 그 자체로 각 필드의 예상 유형, 필요한 필드, 중첩된 개체 및 배열의 모양, 그리고 -와 같은 키워드를 선언하는 JSON 문서입니다 pattern, enum, minimum, 그리고 format - 실제로 허용되는 값은 무엇입니까. 거의 모든 언어의 유효성 검사기는 스키마를 읽고 주어진 문서가 준수되는지 여부를 알려줍니다. JSON 세계가 서비스 경계를 넘어 이동하는 유형 시스템에 가장 가까운 것입니다.
처음부터 작성하는 것이 아니라 샘플에서 스키마를 생성하는 이유는 스키마의 대부분이 기계적이기 때문입니다. Walking a payload and recording "this is a string,this is a integer,this object has these keys" is exactly the kind of work a machine should do. 무슨 일이야 아닙니다 기계적 은 의미론적 계층이다: 그것을 아는 것 status 네 개의 문자열 중 하나일 수도 있습니다 age 부정적일 수는 없습니다 email 실제 주소 패턴과 일치해야 합니다. 생성은 기계적인 발판을 다루므로 중요한 제약 조건에 주의를 기울일 수 있습니다. 빈 파일에서 시작하여 모든 필드를 기억하기를 바라는 대신 이미 현실과 일치하는 문서에서 시작하여 규칙을 추가합니다.
신뢰 차원도 있습니다. 스키마를 손으로 입력하면,여러분이 무엇을 인코딩하는 믿다 엔드포인트가 반환됩니다. 신념은 현실에서 표류합니다. 필드가 추가되고 정수가 무효화되며 단일 개체를 반환한 엔드포인트가 배열을 반환하기 시작합니다. 실제 응답에서 생성된 스키마는 캡처한 날 서비스가 실제로 보낸 내용에 고정됩니다. 해당 앵커는 유효성 검사가 스테이징에서 통과하고 프로덕션에서 실패하는 이유를 디버깅할 때 큰 가치가 있습니다.
생성기가 스키마를 추론하는 방법
엔진은 JSON 을 구문 분석하고 값을 재귀적으로 걸어 구조의 모든 부분에 대해 스키마 노드를 방출합니다. 너무 느슨한 스키마는 쓸모가 없고 너무 엄격한 스키마는 유효한 데이터를 거부하기 때문에 규칙은 의도적으로 보수적입니다.
스칼라의 경우 구별됩니다 integer 부터 number - 42 된다 integer, 4.2 된다 number - 그 구별은 유효성 검사기와 스키마를 읽는 모든 사람에게 의미가 있기 때문입니다. 부울과 null 자신의 타입에 맵. 문자열이 된다 type: string그리고 포맷 감지가 켜져 있으면 엔진은 잘 알려진 패턴 세트에 대해 값을 확인하고 태그를 지정합니다: date-time, date, time, email, uri, uuid, 그리고 ipv4.
객체의 경우 모든 키를 기록하고 각 값에 대한 스키마를 추론합니다 required 추론이 활성화됩니다 - 해당 위치의 모든 개체에 존재할 때 필요한 키를 표시합니다. 모든 키를 의미하는 단일 개체의 경우; 흥미로운 경우는 배열입니다.
객체 배열의 경우 생성기는 순진한 걷기보다 더 유용한 작업을 수행합니다. 각 요소에 대해 별도의 스키마를 내보내거나 스프롤링을 내보내는 대신 anyOf 거의 동일한 모양으로 배열의 모든 개체를 하나로 병합합니다 items 단일 요소를 설명하는 스키마. 모든 요소에 존재하는 키가 필요합니다; 일부 요소에만 존재하는 키는 선택 사항으로 남습니다. 이는 실제 API 컬렉션의 동작 방식을 반영합니다: 대부분의 레코드가 다음을 수행하는 페이지 매겨진 목록입니다 avatarUrl 하지만 몇 개는 그렇지 않습니다. 병합된 스키마는 "these 필드를 항상 표시하고,이들은 때때로 appear"를 읽을 수 있는 하나의 정의에서 볼 수 있습니다. 내장된 샘플에서 이를 볼 수 있습니다 members 배열에는 두 개의 개체가 있습니다. 하나는 a입니다 active 필드와 -가 없는 필드 및 생성된 항목 스키마 표시입니다 id 그리고 role 필수이지만 떠납니다 active 선택사항.
혼합된 스칼라 배열의 경우 엔진은 요소 유형을 단일로 축소합니다 type 배열 - ["integer", "string", "boolean"] - 장황한 합집합이 아니라. 객체와 객체가 아닌 모양이 진정으로 하나의 배열로 혼합되면 다시 돌아갑니다 anyOf"에 대한 올바른 JSON 스키마 구성입니다. 이러한 대안 중 하나입니다."
JSON 스키마 생성기를 사용하는 방법
1 단계: 대표 샘플을 붙여 넣습니다
API 응답, 정착물, 윤곽 파일, 또는 webhook 몸에서 떨어지십시오.정확도를 위해 할 수 있는 단 하나 가장 중요한 것은 a를 풀칠하기 위한 것입니다 대표 샘플. 실제 응답에서 여러 레코드가 있는 경우 배열 안에 모두 포함하십시오. 생성기가 이를 병합하고 선택성을 올바르게 추론합니다. 단일 레코드 샘플은 엔진에 표시되는 모든 필드가 항상 존재한다고 알려주며 이는 종종 잘못된 것입니다. 내장 샘플을 먼저 로드하여 중첩된 개체,개체 배열 및 형식화된 문자열이 자신의 것을 붙여넣기 전에 어떻게 처리되는지 확인합니다.
2 단계: 방언을 선택한다
유효성 검사 라이브러리 전체에서 가장 광범위한 호환성을 보려면 Draft-07 을 선택하고,현재 사양의 경우 2020-12 를 선택하십시오. 도구가 올바른 내용을 작성합니다 $schema 루트 위에 식별자를 넣어서 유효성 검사기가 올바른 규칙을 적용합니다. 이 생성기가 생성하는 객체와 배열 모양의 경우 구조적 출력은 두 방언 모두에서 동일합니다; 눈에 보이는 차이는 식별자입니다. 툴링이 지원하는 것이 무엇인지 확실하지 않은 경우 Draft-07 은 안전한 기본값입니다 - 모든 버전 중에서 가장 광범위한 라이브러리 지원을 제공합니다.
3 단계: 옵션을 설정하십시오
추가 a title 스키마 자체 문서화를 원하는 경우. 방출 여부를 결정합니다 required - 대부분의 경우 원하는데 초기 탐색 중에는 좀 더 느슨한 스키마를 선호할 수 있습니다. false positives 가 보이지 않는 한 형식 감지를 계속 켜두십시오. 그리고 strict mode (additionalProperties: false) 스키마가 구성 파일이나 요청 본문과 같이 완전히 제어하는 것을 보호하고 예상치 못한 키가 무시되기보다는 거부되기를 원하는 경우.
4 단계: 생성, 검토 및 내보내기
생성 을 누른 다음 출력을 비판적으로 읽으십시오. 그 내용을 확인하십시오 required 인텐트와 일치하고,그 정수 대 숫자가 올바르게 나왔으며,검출된 형식이 우연이 아니라 정확하다는 것입니다. 제대로 보이면 스키마를 복사하거나 a 로 다운로드하십시오 .json 유효성 검사기나 저장소에 파일을 삭제할 준비가 되었습니다.
작업된 예
이 응답을 가설에서 생각해 보십시오 /projects 끝점:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
생성기는 스키마를 생성합니다 id 는 로 문자열이다 format: "uuid", createdAt 는 로 문자열이다 format: "date-time", score 는 a number (소수 때문에 정수가 아님), 그리고 members 는 배열입니다 items 스키마가 필요합니다 id 그리고 role 하지만 아닙니다 active. 마지막 세부 사항은 보상입니다: 두 명의 예제 구성원으로부터 이를 정확하게 추론했습니다 active 는 선택 사항입니다. 큰 페이로드에 걸쳐 손으로 그 추론을하는 것은 정확하게 발전기가 제거하는 조심스럽고 지루한 작업의 종류입니다.
추론이 끝나고 판단이 시작되는 곳
나는 한계에 대해 직접적으로 말하고 싶다,왜냐하면 생산에 바로 넘겨지는 생성된 스키마는 실수이기 때문이다. 추론은 타입과 구조를 본다; 그것은 의도를 볼 수 없다.
그것을 알 수 없습니다 role 의 열거형입니다 owner, editor, 그리고 viewer - 샘플에서만 알 수 있습니다 role 는 문자열입니다. 그것은 그것을 알 수 없습니다 score 범위는 0에서 5까지입니다 name 최대 길이를 갖거나 UUID처럼 보이는 코드가 실제로는 일반 문자열로 유지되어야 하는 불투명한 식별자라고 추론합니다 required 존재부터,그래서 당신의 표본에서 나타나는 우연히 선택적인 분야는 당신이 그것을 정정할 때까지 필수이라고 표를 할 것입니다. 그리고 당신이 그것을 주는 자료에서 작동합니다: 당신의 표본이 결코 a 를 포함하지 않는 경우에 null 널링 가능한 필드의 경우 스키마는 필드가 널이 될 수 있다는 것을 알지 못합니다.
올바른 정신 모델은 발판입니다. 생성기는 프레임을 정확하게 구축합니다 - 모든 필드,유형, 중첩,배열 모양,존재 기반 필수 목록. 그런 다음 의미 제약 조건을 추가합니다: 열거형,패턴, 숫자 경계 및 엔진이 하나의 값에서 볼 수 없었던 모든 형식. 이것은 지루한 구조적 전사가 이미 완료되고 정확하기 때문에 아무것도 없는 상태에서 시작하는 것보다 더 빠르고 오류 발생 가능성이 적습니다.
Draft-07 대 2020-12: 어떤 것을 선택해야 합니까?
| 고려사항 | 초안-07 | 2020-12 |
|---|---|---|
| 도서관 지원 | 가장 넓은; 거의 모든 곳에서 지원됩니다 | 성장; 검증기를 확인하세요 |
| 상태 | 널리 배포되고 안정적입니다 | 현재 명세 |
$schema 값 |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| 배열 항목 키워드 | items 단일 항목 스키마의 경우 |
items / prefixItems 튜플을 위해 분할합니다 |
| 가장 좋은 때 | 최대 호환성 문제 | 최신 사양 기능을 원합니다 |
이 도구가 생성하는 스키마의 경우 - 개체,필수 목록,단일 항목 모양의 배열 - 두 방언 모두 동일한 구조를 표현합니다. 실질적인 결정은 유효성 검사 라이브러리가 지원하는 것에 달려 있습니다. 스키마를 설정된 스택에 배선하는 경우 유효성 검사기 문서 버전과 일치하십시오. 새로 시작하고 제약 조건이 없다면 Draft-07 은 타의 추종을 불허하는 생태계 지원을위한 실용적인 선택으로 남아 있습니다.
일반적인 사용 사례
기존 API 문서화. 스키마가 없는 엔드포인트를 상속할 때 실제 응답에서 하나를 생성하면 몇 초 만에 정확한 시작 문서가 제공됩니다. 그런 다음 게시된 계약으로 구체화합니다. 이는 클라이언트 코드에 대한 생성 유형과 자연스럽게 쌍을 이룹니다. 동일한 샘플이 공급될 수 있습니다 JSON에서 타이프스크립트 도구 그래서 서버 계약 및 클라이언트 유형은 진실의 동일한 소스에서 온다.
요청 기관을 검증합니다. 제어하는 요청 본문의 경우 유효한 예제에서 스키마를 생성하고,예상치 못한 키를 거부하기 위해 엄격한 모드를 켜고,엔넘과 엔드포인트가 시행하는 범위를 추가합니다. 이제 잘못된 형식의 요청은 핸들러 깊은 곳에서 혼란스러운 실패를 일으키는 대신 명확한 유효성 검사 오류로 가장자리에서 실패합니다.
구성 파일 유효성 검사. JSON config 를 읽는 응용 프로그램은 스키마에서 엄청난 이점을 얻습니다. 알려진 좋은 config 에서 하나를 생성하고 조이고 시작 시 유효성을 검사하여 config 키의 오타가 기능을 자동으로 비활성화하는 대신 크게 실패합니다.
테스트 및 비품. 스키마는 테스트 자산으로도 사용됩니다. 모양에서 표류하는 고정 장치가 오해의 소지가있는 녹색 테스트를 생성하기 전에 잡히도록 CI 에서 고정 장치를 검증하십시오.
서비스 간 계약 테스트. 두 서비스가 페이로드에 동의하면 공유 스키마가 계약입니다. 실제 메시지에서 이를 생성하고 개선하면 두 팀 모두 독립적으로 검증할 수 있는 문서가 제공됩니다.
개인 정보 보호: 이것이 브라우저에서 실행되는 이유
API 샘플은 개발자가 처리하는 가장 민감한 텍스트 중 일부입니다. 일상적으로 액세스 토큰,세션 식별자,이메일 주소,내부 레코드 ID 및 때로는 임의의 웹 양식에 붙여 넣지 말아야 할 개인 데이터가 포함되어 있습니다. 이것이 바로 JSON 스키마 생성기가 모든 작업 클라이언트 측을 수행하는 이유입니다. 구문 분석,추론 및 직렬화는 브라우저의 JavaScript 에서 발생합니다. 서버에 업로드,로그래밍 또는 저장되는 것은 없습니다. 생성하는 동안 네트워크 탭을 열거나 인터넷에서 연결을 끊어도 이를 확인할 수 있습니다. 도구는 여전히 작동합니다. 내 페이로드를 다른 사람에게 보내는 도구를 사용하지 않을 것이기 때문에 나는 이것에 관심이 있습니다's 서버,그리고 나는 당신에게 어느 쪽도 요청하지 않을 것입니다. 동일한 원리가 Toolz.dev 전체를 통해 실행되며,이는 내가 길게 주장하는 것입니다 온라인 도구의 데이터 개인 정보 보호 쓰기.
더 넓은 JSON 툴킷에 어떻게 맞는지
스키마는 더 큰 JSON 워크플로우의 하나의 아티팩트입니다. 스키마를 생성하기 전에 깨끗하고 유효한 입력을 갖는 것이 도움이 됩니다 JSON 포맷터 는 형식화하고 페이로드를 유효성 검사합니다 그래서 당신은 발전기에 잘못된 형식의 텍스트를 공급하지 않습니다. 스키마가 후,당신은 종종 당신의 응용 프로그램 코드에 대한 유형을 원하는,어디에 있습니다 JSON에서 타이프스크립트 들어옵니다. 그리고 만약 여러분의 파이프라인이 형식들 사이에서 움직인다면,그 JSON에서 YAML로 컨버터는 많은 config 와 CI 시스템이 기대하는 변환을 처리합니다. 나는이 조각들이 에 어떻게 연결되는지에 대해 썼다 JSON 도구에 대한 궁극적 인 가이드그리고 더 넓은 키트를 조립하는 것에 대해 설명합니다 웹 개발자 툴킷 개요. 연결된 툴킷의 요점은 단일 샘플이 브라우저를 떠나지 않고도 스키마,유형, 형식 변환 등 여러 도구를 통해 흐를 수 있다는 것입니다.
자주 묻는 질문
json에서 json 스키마를 생성하려면 어떻게 해야 합니까?
JSON 을 편집기에 붙여넣고 Draft-07 또는 2020-12 를 선택한 다음 Generate 를 누릅니다. 이 도구는 모든 필드의 유형을 추론하고 필요한 키를 추출하며 유효성 검사기에 바로 복사할 수 있는 스키마를 출력하지 않습니다. 업로드 - 추론은 브라우저에서 완전히 실행됩니다.
Draft-07과 2020-12의 차이점은 무엇입니까?
그들은 JSON 스키마 사양의 두 가지 버전입니다. 초안-07 은 라이브러리 전반에 걸쳐 가장 광범위한 지원을하고 안전한 기본값입니다. 2020-12 는 현재 릴리스이며,다른 것들 중에서 배열과 하위 스키마가 표현되는 방식을 변경합니다. 객체와 배열 모양의 경우이 도구는 구조를 생성합니다 동일; 눈에 보이는 주요 차이점은 $schema 식별자.
도구는 어떤 필드가 필요한지 어떻게 결정합니까?
생성기가 보는 모든 객체에 표시되면 키가 필수로 표시됩니다. 모든 키를 의미하는 단일 객체의 경우, 객체의 배열에 대해 모든 요소에 존재하는 키를 의미합니다. 일부 레코드에만 표시되는 키는 필수 항목에서 제외되어 API에서 선택적 필드를 생략하는 방식을 미러링합니다. 필수 필드 감지를 완전히 끌 수 있습니다.
객체 배열은 어떻게 됩니까?
객체들은 하나로 합쳐집니다 items 단일 요소를 설명하는 스키마이며 속성은 그 배열로 입력됩니다. 모든 요소에 존재하는 키는 필수가 됩니다; 일부에만 존재하는 키는 선택 사항입니다. 이렇게 하면 큰 요소를 생성하는 대신 스키마를 읽을 수 있게 유지됩니다 anyOf 거의 동일한 모양.
어떤 문자열 형식을 감지합니까?
그것은 인식합니다 date-time, date, time, email, uri, uuid, 그리고 ipv4 문자열을 사용하고 일치하는 항목을 추가합니다 format 키워드. 감지는 단일 샘플에서 가장 좋은 방법이므로 결과를 검토하십시오. 우연히 UUID처럼 보이는 코드가 하나로 태그됩니다. 일반 문자열 유형을 선호하는 경우 형식 감지를 비활성화할 수 있습니다.
단일 샘플에서 스키마를 생성할 수 있습니까?
예,하지만 하나의 샘플은 하나의 가능한 모양만 보여줍니다. 샘플의 숫자 인 필드는 null 이거나 다른 곳에서 문자열 일 수 있으며 우연히 존재하는 선택적 필드는 필수로 표시됩니다. 샘플을 더 대표 할수록 - 이상적으로는 여러 개의 실제 레코드 - 추론 된 유형과 필수 목록이 더 정확합니다.
생성된 스키마가 프로덕션 검증을 위해 준비되어 있습니까?
완성된 문서가 아닌 강력한 시작점으로 취급합니다. 추론은 유형,구조 및 필요한 필드를 정확하게 캡처하지만 의미 제약 조건 - 열거형,문자열 패턴,숫자 최소값 및 최대값,하나의 값에서 볼 수 없는 형식 - 은 여전히 손으로 생성하면 지루한 발판을 제거하므로 해당 규칙에 집중할 수 있습니다.
내 json이 서버에 업로드되었습니까?
아니요. 전체 추론 엔진은 브라우저에서 JavaScript 로 실행됩니다. 전송,로그 또는 저장되는 것은 없습니다. 생성하는 동안 네트워크 탭을 보거나 인터넷에서 연결을 끊으면 도구를 계속 작동시켜 확인할 수 있습니다.
