JSON(JavaScript Object Notation)은 REST API 및 웹 서비스의 데이터 교환을 위한 사실상의 표준이 되었습니다. 간단한 텍스트 기반 형식 덕분에 JSON은 가볍고 고성능을 유지하면서 쉽게 읽고 구문 분석할 수 있습니다. XML과 달리 JSON은 JavaScript, Python, Ruby 및 Java와 같은 최신 프로그래밍 언어의 기본 데이터 구조에 직접 매핑되므로 사용자 지정 파서가 필요하지 않습니다.

API를 통해 상호 작용하는 단일 페이지 애플리케이션, 모바일 앱 및 IoT 장치의 등장으로 직렬화된 데이터 전송에 대한 JSON의 인기가 더욱 확고해졌습니다. JSON은 어디에나 존재하므로 다양한 시스템 간의 통신을 가능하게 하는 자연스러운 선택입니다. JSON의 단순성, 보편성 및 내장된 언어 지원은 탄력적이고 확장 가능한 데이터 교환 형식임이 입증되었습니다.

엄격한 JSON 스키마를 정의하면 개발자가 런타임에 데이터 형식과 값의 유효성을 검사할 수 있습니다. 이는 전반적인 API 품질과 안정성을 향상시킵니다. 잘 정의된 JSON 스키마는 API 클라이언트와 서버 간의 계약 역할을 하여 모호성과 가능한 실패 지점을 줄입니다. 이 문서에서는 JSON 스키마 정의, 유효성 검사 도구, 디자인 팁 등을 살펴봅니다.

JSON 스키마 정의

JSON 스키마는 JSON 문서의 구조와 데이터 유형을 정의합니다. 구조가 기대와 일치하는지 확인하기 위한 검증에 사용됩니다.

JSON 스키마는 그 자체로 다른 JSON 문서의 형태를 선언하는 JSON 파일입니다. 스키마는 다음과 같은 요구 사항을 지정합니다.

• JSON 객체에 포함될 수 있는 속성
• 필수 속성과 선택 속성
• 문자열, 숫자, 배열과 같은 값의 데이터 유형
• 문자열의 길이 제한 또는 허용되는 값 집합

JSON 스키마의 일부 주요 구성 요소는 다음과 같습니다.

• $schema - JSON 스키마 버전을 선언합니다.
• type - 데이터 유형(객체, 배열, 문자열 등)
• properties - 개체의 속성을 키-값 쌍으로 지정합니다.
• required - 필수 객체 속성을 나열합니다.
• additionalProperties - 지정되지 않은 추가 속성이 허용되는지 여부
• minLength / maxLength - 문자열 길이 범위
• minimum / maximum - 숫자 값 범위
• enum - 값이 될 수 있는 허용되는 값 옵션

스키마를 사용하면 JSON 문서가 선언된 구조와 일치하는지 확인할 수 있습니다. 이는 API 생산자와 소비자 간의 계약 역할을 합니다. 잘 정의된 스키마는 통합을 더 쉽게 만들고 인터페이스의 탄력성을 높여줍니다.

스키마 검증사전 정의된 스키마에 대한 JSON 데이터의 유효성 검증은 JSON 스키마 정의의 가장 큰 이점 중 하나입니다. 스키마 검증은 API와 주고받는 JSON 페이로드가 예상 데이터 형식과 일치하는지 확인합니다.

클라이언트가 API에 요청하면 요청 페이로드가 애플리케이션 코드에 도달하기 전에 요청 스키마에 대해 검증될 수 있습니다. 이는 잘못된 데이터로부터 API를 보호하고 입력이 앱에서 예상하는 것과 일치하도록 보장합니다.

마찬가지로 API의 응답은 응답 스키마에 대해 검증될 수 있습니다. 이렇게 하면 API 출력이 계약과 일치하고 클라이언트가 응답을 안정적으로 구문 분석할 수 있습니다.

스키마 유효성 검사에는 다음과 같은 몇 가지 장점이 있습니다.

• 유효하지 않은 데이터 형식을 거부하여 버그를 조기에 포착합니다.
• API 계약 및 데이터 구조에 규율을 적용합니다.
• 클라이언트 및 서버 코드의 데이터 형태에 대한 가정을 줄입니다.
• 사용 및 통합에 대한 명확한 기대치를 제공합니다.
• 문서 역할을 하고 구현을 안내합니다.
• JSON 스키마 라이브러리를 사용하여 기존 파이프라인에 검증을 쉽게 통합할 수 있습니다.
• TypeScript와 같은 여러 언어에 대한 유효성 검사 코드를 생성할 수 있습니다.

전반적으로 JSON 스키마 유효성 검사는 강력하고 유지 관리 가능한 API를 위한 필수 방법입니다. 스키마를 정의하는 것은 전투의 절반에 불과합니다. 해당 스키마에 대해 유효성을 검사하면 스키마가 실제로 생생해집니다.

검증 도구

JSON 스키마 검증을 통해 JSON 데이터가 예상 형식과 일치하는지 확인합니다. 스키마 유효성 검사를 위한 몇 가지 유용한 오픈 소스 라이브러리가 있습니다.

• Ajv - JavaScript로 작성된 빠른 JSON 스키마 유효성 검사기. 초안-04/06/07을 지원합니다.

• jsonschema - Python용 JSON 스키마 구현.

• JSV - JavaScript로 작성된 독립형 JSON 스키마 유효성 검사기입니다.

• json-schema-validator - JSON 스키마 초안 04-07에 대한 Node.js 유효성 검사기.

• JaySchema - Java용 JSON 스키마 유효성 검사기.

• Jsonix 스키마 컴파일러 - JavaScript에서 스키마 유효성 검사기를 생성합니다.

• Go JSON 스키마 검사기 - Go로 작성된 JSON 스키마 검사기.이러한 라이브러리를 사용하면 스키마에 대해 JSON 데이터의 유효성을 검사하여 형식 문제를 조기에 파악할 수 있습니다. 스키마 준수를 강화하기 위해 빌드 파이프라인 및 테스트 스위트에 쉽게 통합할 수 있습니다. 대부분은 최신 JSON 스키마 초안을 지원하며 검증 엄격성을 위해 구성 가능합니다.

스키마 디자인 팁

JSON 스키마를 설계할 때 다음 모범 사례를 따르세요.

• 스키마를 단순하고 모듈식으로 유지하십시오. 필요에 따라 결합할 수 있는 논리적 청크로 스키마 정의를 나눕니다. 대규모 모놀리식 스키마를 피하세요.

• 약어보다는 firstName과 같이 설명적이고 일관된 속성 이름을 사용하십시오.

• 스키마 및 속성에 대한 명확한 설명과 제목을 제공합니다.

• 적절한 속성을 필수 속성과 선택 속성으로 만듭니다. 데이터가 필요한 경우에만 속성을 필수로 설정하세요.

• 적절한 경우 minLength 및 maxLength를 사용하여 문자열 값을 제한합니다.

• 미리 정의된 값의 작은 고정 세트에는 열거형을 사용합니다.

• 속성에 대해 예상되는 데이터 유형 및 형식을 정의합니다. 예를 들어, 정수에는 integer을 사용하고 타임스탬프에는 format: date-time와 함께 string를 사용합니다.

• minimum: 0 또는 maximum: 100과 같은 숫자 속성에 대한 관련 최소값과 최대값을 설정합니다.

• 합리적인 경우 선택적 속성에 기본값을 사용합니다.

• "type": "string" 대신 "type": ["string", "null"]을 사용하여 적절한 경우에만 null 값을 허용합니다.

• "uniqueItems": true을 사용하여 필요한 경우 고유성을 검증합니다.

• 정의를 복제하기보다는 참조하고 재사용하려면 "$ref"을 사용하세요.

• 클라이언트가 이해할 수 있는 명확한 유효성 검사 오류 메시지를 작성합니다.

• 각 스키마에 대해 유효한 데이터와 유효하지 않은 데이터의 예를 제공합니다.

• "$comment" 필드를 사용하여 스키마를 문서화하세요.

• 스키마가 발전함에 따라 버전을 관리하세요.

스키마 디자인 모범 사례를 따르면 JSON API의 유지 관리 가능성, 테스트 가능성 및 유용성이 향상됩니다.

일반적인 함정

JSON 스키마를 디자인할 때 스키마를 불안정하게 만들거나 유지 관리하기 어렵게 만드는 몇 가지 일반적인 실수를 피하는 것이 중요합니다.

지나치게 엄격한 검증

모든 가능성을 설명하기 위해 스키마를 매우 엄격하게 만들고 싶은 유혹이 있습니다. 그러나 이로 인해 스키마를 업데이트하기가 어려워지고 유효한 데이터가 차단되는 경우가 많습니다. 기본 검증부터 시작하고 꼭 필요한 경우에만 제약 조건을 더 추가하세요.

버전: “2.0.0” 모든 곳에서

각 변경마다 이를 증가시킬 계획이 아니라면 모든 스키마에서 "version": "2.0.0"을 사용하지 않는 것이 가장 좋습니다. 이는 오버헤드를 추가하고 대부분의 경우 의미 있는 버전 관리를 제공하지 않습니다. 대신 태그나 개정 ID를 사용하세요.

확장성을 계획하고 있지 않음스키마는 미래의 새로운 속성과 데이터를 설명해야 합니다. 현재 필요한 속성만 요구하고 추가 속성을 허용합니다.

데이터 변형 무시

데이터 형식에는 날짜나 ID와 같은 여러 가지 표현이 허용되는 경우가 많습니다. 유효성 검사 오류를 방지하려면 스키마에서 공통 변형을 허용해야 합니다.

지나치게 복잡한 중첩 개체

개체와 배열을 너무 깊게 중첩하면 스키마를 이해하고 수정하기가 어려워집니다. 스키마를 상대적으로 단순하게 유지하십시오. 재사용된 중첩 요소를 정의로 분리합니다.

결정을 문서화하지 않음

설명을 사용하여 스키마에서 유효성 검사 결정이 내려진 이유를 문서화합니다. 이는 미래의 유지관리자가 이론적 근거와 의도된 용도를 이해하는 데 도움이 됩니다.

처음부터 스키마 모범 사례를 따르면 이러한 일반적인 실수를 방지하는 데 도움이 됩니다. 핵심 검증에 초점을 맞춘 스키마를 유지하고 확장의 유연성을 허용합니다.

스키마 진화

JSON 스키마는 요구 사항이 변경됨에 따라 시간이 지남에 따라 발전해야 합니다. 여기에는 기존 클라이언트를 손상시킬 수 있는 업데이트가 포함됩니다. 스키마 발전에는 API 제공자와 소비자 간의 신중한 계획과 의사소통이 필요합니다.

스키마 변경을 처리하는 데는 몇 가지 접근 방식이 있습니다.

• 스키마 버전을 지정하고 새 버전에서 호환되지 않는 변경을 수행합니다. 클라이언트가 지원하는 버전을 지정할 수 있도록 허용합니다.

• 기존 클라이언트를 중단하지 않는 새로운 선택적 속성을 도입합니다. 클라이언트가 업데이트할 시간이 생긴 후에 나중에 속성을 필수로 설정하세요.

• “anyOf” 구성을 사용하여 스키마의 새로운 변형과 이전 변형을 동시에 허용합니다. 점차적으로 클라이언트를 새 스키마로 전환합니다.

• 주요 변경 사항의 경우 사전 공지 및 마이그레이션 지침을 제공합니다. 처음에는 기능 토글 뒤 또는 카나리아 클러스터에 변경 사항을 적용합니다.

• 스키마 기록과 메타데이터를 저장하는 스키마 레지스트리를 사용합니다. 이는 서비스 전반에 걸쳐 스키마 수명주기를 중앙에서 관리하는 데 도움이 됩니다.

• 스키마 변경 사항을 감지하고, 데이터를 마이그레이션하고, 업데이트된 클라이언트 모델을 생성하는 도구를 제공합니다. 가능한 한 많은 전환을 자동화하세요.

스키마를 발전시킬 때는 신중한 계획이 필수적입니다. 변경 사항을 초기에 소비자에게 명확하게 전달합니다. 전환 중에 레거시 스키마를 지원합니다. 가능한 경우 마이그레이션 메커니즘을 자동화하세요. 우수한 스키마 거버넌스를 통해 팀은 시간이 지남에 따라 스키마를 조정하는 동시에 클라이언트의 주요 변경 사항을 방지할 수 있습니다.

코드 생성JSON 스키마 정의의 주요 이점 중 하나는 클라이언트가 스키마를 사용할 수 있도록 코드를 자동 생성하는 기능입니다. 이렇게 하면 모델과 직렬 변환기를 수동으로 작성할 필요가 없어 개발 시간과 노력이 크게 절약됩니다. JSON 스키마에서 코드를 생성할 수 있는 여러 도구가 있습니다.

• Quicktype - TypeScript, C#, Java, Go 및 Swift를 포함한 35개 이상의 언어에 대한 유형 및 파서를 생성하는 오픈 소스 도구입니다. 열거형, null 허용 유형, 공용체 및 제네릭과 같은 기능을 사용하여 복잡한 스키마를 지원합니다.

• JSON Schema Codegen - JSON 스키마에서 Java, C#, Go, Typescript, JavaScript, Swift, Kotlin 및 Rust 코드를 생성할 수 있는 Java 명령줄 도구입니다. 코드 생성을 사용자 정의할 수 있는 플러그인 생태계가 있습니다.

• JWT 스키마 - JSON 스키마를 기반으로 하는 JWT 토큰용 코드 생성에 중점을 둡니다. Java, Typescript, C#, Go, Ruby 및 PHP를 지원합니다.

• GraphQL 코드 생성기 - 주로 GraphQL 스키마 및 해석기 코드를 생성하는 데 사용되지만 JSON 스키마에서 TypeScript 유형 생성도 지원합니다.

• API 스크립트 - TypeScript, C#, Java, Go, Ruby 등에 대한 코드를 생성하는 Windows 및 Mac용 GUI 기반 도구입니다. 생성된 코드를 테스트하기 위한 모의 서버를 포함합니다.

• JSONSchema2Pojo - JSON 스키마에서 Java POJO를 생성하기 위한 Maven 및 Gradle 플러그인입니다. 주석 및 구성 가능한 규칙을 통해 사용자 정의할 수 있습니다.

자동 생성된 코드는 반복적인 작업을 많이 줄여주고 스키마에 정의된 구조를 적용합니다. 생성된 모델을 애플리케이션 코드베이스로 직접 가져올 수 있으며 필요에 따라 추가 사용자 정의를 추가할 수 있습니다. 전반적인 스키마 기반 코드 생성은 개발을 간소화하고 API 인터페이스와 구현 간의 일관성을 보장하는 데 도움이 됩니다.

스키마 레지스트리

스키마 레지스트리는 스키마 저장 및 검색을 위한 중앙 집중식 저장소를 제공합니다. 여러 애플리케이션과 서비스를 갖춘 대규모 조직 전체에서 대규모로 스키마 관리를 가능하게 합니다. 스키마 레지스트리의 주요 이점은 다음과 같습니다.

• 중앙 집중식 스키마 저장소 - 모든 스키마 정의가 한 곳에 저장되어 단일 정보 소스를 제공합니다. 이렇게 하면 중복과 불일치가 방지됩니다.

• 스키마 버전 관리 - 레지스트리는 각 스키마의 버전을 유지 관리합니다. 이는 통제된 방식으로 시간이 지남에 따라 스키마의 발전을 지원합니다. 새로운 스키마는 기존 소비자를 손상시키지 않습니다.

• 스키마 조회 - 서비스는 ID 또는 주제별로 스키마 정의를 쉽게 조회할 수 있습니다. 생산자와 소비자 간의 결합을 줄입니다.- 스키마 호환성 검사 - 레지스트리는 새 스키마 버전과 기존 버전 간의 호환성을 확인할 수 있습니다. 주요 변경 사항이 도입되는 것을 방지합니다.

• 스키마 발전 거버넌스 - 레지스트리 정책은 시간이 지남에 따라 스키마가 어떻게 발전할 수 있는지 제어합니다. 예를 들어 특정 주제에 대해 이전 버전과의 호환성을 적용합니다.

• 성능 및 확장성 - 스키마의 중앙 집중식 캐싱으로 성능이 향상됩니다. 레지스트리를 수평으로 확장하면 로드가 처리됩니다.

Apache Kafka를 사용하는 이벤트 기반 아키텍처의 대규모 프로덕션 배포에는 스키마 레지스트리가 필수적입니다. 인기 있는 오픈 소스 옵션으로는 Confluent Schema Registry와 Apicurio Registry가 있습니다. 레지스트리는 스키마 및 스키마 유효성 검사를 통해 강력하고 안정적인 데이터 교환을 가능하게 하는 핵심 구성 요소입니다.

결론

살펴본 것처럼 JSON 스키마는 최신 API 아키텍처에서 기대치를 정의하고 데이터를 검증하는 데 중요한 역할을 합니다. 개발자는 정확한 JSON 스키마를 생성하여 요청 및 응답 페이로드에 대한 명확한 계약을 설정합니다. 이를 통해 API 클라이언트와 서버 간의 안정성, 견고성 및 이해도가 향상됩니다.

JSON 스키마와 같은 스키마 유효성 검사 도구는 스키마에 대해 JSON 데이터의 유효성을 검사하는 기본 제공 기능을 제공합니다. 이는 오류를 조기에 포착하고 올바른 형식이 사용되도록 하는 데 도움이 됩니다. 유효성 검사는 잘못된 데이터로 인해 오류가 발생하는 것을 방지합니다.

JSON 스키마를 디자인할 때 명확성, 유연성 및 호환성에 중점을 두는 것이 중요합니다. 스키마는 지나치게 제한하지 않고 데이터 형식의 본질을 포착해야 합니다. 스키마가 이전 버전과 호환되는 방식으로 발전하도록 허용하면 기존 클라이언트를 손상시키지 않고 API를 개선할 수 있습니다.

전반적으로 JSON 스키마와 검증은 API 개발에 큰 이점을 제공합니다. 스키마를 통해 엄격한 계약을 정의하면 독립적인 모듈식 소프트웨어 시스템이 가능해집니다. 검증을 통해 개발자는 데이터가 정의된 사양을 충족한다는 확신을 갖게 됩니다. 강력한 스키마와 검증은 확장 가능하고 안정적인 API 아키텍처를 가능하게 하는 핵심 요소입니다.

JSON 및 REST API의 사용량이 계속 증가함에 따라 강력한 JSON 스키마를 개발하는 것은 API 개발자에게 필수적인 기술로 남을 것입니다. 고품질 웹 API를 구축하려면 스키마 설계 및 검증 모범 사례를 숙지하는 것이 필수적입니다.이 흥미진진한 분야에 대한 더 많은 통찰력과 업데이트를 보려면 APIRobots)을 계속 지켜봐 주시기 바랍니다. API가 귀하의 비즈니스에 가져올 수 있는 기회를 놓치지 마십시오. 지금 API Robots API 개발 대행사)에 문의하여 API의 모든 잠재력을 함께 활용해 보시기 바랍니다.