JSON 샘플에서 JSON Schema를 생성하는 방법

유효한 JSON 샘플을 입력하면 관찰된 구조를 바탕으로 JSON Schema를 만들 수 있습니다. 제목은 선택 사항이고 비워 두면 Generated Schema가 기본 제목으로 사용됩니다.

샘플 구조를 스키마로 정리하는 이유

JSON 샘플을 바탕으로 JSON Schema를 만들고 싶다면, 실제 데이터 한 건을 입력해 구조를 읽히는 방식으로 시작할 수 있습니다. 이 도구는 입력 문자열을 JSON으로 해석한 다음 객체, 배열, 문자열, 숫자, 불리언, null처럼 확인된 값의 형태를 JSON Schema 표현으로 정리합니다. API 응답 일부, 설정 파일의 데이터, 메시지 본문처럼 필드와 값의 관계가 드러나는 자료가 적합합니다.

제목은 결과를 구분하고 싶을 때 선택적으로 지정하면 됩니다. 제목을 입력하지 않거나 빈칸으로 두면 Generated Schema가 기본 제목으로 사용됩니다. 다만 샘플에 보이지 않는 길이 제한, 숫자 범위, 업무 규칙까지 자동으로 알아내는 과정은 아니므로, 생성 뒤에 실제 요구 사항과 결과를 함께 살펴보는 편이 좋습니다. 샘플의 모양을 빠르게 출발점으로 정리하는 용도에 초점을 두면 결과를 더 올바르게 해석할 수 있습니다. JSON 한 건이 어떤 구조를 갖는지 먼저 정리한 뒤 필요한 장면에 맞춰 활용해 보세요. 이때 결과는 입력값에서 관찰된 형태를 보여 주는 자료로 이해해야 합니다. 실제 서비스에서 필요한 조건을 별도로 검토하면 샘플에 치우친 해석을 줄일 수 있습니다.

입력하고 생성 결과를 확인하는 순서

먼저 사용할 JSON을 준비합니다. 최상위 값은 객체나 배열일 수 있고, 문자열, 정수, 실수, 불리언, null 하나도 입력할 수 있습니다. 객체의 속성 이름과 문자열 값은 큰따옴표로 작성하고, 주석이나 JSON 바깥의 설명은 넣지 않습니다.
준비한 내용을 샘플 데이터 입력란에 문자열로 붙여 넣습니다. 주 입력이 비어 있으면 json, data, text, input, value, sample 가운데 먼저 사용할 수 있는 값이 선택될 수 있습니다. 그러나 실제로 사용할 샘플이 하나도 없으면 작업이 실패하므로, 비어 있지 않은 JSON 값을 제공해야 합니다.
결과를 알아보기 쉽게 하려면 제목 입력란에 이름을 적습니다. 이 단계는 선택 사항이며 제목을 생략하거나 빈 값으로 남겨도 Generated Schema가 적용됩니다. 입력한 제목과 기본 제목 중 어떤 값이 쓰이는지 확인하려면 제목 입력란이 비어 있는지 먼저 살펴보세요.
생성 기능을 실행합니다. JSON 해석이 끝나면 최상위 값의 종류에 맞는 구조가 출력됩니다. 객체에서는 각 구성원에 대응하는 속성 구조가 만들어지고, 입력에서 관찰된 구성원 이름은 필수 항목으로 표시됩니다. 추가 속성을 허용하지 않는 형태도 객체 구조에 함께 반영됩니다.
배열은 배열 자체와 항목 구조를 나누어 읽습니다. 빈 배열은 항목에 대한 제한이 없는 형태가 될 수 있으며, 서로 다른 항목 구조는 중복을 제거한 뒤 anyOf로 결합될 수 있습니다. 문자열은 값의 모양이 특정 패턴과 맞을 때 email, uuid, uri, ipv4, date-time, date 또는 time 형식을 받을 수 있으므로, 해당 형식이 붙었는지 결과에서 확인합니다.

출력에 담긴 의미와 확인할 경계

출력은 입력 샘플에서 관찰된 구조를 JSON Schema로 표현한 결과입니다. 최상위 객체를 넣으면 구성원별 속성 구조를 살펴볼 수 있고, 최상위 배열을 넣으면 배열과 항목의 관계를 확인할 수 있습니다. null은 null 유형으로, 불리언은 boolean 유형으로, 정수는 integer 유형으로, 실수는 number 유형으로 나타납니다. 문자열은 기본적으로 string 유형이며 특정 모양이 감지될 때 형식 정보가 추가될 수 있습니다. 결과에는 JSON Schema draft-07 식별자도 포함됩니다.

객체에서 필수 항목으로 보이는 이름은 해당 샘플에서 구성원이 관찰되었다는 뜻입니다. 다른 응답에서도 반드시 존재해야 한다는 업무 규칙이 그 표시 하나만으로 확정되는 것은 아닙니다. 배열 항목이 적으면 관찰된 사례가 결과에 큰 영향을 줄 수 있고, 빈 배열은 항목을 판단할 정보가 부족할 수 있습니다. 이메일이나 날짜처럼 보이는 문자열에 형식이 붙더라도 입력된 값의 모양을 바탕으로 한 분류로 읽어야 합니다.

생성된 결과를 실제 규칙과 대조하면서 샘플에 없던 길이, 숫자 범위, 조건을 따로 확인하세요. 필요한 제약이 빠져 있다면 결과를 해당 요구 사항에 맞게 직접 보완해야 합니다. 입력 크기도 살펴볼 대상입니다. 선택한 입력의 UTF-8 인코딩 크기가 1,000,000바이트를 초과하면 거부될 수 있으므로, 큰 자료는 필요한 범위를 나누어 검토하는 방법을 고려할 수 있습니다.

사용 예시

API 응답에 포함된 회원 필드의 구조를 문서화하려는 개발자가 객체 형태의 JSON 샘플을 준비합니다.

회원 목록 API 응답을 점검하려는 개발자가 {"id":101,"email":"user@example.com","active":true}를 샘플 입력에 붙여 넣고 제목 입력은 빈칸으로 둔 다음 생성 기능을 실행합니다.

최상위 값이 객체이므로 객체 구조가 출력됩니다. id, email, active에 대응하는 속성 구조와 세 이름을 담은 필수 항목 목록이 나타나며, 정수, 이메일처럼 보이는 문자열, 불리언에 해당하는 유형도 확인할 수 있습니다. 결과에는 draft-07 식별자가 포함되고 제목을 비워 둔 경우 기본 제목이 표시됩니다.

제한 사항

샘플에 나타나지 않은 길이, 숫자 범위, 업무 조건은 결과에 포함되지 않을 수 있으며, 선택한 입력의 UTF-8 인코딩 크기가 1,000,000바이트를 초과하면 거부될 수 있습니다.

자주 발생하는 오류

쉼표, 중괄호, 대괄호 또는 큰따옴표가 빠진 내용은 JSON으로 해석되지 않으며, 사용할 샘플이 없는 경우에도 작업이 실패합니다. 문장 부호와 따옴표를 다시 확인한 뒤 비어 있지 않은 유효한 JSON 값을 입력하고 생성을 다시 실행하세요.

자주 묻는 질문

JSON 객체를 입력하면 속성과 필수 항목도 만들어지나요?

객체를 입력하면 샘플에서 확인된 구성원마다 속성 구조가 만들어지고, 그 이름이 필수 항목으로 표시됩니다. 추가 속성을 허용하지 않는 형태도 추론되므로 실제 응답 규칙과 대조해 해석해야 합니다. 샘플에 한 번 나타난 이름과 업무상 반드시 필요한 이름은 같은 의미가 아닐 수 있습니다.

배열 샘플은 어떤 방식으로 표현되나요?

배열의 내용에 따라 항목 구조가 달라집니다. 빈 배열은 항목을 제한하지 않는 형태가 될 수 있고, 서로 다른 항목 구조는 중복을 제거한 뒤 anyOf로 합쳐질 수 있습니다. 따라서 배열에 넣은 사례의 구성 차이를 결과와 함께 살펴보는 것이 좋습니다.

잘못된 JSON을 넣으면 자동으로 고쳐 주나요?

잘못된 JSON은 스키마로 바뀌지 않으며, 사용할 샘플이 없는 경우에도 결과가 나오지 않습니다. 괄호와 쉼표, 큰따옴표를 고친 다음 해석 가능한 JSON 값을 입력해야 작업을 다시 진행할 수 있습니다. JSON 바깥에 적은 설명은 샘플에서 제거하세요.