개발자 도구 · JSON 포맷터 및 유효성 검사기
유효한 JSON과 스키마에 대한 유효한 비교: '유효'의 두 가지 의미
· 배경
JSON 표준 검증
JSON이 유효하다고 말하는 유효성 검사기는 구문 분석만 의미합니다. 이 게시물에서는 유효성 수준(구문, 구조, 의미)과 문법 이외의 모든 것에 대해 JSON 스키마가 존재하는 이유를 설명합니다.
유효하지만 여전히 거부됨
요청은 완벽할 수 있지만(JSON) 여전히 API에서 허용되지 않습니다. `{"username":"nori","plan":"gold"}`에는 균형 구분 기호, 인용된 이름 및 법적 값이 있지만 서비스에서 이메일을 요구하거나 계획 이름을 거부하거나 현재 상태에서 계정 생성을 금지할 수 있습니다. 파서와 애플리케이션은 서로 다른 질문에 응답하므로 두 결과가 모두 정확할 수 있습니다.
ToolAcre는 첫 번째 질문에만 답변합니다. 이 텍스트를 입력 제한 내에서 엄격한 JSON로 구문 분석할 수 있습니까? 스키마 로드, 필수 속성 확인, 형식 확인, 데이터베이스 연결 또는 비즈니스 규칙 평가는 수행되지 않습니다. 도구에 유효하다고 표시되면 해당 값을 사용하는 시스템의 승인이 아니라 "잘 구성된 JSON 구문"으로 읽으십시오.
레벨 1: 올바른 형식의 구문
구문 유효성 검사는 JSON 문법(최상위 값 1개, 올바르게 쌍을 이루는 컨테이너, 인용된 개체 이름, 유효한 쉼표와 콜론, 유효한 문자열, 유효한 숫자 및 정확한 리터럴)을 확인합니다. `NaN` 및 `Infinity`, 주석, 후행 쉼표 및 작은따옴표 문자열을 거부합니다. 고립된 숫자나 익숙하지 않은 필드가 있는 객체를 포함하여 문법에 유효한 모든 형태를 허용합니다.
잘못된 소스에는 텍스트 오류 지점이 있으므로 ToolAcre는 첫 번째 불가능한 문자에 대한 줄과 열을 보고할 수 있습니다. 쉼표가 없으면 다음 인용문이 보고될 수 있습니다. 후행 쉼표로 인해 닫는 구분 기호가 보고될 수 있습니다. 구문을 수정하면 구문 분석 가능한 값이 생성되지만 해당 값이 다른 프로그램에서 예상하는 모양이나 의미를 갖는지 확인하지는 않습니다.
레벨 2: 모양
형태 검증은 구문 분석된 값이 선언된 계약과 일치하는지 여부를 묻습니다. 사용자 스키마에는 `email`이 필요하고, `age`을 최소 18의 정수로 제한하고, `tier`을 `free` 또는 `pro`로 제한하고, 알 수 없는 속성을 허용하지 않을 수 있습니다. `{"email":false,"tier":"gold"}`은 유효한 JSON 구문이지만 값 유형과 허용된 선택 사항이 잘못되었기 때문에 이러한 구조적 규칙에 실패합니다.
JSON 스키마는 이러한 제약 조건을 표현하는 한 가지 방법이지만 ToolAcre는 이를 실행하지 않습니다. 스키마 유효성 검사기는 일반적으로 `/tier`과 같은 인스턴스 경로, `enum`와 같은 키워드 및 파서 캐럿 대신 설명 메시지를 보고합니다. 이 수준을 진단할 때 페이로드 옆에 스키마 버전과 API 계약을 유지하세요. 구두점을 변경해도 잘못된 모양의 올바르게 구문 분석된 값이 복구되지 않습니다.
레벨 3: 의미
의미는 문서의 정적인 형태를 넘어서는 사실과 규칙에 따라 달라집니다. `accountId`은(는) 계정 이름을 지정하지 않고도 올바른 문자열 패턴을 가질 수 있습니다. 시작 날짜는 종료 날짜 이후에 해당하는 ISO 스타일 형식과 일치할 수 있습니다. 수량은 양수이지만 현재 재고를 초과할 수 있습니다. 이러한 실패에는 애플리케이션 컨텍스트, 저장된 상태 또는 필드 간의 관계가 필요합니다.
일부 의미론적 제약 조건은 스키마에서 근사화될 수 있지만 대부분은 신뢰할 수 있는 데이터와 트랜잭션 상태를 사용할 수 있는 서비스 논리에 속합니다. 이 수준의 오류 응답은 JSON 텍스트의 형식이 잘못된 척하지 않고 관련 필드 또는 규칙을 식별해야 합니다. ToolAcre는 계약을 모르거나 비즈니스 규칙을 소유한 애플리케이션에 입력을 보내지 않기 때문에 이러한 결정을 재현할 수 없습니다.
실제 예: 세 번의 검사를 통한 하나의 페이로드
`{"sku":"A-19","quantity":3,"warehouse":"north"}`로 시작하세요. ToolAcre는 이를 허용합니다. 모든 이름과 값은 JSON 문법을 따릅니다. 그런 다음 스키마에는 개체, 비어 있지 않은 문자열 SKU, 양의 정수 수량 및 문서화된 창고 코드 중 하나가 필요할 수 있습니다. 이 페이로드도 이러한 제약 조건을 통과한다고 가정합니다. 두 확인 모두 SKU A-19이 존재하는지 또는 북쪽에 3개 단위가 있는지 확인하지 못했습니다.
인벤토리 서비스는 현재 기록에 대해 세 번째 확인을 수행하고 요청을 사용할 수 없는 것으로 거부할 수 있습니다. 들여쓰기를 변경해도 해당 결과는 바뀔 수 없습니다. `quantity`이 `03`로 작성된 경우 구문이 먼저 실패합니다. `"3"`인 경우 구문 분석은 통과하지만 스키마 유형 확인은 실패합니다. 숫자 `3`을 사용하면 라이브 재고 규칙만 남습니다. 따라서 동일한 필드는 세 가지 다른 이유로 인해 세 가지 개별 레이어에서 실패할 수 있습니다.
각 수표가 속한 곳
구문 분석되지 않는 텍스트에서는 나중에 검사가 안정적으로 작동할 수 없으므로 편집하는 동안 가능한 한 빨리 구문 유효성 검사를 실행하십시오. 클라이언트가 이미 그렇게 했다고 가정하기보다는 신뢰할 수 없는 각 애플리케이션 경계에서 선언된 형태를 적용하십시오. 특히 요청 간에 응답이 변경될 수 있는 경우 필요한 상태를 소유하는 구성 요소의 비즈니스 불변성을 평가합니다.
클라이언트측 검사는 피드백을 개선하지만 서버측 시행을 대체하지는 않습니다. 반대로, "잘못된 JSON"이라는 서버 응답은 거부된 모든 요청에 사용되기보다는 구문 분석 실패를 위해 예약되어야 합니다. 명확한 분리는 구문에 대한 행과 열, 구조적 제약에 대한 인스턴스 경로, 의미 충돌에 대한 도메인별 코드 또는 메시지 등 유용한 진단을 생성합니다. ToolAcre는 첫 번째 범주만 제공합니다.
여기서 다루지 않는 내용
이 포맷터는 JSON 스키마를 작성하거나 평가하고, 스키마 초안을 선택하고, 스키마 참조를 확인하고, 기본값을 삽입하거나 숫자에 문자열을 강제 변환하지 않습니다. 또한 API의 OpenAPI 문서나 사용자 정의 유효성 검사 규칙도 모릅니다. 이 도구에는 스키마 처리 단계가 없기 때문에 입력과 함께 스키마를 제공하면 ToolAcre의 결과가 변경되지 않습니다.
구문 유효성 검사는 여기서 중복된 개체 이름도 감지하지 않습니다. `JSON.parse`은 포맷하기 전 마지막 항목을 유지합니다. 또한 숫자 정밀도, 표준 바이트, 안전한 렌더링 또는 인증을 보장하지 않습니다. 이러한 각 문제에는 자체 계약과 구현이 필요합니다. 이를 하나의 녹색 "유효" 배지로 압축하지 마십시오. 그렇게 하면 수집된 증거와 질문되지 않은 질문이 숨겨지기 때문입니다.
요점: '유효'에는 한정자가 필요합니다.
모든 검증 청구에 자격을 부여합니다. "유효한 JSON"은 텍스트가 문법을 따른다는 의미입니다. "이 스키마에 대해 유효함"은 구문 분석된 값이 명명된 구조 계약을 충족한다는 것을 의미합니다. "서비스에서 승인됨"은 현재 애플리케이션 규칙이 작업을 허용한다는 의미입니다. 많은 워크플로에서 다음 레이어를 위해 하나의 레이어를 전달해야 하지만 이것이 이후의 모든 레이어가 통과했다는 증거는 아닙니다.
ToolAcre를 사용하여 `NaN` 및 `Infinity`와 같은 비 JSON 리터럴 거부를 포함하여 엄격한 구문을 형식화하고 확인합니다. 그런 다음 실제로 페이로드를 관리하는 스키마와 애플리케이션을 사용하세요. 요청이 여전히 실패하면 올바른 JSON 형식을 반복적으로 다시 지정하는 대신 자체 계층에서 오류를 읽으십시오. 이 도구에는 스키마 검사가 없으며 명시적인 경계는 유효성에 대한 광범위한 약속보다 더 유용합니다.