json schema validator
1.5.3
Переполнение стека | Google Group | Чат с друтком | Subreddit | YouTube | Документация | Руководство по взносу |
Это реализация Java схемы схемы JSON Core Draft V4, V6, V7, V2019-09 и V2020-12 для проверки схемы JSON. Эта реализация поддерживает настройку мета-схемы, словари, ключевые слова и форматы.
Кроме того, подтверждение запроса/ответа OpenAPI 3 поддерживается с использованием соответствующей мета-схемы. Для пользователей, которые хотят собирать информацию из узла JSON на основе схемы, ходунки могут помочь. Используемый анализатор JSON - это диапазон Джексона. Поскольку это ключевой компонент в нашей структуре микросервисов Light-4J для проверки запроса/ответа на спецификацию OpenAPI для схемы Light-REST-4J и RPC для Light-Hybrid-4J во время выполнения, производительность является наиболее важным аспектом в дизайне.
Информацию о поддержке совместимости для каждой версии, включая известные проблемы, можно найти в совместимости с документом JSON Schema Versions.
Поскольку проект 2019-09 Ключевое слово format генерирует только аннотации по умолчанию и не генерирует утверждения.
Это поведение может быть переопределено, чтобы генерировать утверждения, установив setFormatAssertionsEnabled true в SchemaValidatorsConfig или ExecutionConfig .
Эта библиотека может содержать нарушающие изменения в minor выпусках версий, которые могут потребовать изменения кода.
Информацию о заметных или нарушающих изменениях при обновлении библиотеки можно найти в документе «Обновление новых версий».
На странице релизов будет содержать информацию о последних версиях.
Проект сравнения валидации схемы JSON от Creek имеет информативное сравнение реализаций валидации схемы на основе JVM, которые сравнивают как функциональные, так и характеристики производительности ряда различных реализаций Java.
Проект Bowtie имеет отчет, в котором сравниваются функциональные характеристики различных реализаций, включая реализации не Java, но не выполняет никаких сравнительных показателей эффективности.
Это должна быть самая быстрая реализация валидатора схемой JAVA JSON.
Ниже приведены эталонные результаты проекта Valdator Perftest Proftator схемы JSON, который использует жгут Java Microbenchmark.
Обратите внимание, что контрольные результаты сильно зависят от рабочих нагрузок входных данных и схем, используемых для проверки.
В этом случае эта рабочая нагрузка использует спецификацию 4. и в значительной степени проверяет производительность оценки ключевого слова properties . Вы можете ссылаться на результаты сравнения эффективности реализаций валидации схемы JSON на основе JSM для контрольных результатов для более типичных рабочих нагрузок
Если производительность является важным фактором, конкретные образцы рабочих нагрузок должны быть сравнены, так как существуют различные характеристики производительности, когда используются определенные ключевые слова. Например, использование ключевых слов 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. Поскольку тесты постоянно добавляются в набор, эти результаты тестов могут не быть актуальными.
| Реализации | Общий | DRACK_03 | DRACK_04 | DRACK_06 | DRACK_07 | DRACK_2019_09 | DRACK_2020_12 |
|---|---|---|---|---|---|---|---|
| Сеть | Пропуск: 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%) |
JoniRegularExpressionFactory для тестов regex pattern и format . В этой библиотеке используется Джексон, который является анализатором Java JSON, который широко используется в других проектах. Если вы уже используете анализатор Джексона в своем проекте, естественно выбирать эту библиотеку над другими для проверки схемы.
Библиотека работает с JSON и YAML по определениям схемы и входных данных.
Спецификация OpenAPI 3.0 использует схему JSON для проверки запроса/ответа, но есть некоторые различия. С помощью файла конфигурации вы можете разрешить библиотеку работать с валидацией OpenAPI 3.0.
В соответствии с принципом дизайна платформы Light, эта библиотека имеет минимальные зависимости, чтобы гарантировать, что при ее использовании нет конфликтов зависимостей.
Ниже приведены зависимости, которые будут автоматически включены, когда эта библиотека будет включена.
< 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 > Зависимость от времени Ethlo может быть исключена, если точная проверка формата date-time не требуется. Затем в формате 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 >Эта библиотека очень активна со многими участниками. Новые функции и исправления ошибок быстро обрабатываются членами команды. Поскольку это важная зависимость структуры Light-4J в той же организации GitHub, она будет развиваться и сохраняться вместе с рамками.
Библиотека поддерживает Java 8 и UP. Если вы хотите построить из исходного кода, вам нужно установить 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' );
}В следующем примере демонстрируется, как входные данные подтверждены с схемой. Он включает в себя следующие шаги.
$id в поисковый URI с использованием schemaMappers .schemaLoaders . Например, Map<String, String> schemas , содержащие отображение URI -URI с данными схемы в качестве String , настройка с использованием builder.schemaLoaders(schemaLoaders -> schemaLoaders.schemas(schemas)) . Это также принимает 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 |
| Расположение схемы | Это канонический Ири схемы плюс фрагмент указателя JSON для схемы, которая использовалась для оценки экземпляра. например. https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop |
| Местоположение экземпляра | Это фрагмент указателя JSON к данным экземпляра, которые оценивались. например. /bar/bar-prop |
Утверждения содержит следующую дополнительную информацию
| Тип | Описание |
|---|---|
| Сообщение | Сообщение об ошибке проверки. |
| Код | Код ошибки. |
| Ключ сообщения | Ключ сообщения, используемый для генерации сообщения для локализации. |
| Аргументы | Аргументы, используемые для генерации сообщения. |
| Тип | Ключевое слово, которое сгенерировало сообщение. |
| Свойство | Имя свойства, которое вызвало ошибку проверки, например, для required ключевого слова. Обратите внимание, что это не является частью местоположения экземпляра, так как это указывает на узел экземпляра. |
| Узел схемы | JsonNode , на который указал местоположение схемы. Это данные схемы, которые заставили входных данных сбой. Можно получить информацию о местоположении, настройка JsonSchemaFactory с помощью JsonNodeReader , который использует LocationJsonNodeFactoryFactory и использует JsonNodes.tokenLocationOf(schemaNode) . |
| Узел экземпляра | JsonNode на который указал местоположение экземпляра. Это входные данные, которые не удалились. Можно получить информацию о местоположении, настройка JsonSchemaFactory с помощью JsonNodeReader , который использует LocationJsonNodeFactoryFactory и использует JsonNodes.tokenLocationOf(instanceNode) . |
| Ошибка | Ошибка. |
| Подробности | Дополнительные сведения, которые могут быть установлены с помощью пользовательских реализаций валидаторов ключевых слов. Это не используется библиотекой. |
Аннотация содержит следующую дополнительную информацию
| Тип | Описание |
|---|---|
| Ценить | Сгенерированное значение аннотации |
Библиотека может быть настроена для хранения информации о строке и столбцах в экземплярах JsonNode для экземпляров и узлов схемы. Это отрицательно повлияет на производительность и не настроено по умолчанию.
Это делается путем настройки JsonNodeReader , который использует LocationJsonNodeFactoryFactory на JsonSchemaFactory . Затем информация 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 если проверка успешна. Обратите внимание, что опция Fail Fast включена по умолчанию для этого формата вывода. |
| Флаг | Возвращает объект OutputFlag с valid , имеющим true , если проверка успешна. Обратите внимание, что опция Fail Fast включена по умолчанию для этого формата вывода. |
| Список | Возвращает объект OutputUnit с details со списком объектов OutputUnit с утверждениями и аннотациями. Обратите внимание, что аннотации не собираются по умолчанию и должны быть включены, поскольку это повлияет на производительность. |
| Иерархический | Возвращает объект OutputUnit с иерархией объектов OutputUnit для пути оценки с утверждениями и аннотациями. Обратите внимание, что аннотации не собираются по умолчанию и должны быть включены, поскольку это повлияет на производительность. |
В следующем примере показано, как генерировать иерархический выходной формат с помощью сбора аннотаций и отчетов, включенных и включенных форматов.
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 и для создания аннотаций только из проекта 2019-09. Настройка на true или false будет переопределить поведение по умолчанию. | null |
debugEnabled | Управляет, включена ли регистрация отладки для регистрации информации о узле при обработке. Обратите внимание, что это генерирует много журналов, которые повлияют на производительность. | false |
| Имя | Описание | Значение по умолчанию |
|---|---|---|
applyDefaultsStrategy | Стратегия применения по умолчанию при ходьбе при отсутствии или нулевых узлах встречается. | ApplyDefaultsStrategy.EMPTY_APPLY_DEFAULTS_STRATEGY |
cacheRefs | Будут ли схемы, загруженные из ссылок, кэшированы и использованы повторно для последующих пробежек. Установка этого на false будет влиять на производительность, но может быть необходимым, чтобы предотвратить высокое использование памяти для кэша, если используются несколько вложенных аппликаторов, таких как anyOf , oneOf и allOf . | true |
discriminatorKeywordEnabled | Будет ли ключевое слово discriminator обрабатывается в соответствии с OpenAPI 3. | false |
errorMessageKeyword | Ключевое слово, которое можно использовать для пользовательских сообщений об ошибках в схеме. Если не установить, эти функции отключены. Обычно это установлено на errorMessage или message . | null |
executionContextCustomizer | Это может быть использовано для настройки ExecutionContext сгенерированного JsonSchema для каждого запуска проверки. | null |
failFast | Стоит ли сбой вернуть сбой, когда генерируется утверждение. | false |
formatAssertionsEnabled | По умолчанию состоит в том, чтобы генерировать утверждения формата из проекта 4 до проекта 7 и для создания аннотаций только из проекта 2019-09. Настройка на true или false будет переопределить поведение по умолчанию. | null |
javaSemantics | Используется ли Java Semantics для ключевого слова type . | false |
locale | Локаль для использования для генерации сообщений в ValidationMessage . | Locale.getDefault() |
losslessNarrowing | Используется ли сужение без потерь для ключевого слова type . | false |
messageSource | Это используется для извлечения конкретных локальных сообщений. | DefaultMessageSource.getInstance() |
nullableKeywordEnabled | Обрабатывается ли nullable ключевое слово в соответствии с OpenAPI 3.0. Это влияет на enum и type ключевых слов. | false |
pathType | Тип пути, который можно использовать для сообщения о местоположении экземпляра и пути оценки. Установите на PathType.JSON_PATH для использования пути JSON. | 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 , которые ссылаются на одно и то же местоположение схемы, для каждого пути оценки создаются различные экземпляры валидатора.
Когда схема создана, библиотека по умолчанию будет автоматически загружать все необходимые валидаторы и разрешать ссылки. Это может быть отключено с помощью опции preloadJsonSchema в SchemaValidatorsConfig . На этом этапе не будет исключено, что ссылка не может быть решена. Если есть циклические ссылки, будет предварительно загружен только первый цикл. Если вы хотите убедиться, что все удаленные ссылки могут быть разрешены, метод initializeValidators должен быть вызван на JsonSchema , который будет выбросить исключение, если есть ссылки, которые не могут быть разрешены.
Экземпляры для JsonSchemaFactory и JsonSchema , созданных из него, предназначены для того, чтобы быть защищенными потоком при условии, что ее конфигурация не модифицирована и должна быть кэширована и повторно используется. Не повторное использование JsonSchema означает, что данные схемы должны повторяться с помощью созданных экземпляров и разрешенных ссылок. Когда ссылки будут разрешены, созданные валидаторы будут кэшированы. Для схем, которые имеют глубоко вложенные ссылки, память, необходимая для валидаторов, может быть очень высокой, и в этом случае кеширование может потребоваться отключено, используя опцию cacheRefs в SchemaValidatorsConfig . Отключение этого будет означать, что валидаторы из ссылок должны быть воссозданы для каждого прогона валидации, что повлияет на производительность.
Сбор аннотаций будет отрицательно повлиять на производительность проверки.
Более ранние характеристики проекта содержат меньше ключевых слов, которые потенциально могут повлиять на производительность. Например, использование ключевых слов unevaluatedProperties или unevaluatedItems будет запустить сбор аннотаций в соответствующих валидаторах, таких как properties или items .
Это не означает, что использование схемы с более поздним черновым спецификацией автоматически приведет к влиянию на производительность. Например, валидатор properties будет выполнять чеки, чтобы определить, необходимо ли собирать аннотации, и проверяет, содержит ли мета-схема ключевое слово unevaluatedProperties и существует ли ключевое слово unevaluatedProperties прилегающее к пути оценки.
Библиотека предполагает, что загруженные схемы доверяют. Эта модель безопасности предполагает вариант использования, когда схемы связаны с приложением на классе.
| Проблема | Описание | Смягчение |
|---|---|---|
| Загрузка схемы | Библиотека по умолчанию будет загружать схемы с трассы класса и через Интернет, если это необходимо. | DisallowSchemaLoader может быть настроен, чтобы не разрешать поиск схемы. В качестве альтернативы можно настроить AllowSchemaLoader , чтобы ограничить разрешенную радужную оболочку. |
| Схема кэширование | Библиотека по умолчанию предварительной нагрузки и кэширует ссылки при загрузке схем. Хотя есть максимальная глубина гнездования, когда схемы предварительной загрузки по -прежнему можно построить схему, в которой есть вентилятор, которая потребляет много памяти с сервера. | Установите опцию cacheRefs в SchemaValidatorsConfig на false. |
| Регулярные выражения | Библиотека не подтверждает, воспринимается ли данное регулярное выражение к отрицанию обслуживания (REDOS). | AllowRegularExpressionFactory может быть настроен для выполнения проверки на регулярные выражения, которые разрешены. |
| Ошибки проверки | Библиотека по умолчанию пытается вернуть все ошибки проверки. Использование аппликаторов, таких как allOf , с большим количеством схем, может привести к большому количеству ошибок проверки, которые будут восприняты память. | Установите опцию failFast в SchemaValidatorsConfig , чтобы немедленно вернуться, когда встречается первая ошибка. OutputFormat.BOOLEAN или OutputFormat.FLAG также может использоваться. |
Light-Rest-4J, Light-GraphQL-4J и Light-Hybrid-4J используют эту библиотеку для проверки запроса и ответа на основе спецификаций. Если вы используете другие фреймворки, такие как Spring Boot, вы можете использовать OpenApivalidator, общий валидатор OpenAPI 3.0 на основе спецификации OpenAPI 3.0.
Если у вас есть проект, использующий эту библиотеку, отправьте 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/contributors
Если вы являетесь участником, присоединяйтесь к спонсорам GitHub и переключите ссылку на панель панели спонсоров через PR.
