json schema validator
1.5.3
스택 오버플로 | Google Group | Gitter 채팅 | 하위 레드 | YouTube | 문서 | 기여 가이드 |
JSON 스키마 유효성 검사를위한 JSON 스키마 코어 드래프트 v4, v6, v6, V2019-09 및 V2020-12 사양의 Java 구현입니다. 이 구현은 메타-스케인, 어휘, 키워드 및 형식 사용자 정의를 지원합니다.
또한 OpenAPI 3 요청/응답 검증은 적절한 메타 스키마를 사용하여 지원됩니다. 스키마를 기반으로 JSON 노드에서 정보를 수집하려는 사용자의 경우 Walkers가 도움을 줄 수 있습니다. 사용 된 JSON 파서는 Jackson Parser입니다. Light-4J MicroServices 프레임 워크의 핵심 구성 요소이므로 런타임시 Light-Hybrid-4J의 OpenAPI 사양 및 RPC 스키마에 대한 요청/응답을 검증하기위한 핵심 요소이므로 성능은 설계에서 가장 중요한 측면입니다.
알려진 문제를 포함하여 각 버전에 대한 호환성 지원에 대한 정보는 JSON Schema 버전 문서와의 호환성에서 찾을 수 있습니다.
2019-09 초안 이후 format 키워드는 기본적으로 주석 만 생성되며 어설 션을 생성하지 않습니다.
이 동작은 SchemaValidatorsConfig 또는 ExecutionConfig 에서 setFormatAssertionsEnabled true 로 설정하여 어설 션을 생성하기 위해 무시할 수 있습니다.
이 라이브러리에는 코드 변경이 필요할 수있는 minor 버전 릴리스의 중단이 포함될 수 있습니다.
라이브러리를 업그레이드 할 때 주목할만한 변경 또는 변경 사항에 대한 정보는 새로운 버전 문서로 업그레이드 한 문서에서 찾을 수 있습니다.
릴리스 페이지에는 최신 버전에 대한 정보가 포함됩니다.
Creek의 JSON 스키마 검증 비교 프로젝트는 다양한 Java 구현의 기능 및 성능 특성을 모두 비교하는 JVM 기반 스키마 검증 구현을 유익한 비교했습니다.
Bowtie Project에는 Java가 아닌 구현을 포함하여 다양한 구현의 기능적 특성을 비교하지만 성능 벤치마킹을 수행하지 않는 보고서가 있습니다.
이것은 가장 빠른 Java JSON Schema Validator 구현이어야합니다.
다음은 Java Microbenchmark 하네스를 사용하는 JSON Schema Validator Perftest 프로젝트의 벤치 마크 결과입니다.
벤치 마크 결과는 입력 데이터 워크로드 및 유효성 검사에 사용되는 스키마에 크게 의존합니다.
이 경우이 워크로드는 초안 4 사양을 사용하고 properties 키워드 평가의 성능을 크게 테스트합니다. 보다 일반적인 워크로드에 대한 벤치 마크 결과에 대한 JVM 기반 JSON 스키마 검증 구현의 성능 비교 결과를 참조하십시오.
성능이 중요한 고려 사항 인 경우 특정 키워드를 사용할 때는 성능 특성이 다르므로 특정 샘플 워크로드를 벤치마킹해야합니다. 예를 들어, unevaluatedProperties 요소 또는 unevaluatedItems 화 키워드를 사용하면 properties 또는 items 검증기와 같은 관련 유효성 검사기에서 주석 수집이 트리거되며 주석 컬렉션은 성능에 부정적인 영향을 미칩니다.
Benchmark Mode Cnt Score Error Units
NetworkntBenchmark.testValidate thrpt 10 8352.126 ± 61.870 ops/s
NetworkntBenchmark.testValidate:gc.alloc.rate thrpt 10 721.296 ± 5.342 MB/sec
NetworkntBenchmark.testValidate:gc.alloc.rate.norm thrpt 10 90560.013 ± 0.001 B/op
NetworkntBenchmark.testValidate:gc.count thrpt 10 61.000 counts
NetworkntBenchmark.testValidate:gc.time thrpt 10 68.000 ms
Benchmark Mode Cnt Score Error Units
EveritBenchmark.testValidate thrpt 10 3775.453 ± 44.023 ops/s
EveritBenchmark.testValidate:gc.alloc.rate thrpt 10 1667.345 ± 19.437 MB/sec
EveritBenchmark.testValidate:gc.alloc.rate.norm thrpt 10 463104.030 ± 0.003 B/op
EveritBenchmark.testValidate:gc.count thrpt 10 140.000 counts
EveritBenchmark.testValidate:gc.time thrpt 10 158.000 ms
이 구현은 JSON 스키마 테스트 스위트에 대해 테스트됩니다. 테스트가 스위트에 지속적으로 추가되므로 이러한 테스트 결과는 최신 상태가 아닐 수 있습니다.
| 구현 | 전반적인 | Draft_03 | Draft_04 | Draft_06 | Draft_07 | Draft_2019_09 | Draft_2020_12 |
|---|---|---|---|---|---|---|---|
| Networknt | 패스 : R : 4803 (100.0%) O : 2372 (100.0%) 실패 : R : 0 (0.0%) O : 0 (0.0%) | 패스 : R : 610 (100.0%) O : 251 (100.0%) 실패 : R : 0 (0.0%) O : 0 (0.0%) | 패스 : R : 822 (100.0%) O : 318 (100.0%) 실패 : R : 0 (0.0%) O : 0 (0.0%) | 패스 : R : 906 (100.0%) O : 541 (100.0%) 실패 : R : 0 (0.0%) O : 0 (0.0%) | 패스 : R : 1220 (100.0%) O : 625 (100.0%) 실패 : R : 0 (0.0%) O : 0 (0.0%) | 패스 : R : 1245 (100.0%) O : 637 (100.0%) 실패 : R : 0 (0.0%) O : 0 (0.0%) |
pattern 및 format regex 테스트에 JoniRegularExpressionFactory 사용합니다. 이 라이브러리는 다른 프로젝트에서 널리 사용되는 Java JSON 파서 인 Jackson을 사용합니다. 프로젝트에서 이미 Jackson Parser를 사용하는 경우 스키마 검증을 위해 다른 사람 보다이 라이브러리를 선택하는 것이 당연합니다.
라이브러리는 스키마 정의 및 입력 데이터에서 JSON 및 YAML과 함께 작동합니다.
OpenApi 3.0 사양은 JSON 스키마를 사용하여 요청/응답을 유효성을 유지하지만 몇 가지 차이점이 있습니다. 구성 파일을 사용하면 라이브러리가 OpenApi 3.0 유효성 검사에서 작업 할 수 있습니다.
라이트 플랫폼의 설계 원칙에 따라이 라이브러리는 최소한의 종속성이있어 사용시 종속성 충돌이 없도록합니다.
다음은이 라이브러리가 포함될 때 자동으로 포함되는 종속성입니다.
< dependency >
<!-- Used for logging -->
< groupId >org.slf4j</ groupId >
< artifactId >slf4j-api</ artifactId >
< version >${version.slf4j}</ version >
</ dependency >
< dependency >
<!-- Used to process JSON -->
< groupId >com.fasterxml.jackson.core</ groupId >
< artifactId >jackson-databind</ artifactId >
< version >${version.jackson}</ version >
</ dependency >
< dependency >
<!-- Used to process YAML -->
< groupId >com.fasterxml.jackson.dataformat</ groupId >
< artifactId >jackson-dataformat-yaml</ artifactId >
< version >${version.jackson}</ version >
</ dependency >
< dependency >
<!-- Used to validate RFC 3339 date and date-time -->
< groupId >com.ethlo.time</ groupId >
< artifactId >itu</ artifactId >
< version >${version.itu}</ version >
</ dependency >다음은 특정 옵션에 필요한 선택적 종속성입니다.
여기에는 자동으로 포함되지 않으며 라이브러리를 추가하지 않고 관련 옵션을 설정하면 ClassNotFoundException 이 발생합니다.
< dependency >
<!-- Used to validate ECMA 262 regular expressions -->
<!-- Approximately 50 MB in dependencies -->
<!-- GraalJSRegularExpressionFactory -->
< groupId >org.graalvm.js</ groupId >
< artifactId >js</ artifactId >
< version >${version.graaljs}</ version >
</ dependency >
< dependency >
<!-- Used to validate ECMA 262 regular expressions -->
<!-- Approximately 2 MB in dependencies -->
<!-- JoniRegularExpressionFactory -->
< groupId >org.jruby.joni</ groupId >
< artifactId >joni</ artifactId >
< version >${version.joni}</ version >
</ dependency >다음은 자동으로 포함 된 의존성이 필요하지만 필요하지 않은 경우 명시 적으로 제외 할 수 있습니다.
필요하지 않은 경우 YAML 의존성을 제외 할 수 있습니다. YAML 인 스키마 또는 입력을 처리하려고하면 ClassNotFoundException 이 발생합니다.
< dependency >
< groupId >com.networknt</ groupId >
< artifactId >json-schema-validator</ artifactId >
< exclusions >
< exclusion >
< groupId >com.fasterxml.jackson.dataformat</ groupId >
< artifactId >jackson-dataformat-yaml</ artifactId >
</ exclusion >
</ exclusions >
</ dependency > date-time 형식의 정확한 검증이 필요하지 않은 경우 Ethlo 시간 종속성을 제외 할 수 있습니다. date-time 형식은 java.time.OffsetDateTime 사용하여 date-time 유효한지 확인합니다.
< dependency >
< groupId >com.networknt</ groupId >
< artifactId >json-schema-validator</ artifactId >
< exclusions >
< exclusion >
< groupId >com.ethlo.time</ groupId >
< artifactId >itu</ artifactId >
</ exclusion >
</ exclusions >
</ dependency >이 라이브러리는 많은 기고자들에게 매우 활발합니다. 새로운 기능과 버그 수정은 팀원이 신속하게 처리합니다. 동일한 GitHub 조직에서 Light-4J 프레임 워크의 필수 의존성이기 때문에 프레임 워크와 함께 진화하고 유지 될 것입니다.
도서관은 Java 8 이상을 지원합니다. 소스 코드에서 빌드하려면 로컬로 JDK 8을 설치해야합니다. 여러 버전의 JDK를 지원하려면 sdkman을 사용할 수 있습니다.
이 패키지는 Maven Central에서 제공됩니다.
< dependency >
< groupId >com.networknt</ groupId >
< artifactId >json-schema-validator</ artifactId >
< version >1.5.3</ version >
</ dependency > dependencies {
implementation ( group : 'com.networknt' , name : 'json-schema-validator' , version : '1.5.3' );
}다음 예제는 입력이 스키마에 대해 검증되는 방법을 보여줍니다. 다음 단계로 구성됩니다.
schemaMappers 사용하여 $id 검색 URI에 매핑하는 구성.schemaLoaders 사용하여 검색 URI를 사용하여 스키마를로드하는 방법 구성. 예를 들어 Map<String, String> schemas 에 대한 검색 URI를 스키마 데이터에 매핑하는 스키마 builder.schemaLoaders(schemaLoaders -> schemaLoaders.schemas(schemas)) 사용하여 String 로 스키마 데이터에 대한 매핑을 포함합니다. 또한 Function<String, String> schemaRetrievalFunction 허용합니다. // This creates a schema factory that will use Draft 2020-12 as the default if $schema is not specified
// in the schema data. If $schema is specified in the schema data then that schema dialect will be used
// instead and this version is ignored.
JsonSchemaFactory jsonSchemaFactory = JsonSchemaFactory . getInstance ( VersionFlag . V202012 , builder ->
// This creates a mapping from $id which starts with https://www.example.org/ to the retrieval URI classpath:schema/
builder . schemaMappers ( schemaMappers -> schemaMappers . mapPrefix ( "https://www.example.org/" , "classpath:schema/" ))
);
SchemaValidatorsConfig . Builder builder = SchemaValidatorsConfig . builder ();
// By default the JDK regular expression implementation which is not ECMA 262 compliant is used
// Note that setting this requires including optional dependencies
// builder.regularExpressionFactory(GraalJSRegularExpressionFactory.getInstance());
// builder.regularExpressionFactory(JoniRegularExpressionFactory.getInstance());
SchemaValidatorsConfig config = builder . build ();
// Due to the mapping the schema will be retrieved from the classpath at classpath:schema/example-main.json.
// If the schema data does not specify an $id the absolute IRI of the schema location will be used as the $id.
JsonSchema schema = jsonSchemaFactory . getSchema ( SchemaLocation . of ( "https://www.example.org/example-main.json" ), config );
String input = "{ r n "
+ " " main " : { r n "
+ " " common " : { r n "
+ " " field " : " invalidfield " r n "
+ " } r n "
+ " } r n "
+ "}" ;
Set < ValidationMessage > assertions = schema . validate ( input , InputFormat . JSON , executionContext -> {
// By default since Draft 2019-09 the format keyword only generates annotations and not assertions
executionContext . getExecutionConfig (). setFormatAssertionsEnabled ( true );
});다음 예제는 스키마가 메타 스키마에 대해 어떻게 검증되는지 보여줍니다.
이 경우 입력은 스키마이고 사용 된 스키마가 메타 스키마입니다.
초안 4, 초안 6, 초안 7, 초안 2019-09 및 2020-12 초안의 메타 스케인은 라이브러리와 번들로 제공되며 이러한 클래스 경로 리소스는 기본적으로 사용됩니다.
JsonSchemaFactory jsonSchemaFactory = JsonSchemaFactory . getInstance ( VersionFlag . V202012 );
SchemaValidatorsConfig . Builder builder = SchemaValidatorsConfig . builder ();
// By default the JDK regular expression implementation which is not ECMA 262 compliant is used
// Note that setting this requires including optional dependencies
// builder.regularExpressionFactory(GraalJSRegularExpressionFactory.getInstance());
// builder.regularExpressionFactory(JoniRegularExpressionFactory.getInstance());
SchemaValidatorsConfig config = builder . build ();
// Due to the mapping the meta-schema will be retrieved from the classpath at classpath:draft/2020-12/schema.
JsonSchema schema = jsonSchemaFactory . getSchema ( SchemaLocation . of ( SchemaId . V202012 ), config );
String input = "{ r n "
+ " " type " : " object " , r n "
+ " " properties " : { r n "
+ " " key " : { r n "
+ " " title " : " My key " , r n "
+ " " type " : " invalidtype " r n "
+ " } r n "
+ " } r n "
+ "}" ;
Set < ValidationMessage > assertions = schema . validate ( input , InputFormat . JSON , executionContext -> {
// By default since Draft 2019-09 the format keyword only generates annotations and not assertions
executionContext . getExecutionConfig (). setFormatAssertionsEnabled ( true );
});다음 유형의 결과는 라이브러리에서 생성됩니다.
| 유형 | 설명 |
|---|---|
| 주장 | 특정 입력 데이터 인스턴스에서 키워드로 생성 된 유효성 검사 오류. 이것은 일반적으로 ValidationMessage 또는 OutputUnit 에 설명되어 있습니다. 2019-09 초안 초안 이후 format 키워드는 더 이상 기본적으로 어설 션을 생성하지 않고 구성 옵션을 사용하여 구성되지 않거나 적절한 어휘를 사용하는 메타 스키마를 사용하지 않는 한 주석 만 생성합니다. |
| 주석 | 특정 입력 데이터 인스턴스에 대한 키워드로 생성 된 추가 정보. 이것은 일반적으로 OutputUnit 에 설명되어 있습니다. 주석 수집 및보고는 기본적으로 꺼져 있습니다. unevaluatedProperties 또는 unevaluatedItems 와 같은 키워드에 필요한 주석은 항상 평가 목적으로 수집되며 비활성화 할 수는 없지만 구성되지 않으면보고되지 않습니다. |
다음 정보는 두 유형의 결과를 모두 설명하는 데 사용됩니다.
| 유형 | 설명 |
|---|---|
| 평가 경로 | 이것은 루트에서 인스턴스를 평가하기 위해 스키마에 도달하기 위해 통과하는 루트에서 키 세트입니다. 여기에는 $ref 및 $dynamicRef 포함됩니다. 예를 들어. /properties/bar/$ref/properties/bar-prop |
| 스키마 위치 | 이것은 스키마의 정식 IRI와 인스턴스를 평가하는 데 사용 된 스키마에 대한 JSON 포인터 조각입니다. 예를 들어. https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop |
| 인스턴스 위치 | 이것은 평가중인 인스턴스 데이터에 대한 JSON 포인터 조각입니다. 예를 들어. /bar/bar-prop |
주장에는 다음 추가 정보가 포함되어 있습니다
| 유형 | 설명 |
|---|---|
| 메시지 | 유효성 검사 오류 메시지. |
| 암호 | 오류 코드. |
| 메시지 키 | 현지화 메시지를 생성하는 데 사용되는 메시지 키. |
| 논쟁 | 메시지를 생성하는 데 사용되는 인수. |
| 유형 | 메시지를 생성 한 키워드. |
| 재산 | 예를 들어 required 키워드에 대해 유효성 검사 오류를 일으킨 속성 이름입니다. 인스턴스 노드를 가리키기 때문에 인스턴스 위치의 일부가 아닙니다. |
| 스키마 노드 | JsonNode 스키마 위치를 가리 킵니다. 이것은 입력 데이터가 실패하게 된 스키마 데이터입니다. JSONNODEDEREADER로 JsonNodeReader 로 LocationJsonNodeFactoryFactory 사용하고 JsonNodes.tokenLocationOf(schemaNode) 사용하여 JsonSchemaFactory 를 구성하여 위치 정보를 얻을 수 있습니다. |
| 인스턴스 노드 | JsonNode 인스턴스 위치를 가리 킵니다. 이것은 유효성 검사에 실패한 입력 데이터입니다. JSONNODEDEREADER로 LocationJsonNodeFactoryFactory 를 사용하고 JsonNodes.tokenLocationOf(instanceNode) 사용하는 JsonNodeReader 로 JsonSchemaFactory 구성하여 위치 정보를 얻을 수 있습니다. |
| 오류 | 오류. |
| 세부 | Custom Keyword Validator 구현에서 설정할 수있는 추가 세부 정보. 이것은 라이브러리에서 사용되지 않습니다. |
주석에는 다음 추가 정보가 포함되어 있습니다
| 유형 | 설명 |
|---|---|
| 값 | 주석 값이 생성되었습니다 |
라이브러리는 인스턴스 및 스키마 노드의 JsonNode 인스턴스에 라인 및 열 정보를 저장하도록 구성 할 수 있습니다. 이는 성능에 부정적인 영향을 미치며 기본적으로 구성되지 않습니다.
이것은 JsonSchemaFactory 의 LocationJsonNodeFactoryFactory 사용하는 JsonNodeReader 구성하여 수행됩니다. 그런 다음 JsonLocation 정보를 JsonNodes.tokenLocationOf(jsonNode) 사용하여 검색 할 수 있습니다.
String schemaData = "{ r n "
+ " " $id " : " https://schema/myschema " , r n "
+ " " properties " : { r n "
+ " " startDate " : { r n "
+ " " format " : " date " , r n "
+ " " minLength " : 6 r n "
+ " } r n "
+ " } r n "
+ "}" ;
String inputData = "{ r n "
+ " " startDate " : " 1 " r n "
+ "}" ;
JsonSchemaFactory factory = JsonSchemaFactory . getInstance ( VersionFlag . V202012 ,
builder -> builder . jsonNodeReader ( JsonNodeReader . builder (). locationAware (). build ()));
SchemaValidatorsConfig config = SchemaValidatorsConfig . builder (). build ();
JsonSchema schema = factory . getSchema ( schemaData , InputFormat . JSON , config );
Set < ValidationMessage > messages = schema . validate ( inputData , InputFormat . JSON , executionContext -> {
executionContext . getExecutionConfig (). setFormatAssertionsEnabled ( true );
});
List < ValidationMessage > list = messages . stream (). collect ( Collectors . toList ());
ValidationMessage format = list . get ( 0 );
JsonLocation formatInstanceNodeTokenLocation = JsonNodes . tokenLocationOf ( format . getInstanceNode ());
JsonLocation formatSchemaNodeTokenLocation = JsonNodes . tokenLocationOf ( format . getSchemaNode ());
ValidationMessage minLength = list . get ( 1 );
JsonLocation minLengthInstanceNodeTokenLocation = JsonNodes . tokenLocationOf ( minLength . getInstanceNode ());
JsonLocation minLengthSchemaNodeTokenLocation = JsonNodes . tokenLocationOf ( minLength . getSchemaNode ());
assertEquals ( "format" , format . getType ());
assertEquals ( "date" , format . getSchemaNode (). asText ());
assertEquals ( 5 , formatSchemaNodeTokenLocation . getLineNr ());
assertEquals ( 17 , formatSchemaNodeTokenLocation . getColumnNr ());
assertEquals ( "1" , format . getInstanceNode (). asText ());
assertEquals ( 2 , formatInstanceNodeTokenLocation . getLineNr ());
assertEquals ( 16 , formatInstanceNodeTokenLocation . getColumnNr ());
assertEquals ( "minLength" , minLength . getType ());
assertEquals ( "6" , minLength . getSchemaNode (). asText ());
assertEquals ( 6 , minLengthSchemaNodeTokenLocation . getLineNr ());
assertEquals ( 20 , minLengthSchemaNodeTokenLocation . getColumnNr ());
assertEquals ( "1" , minLength . getInstanceNode (). asText ());
assertEquals ( 2 , minLengthInstanceNodeTokenLocation . getLineNr ());
assertEquals ( 16 , minLengthInstanceNodeTokenLocation . getColumnNr ());
assertEquals ( 16 , minLengthInstanceNodeTokenLocation . getColumnNr ());이 라이브러리는 JSON 스키마 검증 및 주석에 대한 기계 읽을 수있는 출력 사양에 정의 된 플래그, 목록 및 계층 적 출력 형식을 구현합니다.
목록과 계층 적 출력 형식은 특히 시스템이 특정 결과에 도달하는 방법을 이해하는 데 특히 도움이됩니다.
| 출력 형식 | 설명 |
|---|---|
| 기본 | 어설 션 목록을 생성합니다. |
| 부울 | 유효성 검사가 성공하면 true 반환합니다. 이 출력 형식에 대해 FAST FAST 옵션이 기본적으로 켜집니다. |
| 깃발 | 유효성 검사가 성공하면 valid true OutputFlag 개체를 반환합니다. 이 출력 형식에 대해 FAST FAST 옵션이 기본적으로 켜집니다. |
| 목록 | 어설 션과 주석이있는 OutputUnit 객체 목록이있는 details 있는 OutputUnit 객체를 반환합니다. 주석은 기본적으로 수집되지 않으며 성능에 영향을 미치므로 활성화되어야합니다. |
| 계층 적 | 어설 션 및 주석이있는 평가 경로에 대한 OutputUnit 객체의 계층 구조로 OutputUnit 객체를 반환합니다. 주석은 기본적으로 수집되지 않으며 성능에 영향을 미치므로 활성화되어야합니다. |
다음 예제는 주석 수집 및보고가 ON을 사용하여 계층 적 출력 형식을 생성하는 방법을 보여줍니다.
JsonSchemaFactory factory = JsonSchemaFactory . getInstance ( VersionFlag . V202012 );
SchemaValidatorsConfig config = SchemaValidatorsConfig (). builder (). formatAssertionsEnabled ( true ). build ();
JsonSchema schema = factory . getSchema ( SchemaLocation . of ( "https://json-schema.org/schemas/example" ), config );
OutputUnit outputUnit = schema . validate ( inputData , InputFormat . JSON , OutputFormat . HIERARCHICAL , executionContext -> {
executionContext . getExecutionConfig (). setAnnotationCollectionEnabled ( true );
executionContext . getExecutionConfig (). setAnnotationCollectionFilter ( keyword -> true );
});다음은 계층 형식의 샘플 출력입니다.
{
"valid" : false ,
"evaluationPath" : " " ,
"schemaLocation" : " https://json-schema.org/schemas/example# " ,
"instanceLocation" : " " ,
"droppedAnnotations" : {
"properties" : [ " foo " , " bar " ],
"title" : " root "
},
"details" : [ {
"valid" : false ,
"evaluationPath" : " /properties/foo/allOf/0 " ,
"schemaLocation" : " https://json-schema.org/schemas/example#/properties/foo/allOf/0 " ,
"instanceLocation" : " /foo " ,
"errors" : {
"required" : " required property 'unspecified-prop' not found "
}
}, {
"valid" : false ,
"evaluationPath" : " /properties/foo/allOf/1 " ,
"schemaLocation" : " https://json-schema.org/schemas/example#/properties/foo/allOf/1 " ,
"instanceLocation" : " /foo " ,
"droppedAnnotations" : {
"properties" : [ " foo-prop " ],
"title" : " foo-title " ,
"additionalProperties" : [ " foo-prop " , " other-prop " ]
},
"details" : [ {
"valid" : false ,
"evaluationPath" : " /properties/foo/allOf/1/properties/foo-prop " ,
"schemaLocation" : " https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop " ,
"instanceLocation" : " /foo/foo-prop " ,
"errors" : {
"const" : " must be a constant value 1 "
},
"droppedAnnotations" : {
"title" : " foo-prop-title "
}
} ]
}, {
"valid" : false ,
"evaluationPath" : " /properties/bar/$ref " ,
"schemaLocation" : " https://json-schema.org/schemas/example#/$defs/bar " ,
"instanceLocation" : " /bar " ,
"droppedAnnotations" : {
"properties" : [ " bar-prop " ],
"title" : " bar-title "
},
"details" : [ {
"valid" : false ,
"evaluationPath" : " /properties/bar/$ref/properties/bar-prop " ,
"schemaLocation" : " https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop " ,
"instanceLocation" : " /bar/bar-prop " ,
"errors" : {
"minimum" : " must have a minimum value of 10 "
},
"droppedAnnotations" : {
"title" : " bar-prop-title "
}
} ]
} ]
}| 이름 | 설명 | 기본값 |
|---|---|---|
annotationCollectionEnabled | 처리 중에 주석이 수집되는지 여부를 제어합니다. 주석을 수집하면 성능에 부정적인 영향을 미칩니다. | false |
annotationCollectionFilter | 술어는 주석을 수집하고보고 할 키워드를 제어하는 데 사용됩니다. 이를 위해서는 annotationCollectionEnabled true 이어야합니다. | keyword -> false |
locale | ValidationMessage 에서 메시지를 생성하는 데 사용할 로케일. 이 값은 각 실행에 대해 SchemaValidatorsConfig 에서 복사됩니다. | Locale.getDefault() |
failFast | 어설 션이 생성 될 때 즉시 실패를 반환할지 여부. 이 값은 각 실행에 대해 SchemaValidatorsConfig 에서 복사되지만 부울 및 플래그 출력 형식에 대해 자동으로 true 로 설정됩니다. | false |
formatAssertionsEnabled | 기본값은 4에서 초안 7에서 7 초안까지 형식의 어설 션을 생성하고 2019-09 초안에서 주석 만 생성하는 것입니다. true 또는 false 로 설정하면 기본 동작이 무시됩니다. | null |
debugEnabled | 처리시 노드 정보를 로깅하기 위해 디버그 로깅이 활성화되어 있는지 여부를 제어합니다. 이것은 성능에 영향을 미치는 많은 로그를 생성합니다. | false |
| 이름 | 설명 | 기본값 |
|---|---|---|
applyDefaultsStrategy | 누락되거나 널 노드가 발생할 때 걷는 경우 기본값을 적용하는 전략이 발생합니다. | ApplyDefaultsStrategy.EMPTY_APPLY_DEFAULTS_STRATEGY |
cacheRefs | 심판에서로드 된 스키마가 캐싱되고 후속 실행에 대해 재사용되는지 여부. 이것을 false 로 설정하면 성능에 영향을 미치지 만 oneOf anyOf allOf 와 같은 여러 중첩 어플리케이터가 사용되는 경우 캐시에 대한 높은 메모리 사용을 방지하기 위해 필요한 것입니다. | true |
discriminatorKeywordEnabled | discriminator 키워드가 OpenAPI 3에 따라 처리되는지 여부. | false |
errorMessageKeyword | 스키마의 사용자 정의 오류 메시지에 사용할 키워드. 설정하지 않으면이 기능이 비활성화됩니다. 이것은 일반적으로 errorMessage 또는 message 로 설정됩니다. | null |
executionContextCustomizer | 이를 사용하여 각 유효성 검사 실행에 대해 JsonSchema 에서 생성 한 ExecutionContext 사용자 정의 할 수 있습니다. | null |
failFast | 어설 션이 생성 될 때 즉시 실패를 반환할지 여부. | false |
formatAssertionsEnabled | 기본값은 4에서 초안 7에서 7 초안까지 형식의 어설 션을 생성하고 2019-09 초안에서 주석 만 생성하는 것입니다. true 또는 false 로 설정하면 기본 동작이 무시됩니다. | null |
javaSemantics | Java Semantics가 type 키워드에 사용되는지 여부 | false |
locale | ValidationMessage 에서 메시지를 생성하는 데 사용할 로케일. | Locale.getDefault() |
losslessNarrowing | type 키워드에 무손실 좁아짐이 사용되는지 여부 | false |
messageSource | 이것은 로케일 특정 메시지를 검색하는 데 사용됩니다. | DefaultMessageSource.getInstance() |
nullableKeywordEnabled | OpenApi 3.0에 따라 nullable 키워드가 처리되는지 여부. 이는 enum 및 type 키워드에 영향을 미칩니다. | false |
pathType | 인스턴스 위치 및 평가 경로를보고하는 데 사용할 경로 유형. JSON PATH를 사용하려면 PathType.JSON_PATH 로 설정하십시오. | PathType.JSON_POINTER |
preloadJsonSchema | 입력을 처리하기 전에 스키마가 사전로드 될지 여부. 이것은 메모리를 사용하지만 검증의 실행이 더 빠릅니다. | true |
preloadJsonSchemaRefMaxNestingDepth | 사전로드 할 때 예압에 대한 평가 경로의 최대 깊이. | 40 |
readOnly | 스키마가 읽는 지 여부. 이것은 readOnly 키워드에 영향을 미칩니다. | null |
regularExpressionFactory | 예를 들어 JoniRegularExpressionFactory 또는 GraalJSRegularExpressionFactory 와 같은 정기적 인 표현을 만드는 데 사용하는 공장. 이를 위해서는 종속성이 프로젝트에 수동으로 추가되어야합니다. 그렇지 않으면 ClassNotFoundException 이 발생합니다. | JDKRegularExpressionFactory.getInstance() |
schemaIdValidator | $id 값이 검증되는 방식을 사용자 정의하는 데 사용됩니다. 기본 구현은 기본 IRI가 지정되지 않고 루트 스키마에서 비 변제 IRI $id 값을 허용하는 비어있는 단편을 허용합니다. | JsonSchemaIdValidator.DEFAULT |
strict | 키워드가 검증에서 엄격한 지 여부에 따라 설정됩니다. 이것이하는 것은 개별 유효성 검사기에 달려 있습니다. | |
typeLoose | 유형이 느슨한 방식으로 해석되는지 여부. true로 설정되면 단일 값을 크기 1 어레이로 해석 할 수 있습니다. 문자열은 또한 숫자, 정수 또는 부울로 해석 될 수 있습니다. | false |
writeOnly | 스키마가 작성된 지 여부. 이것은 writeOnly 키워드에 영향을 미칩니다. | null |
라이브러리가 스키마 팩토리에서 스키마를 생성하면 평가 경로에서 각 위치에 대해 고유 한 유효성 검사기 인스턴스를 만듭니다. 즉, 동일한 스키마 위치를 참조하는 다른 $ref 있는 경우 각 평가 경로마다 다른 유효성 검사 인스턴스가 생성됩니다.
스키마가 생성되면 라이브러리는 기본적으로 필요한 모든 유효성 검사기를 자동으로 사전로드하고 참조를 해결합니다. SchemaValidatorsConfig 의 preloadJsonSchema 옵션으로 비활성화 할 수 있습니다. 이 시점에서 참조를 해결할 수없는 경우 예외가 발생하지 않습니다. 순환적인 참조가있는 경우 첫 번째주기 만 사전로드됩니다. 원격 참조를 모두 해결할 수 있으려면 JsonSchema 에서 initializeValidators 메소드를 호출해야합니다.
JsonSchemaFactory 의 인스턴스 및 IT로부터 생성 된 JsonSchema 는 구성이 수정되지 않고 캐시 및 재사용 된 경우 스레드 안전하도록 설계되었습니다. JsonSchema 재사용하지 않으면 스키마 데이터가 생성 된 유효성 검사기 인스턴스와 참조가 해결 될 필요가 있음을 의미합니다. 참조가 해결되면 생성 된 유효성 검사기가 캐시됩니다. 참조가 깊게 중첩 된 스키마의 경우, 유효성 검사기에 필요한 메모리가 매우 높을 수 있으며,이 경우 SchemaValidatorsConfig 에서 cacheRefs 옵션을 사용하여 캐싱을 비활성화해야 할 수 있습니다. 이를 비활성화하면 성능에 영향을 미치는 각 유효성 검사 실행에 대해 참조의 유효성 검사기를 다시 만들어야합니다.
주석을 수집하면 유효성 검사 성능에 부정적인 영향을 미칩니다.
초기 초안 사양에는 성능에 잠재적으로 영향을 줄 수있는 키워드가 적습니다. 예를 들어, unevaluatedProperties 또는 unevaluatedItems 키워드를 사용하면 properties 또는 items 유효성 검사기와 같은 관련 유효성 검사기에서 주석 수집이 트리거됩니다.
그렇다고해서 이후의 초안 사양이있는 스키마를 사용하면 자동으로 성능 영향이 발생한다는 의미는 아닙니다. 예를 들어, properties Validator는 주석을 수집 해야하는지 확인하기 위해 점검을 수행하고 메타 스키마에 unevaluatedProperties unevaluatedProperties 키워드가 포함되어 있는지 확인하고 평가 경로에 인접 해지는지 확인합니다.
라이브러리는로드중인 스키마가 신뢰한다고 가정합니다. 이 보안 모델은 스키마가 클래스 경로의 응용 프로그램과 함께 묶인 사용 사례를 가정합니다.
| 문제 | 설명 | 완화 |
|---|---|---|
| 스키마로드 | 기본적으로 라이브러리는 필요한 경우 클래스 경로와 인터넷을 통해 스키마를로드합니다. | 스키마 검색을 허용하지 않도록 DisallowSchemaLoader 구성 할 수 있습니다. 또는 허용 된 검색 아이리스를 제한하도록 AllowSchemaLoader 구성 할 수 있습니다. |
| 스키마 캐싱 | 기본적으로 도서관은 스키마를로드시 참조를 예압 및 캐시합니다. 사전로드 스키마시 최대 중첩 깊이가 있지만 서버에서 많은 메모리를 소비하는 팬이있는 스키마를 구성 할 수 있습니다. | SchemaValidatorsConfig 에서 cacheRefs 옵션을 false로 설정하십시오. |
| 정규 표현 | 주어진 정규 표현이 서비스 거부 (REDOS)에 취약 할 수있는 경우 라이브러리는 검증되지 않습니다. | AllowRegularExpressionFactory 허용되는 일반 표현식에서 검증을 수행하도록 구성 할 수 있습니다. |
| 유효성 검사 오류 | 기본적으로 라이브러리는 모든 유효성 검사 오류를 반환하려고 시도합니다. 많은 수의 스키마를 가진 allOf 와 같은 어플리케이터를 사용하면 메모리를 취하는 많은 검증 오류가 발생할 수 있습니다. | SchemaValidatorsConfig 에서 failFast 옵션을 설정하여 첫 번째 오류가 발생하면 즉시 반환됩니다. OutputFormat.BOOLEAN 또는 OutputFormat.FLAG 도 사용할 수 있습니다. |
Light-Rest-4J, Light-GraphQL-4J 및 Light-Hybrid-4J는이 라이브러리를 사용하여 사양에 따라 요청 및 응답을 검증합니다. Spring Boot와 같은 다른 프레임 워크를 사용하는 경우 OpenAPI 3.0 사양을 기반으로 Generic OpenAPI 3.0 유효성 검사기 인 OpenApivalidator를 사용할 수 있습니다.
이 라이브러리를 사용하는 프로젝트가있는 경우 PR을 제출하여 아래 프로젝트를 추가하십시오.
이 프로젝트에 기여한 다음 사람들에게 감사합니다. 이 라이브러리를 사용하는 경우 기고자 중 한 명을 후원하는 것을 고려하십시오.
@stevehu
@Prashanth-Chaitanya
@fdutton
@Valfirst
@balloonwen
@jiachen1120
@ddobrin
@eskabetxe
@ehrmann
@prashanthjos
@subhajitdas298
@fwiesner
@rhwood
@jawaff
@nitin1891
모든 기고자는 https://github.com/networknt/json-schema-validator/graphs/contripors를 방문하십시오
기고자 인 경우 Github 스폰서에 가입하여 PR을 통해 스폰서 대시 보드로 링크를 전환하십시오.
