json schema validator
1.5.3
Pilha Overflow | Grupo do Google | Chat gitter | Subreddit | YouTube | Documentação | Guia de contribuição |
Esta é uma implementação Java do JSON Schema Core Draft V4, V6, V7, V2019-09 e V2020-12 especificação para validação de esquema JSON. Esta implementação suporta meta-esquemas personalizados, vocabulários, palavras-chave e formatos.
Além disso, a validação de solicitação/resposta do OpenAPI 3 é suportada com o uso do meta-esquema apropriado. Para os usuários que desejam coletar informações de um nó JSON com base no esquema, os caminhantes podem ajudar. O analisador JSON usado é o analisador de Jackson. Como é um componente essencial em nossa estrutura de microsserviços Light-4J para validar a solicitação/resposta contra a especificação OpenAPI para o esquema de luz-restos-4J e RPC para o híbrido leve-4J em tempo de execução, o desempenho é o aspecto mais importante do design.
As informações sobre o suporte de compatibilidade para cada versão, incluindo questões conhecidas, podem ser encontradas no documento de compatibilidade com o JSON Schema Versions.
Desde o rascunho de 2019-09, a palavra-chave format gera apenas anotações por padrão e não gera afirmações.
Esse comportamento pode ser substituído para gerar afirmações, definindo o setFormatAssertionsEnabled como true em SchemaValidatorsConfig ou ExecutionConfig .
Esta biblioteca pode conter alterações de ruptura nas versões minor da versão que podem exigir alterações de código.
Informações sobre alterações notáveis ou interrompidas ao atualizar a biblioteca podem ser encontradas no documento de atualização para novas versões.
A página de lançamentos conterá informações sobre as versões mais recentes.
O projeto de comparação de validação de esquema JSON de Creek possui uma comparação informativa das implementações de validação de esquema baseadas em JVM, que compara as características funcionais e de desempenho de várias implementações Java diferentes.
O projeto Bowtie possui um relatório que compara as características funcionais de diferentes implementações, incluindo implementações que não são de Java, mas não fazem nenhum benchmarking de desempenho.
Esta deve ser a implementação do Validador de Esquema JASE mais rápida JASE.
A seguir, são apresentados os resultados do referência do projeto Perftest Project do Validador de Esquema JSON que usa o arnês Java Microbenchmark.
Observe que os resultados de referência são altamente dependentes das cargas de trabalho de dados de entrada e esquemas usados para a validação.
Nesse caso, essa carga de trabalho está usando o rascunho de 4 especificações e testa amplamente o desempenho da avaliação da palavra -chave properties . Você pode se referir aos resultados da comparação de desempenho de implementações de validação de esquema JVM baseadas em JVM para resultados de referência para cargas de trabalho mais típicas
Se o desempenho for uma consideração importante, as cargas de trabalho de amostra específicas devem ser comparadas, pois existem diferentes características de desempenho quando certas palavras -chave são usadas. Por exemplo, o uso das palavras -chave unevaluatedProperties ou unevaluatedItems acionará a coleta de anotação nos validadores relacionados, como as properties ou os validadores items , e a coleção de anotação afetará adversamente o desempenho.
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
Esta implementação é testada contra o JSON Schema Test Suite. Como os testes são continuamente adicionados à suíte, esses resultados dos testes podem não estar atualizados.
| Implementações | Geral | Draft_03 | Draft_04 | Draft_06 | Draft_07 | Draft_2019_09 | Draft_2020_12 |
|---|---|---|---|---|---|---|---|
| Networknt | PASSE: R: 4803 (100,0%) o: 2372 (100,0%) Falha: R: 0 (0,0%) O: 0 (0,0%) | PASSE: R: 610 (100,0%) o: 251 (100,0%) Falha: R: 0 (0,0%) O: 0 (0,0%) | PASSE: R: 822 (100,0%) o: 318 (100,0%) Falha: R: 0 (0,0%) O: 0 (0,0%) | PASSE: R: 906 (100,0%) o: 541 (100,0%) Falha: R: 0 (0,0%) O: 0 (0,0%) | PASSE: R: 1220 (100,0%) o: 625 (100,0%) Falha: R: 0 (0,0%) O: 0 (0,0%) | PASSE: R: 1245 (100,0%) o: 637 (100,0%) Falha: R: 0 (0,0%) O: 0 (0,0%) |
JoniRegularExpressionFactory para os testes regex pattern e format . Esta biblioteca usa Jackson, que é um analisador Java JSON que é amplamente utilizado em outros projetos. Se você já está usando o analisador Jackson em seu projeto, é natural escolher esta biblioteca em detrimento de outras pessoas para validação de esquema.
A biblioteca trabalha com JSON e YAML nas definições de esquema e nos dados de entrada.
A especificação OpenAPI 3.0 está usando o esquema JSON para validar a solicitação/resposta, mas existem algumas diferenças. Com um arquivo de configuração, você pode permitir que a biblioteca trabalhe com a validação do OpenAPI 3.0.
Seguindo o princípio do design da plataforma de luz, esta biblioteca possui dependências mínimas para garantir que não haja conflitos de dependência ao usá -la.
A seguir, são apresentadas as dependências que serão incluídas automaticamente quando esta biblioteca estiver incluída.
< 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 >A seguir, são apresentadas as dependências opcionais que podem ser necessárias para certas opções.
Eles não são incluídos automaticamente e a definição da opção relevante sem adicionar a biblioteca resultará em uma 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 >A seguir, são necessárias dependências necessárias que são incluídas automaticamente, mas podem ser explicitamente excluídas se não forem necessárias.
A dependência da YAML pode ser excluída se isso não for necessário. A tentativa de processar esquemas ou entradas que são YAML resultará em uma 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 > A dependência do tempo da Ethlo pode ser excluída se a validação precisa do formato date-time não for necessária. O formato date-time usará java.time.OffsetDateTime para determinar se o date-time é válido.
< dependency >
< groupId >com.networknt</ groupId >
< artifactId >json-schema-validator</ artifactId >
< exclusions >
< exclusion >
< groupId >com.ethlo.time</ groupId >
< artifactId >itu</ artifactId >
</ exclusion >
</ exclusions >
</ dependency >Esta biblioteca é muito ativa com muitos colaboradores. Novos recursos e correções de bugs são tratados rapidamente pelos membros da equipe. Por ser uma dependência essencial da estrutura do Light-4J na mesma organização do GitHub, ela será evoluída e mantida junto com a estrutura.
A biblioteca suporta Java 8 ou mais. Se você deseja construir a partir do código -fonte, precisará instalar o JDK 8 localmente. Para suportar a versão múltipla do JDK, você pode usar o SDKMAN
Este pacote está disponível no 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' );
}O exemplo a seguir demonstra como as entradas são validadas em relação a um esquema. Compreende as etapas a seguir.
$id para um URI de recuperação usando schemaMappers .schemaLoaders . Por exemplo, um Map<String, String> schemas contendo um mapeamento de dados de URI de recuperação para esquema como uma String pode, configurada usando builder.schemaLoaders(schemaLoaders -> schemaLoaders.schemas(schemas)) . Isso também aceita uma 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 );
});O exemplo a seguir demonstra como um esquema é validado em relação a um meta-esquema.
Na verdade, é o mesmo que validar as entradas em relação a um esquema, exceto neste caso, a entrada é o esquema e o esquema usado é o meta-esquema.
Observe que os meta-schemas para o Draft 4, Draft 6, Draft 7, Draft 2019-09 e Draft 2020-12 estão incluídos na biblioteca e esses recursos de patrimônio de classe serão usados por padrão.
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 );
});Os seguintes tipos de resultados são gerados pela biblioteca.
| Tipo | Descrição |
|---|---|
| Afirmações | Erros de validação gerados por uma palavra -chave em uma instância de dados de entrada específica. Isso geralmente é descrito em uma ValidationMessage ou em uma OutputUnit . Observe que, desde o rascunho de 2019-09, a palavra-chave format não gera mais afirmações por padrão e gera apenas anotações, a menos que seja configurado de outra forma usando uma opção de configuração ou usando um meta-esquema que use o vocabulário apropriado. |
| Anotações | Informações adicionais geradas por uma palavra -chave para uma instância de dados de entrada específica. Isso geralmente é descrito em uma OutputUnit . A coleta e os relatórios de anotação são desligados por padrão. As anotações exigidas por palavras -chave, como unevaluatedProperties ou unevaluatedItems são sempre coletadas para fins de avaliação e não podem ser desativadas, mas não serão relatadas, a menos que sejam configuradas para fazê -lo. |
As informações a seguir são usadas para descrever os dois tipos de resultados.
| Tipo | Descrição |
|---|---|
| Caminho de avaliação | Este é o conjunto de chaves da raiz através da qual a avaliação passa para atingir o esquema para avaliar a instância. Isso inclui $ref e $dynamicRef . por exemplo. /properties/bar/$ref/properties/bar-prop |
| Localização do esquema | Este é o IRI canônico do esquema mais o fragmento de ponteiro JSON para o esquema que foi usado para avaliar a instância. por exemplo. https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop |
| Localização da instância | Este é o fragmento de ponteiro JSON para os dados da instância que estavam sendo avaliados. por exemplo. /bar/bar-prop |
As afirmações contêm as seguintes informações adicionais
| Tipo | Descrição |
|---|---|
| Mensagem | A mensagem de erro de validação. |
| Código | O código de erro. |
| Chave de mensagem | A chave de mensagem usada para gerar a mensagem para localização. |
| Argumentos | Os argumentos usados para gerar a mensagem. |
| Tipo | A palavra -chave que gerou a mensagem. |
| Propriedade | O nome da propriedade que causou o erro de validação, por exemplo, para a palavra -chave required . Observe que isso não faz parte do local da instância, pois isso aponta para o nó da instância. |
| Nó do esquema | O JsonNode apontou pelo local do esquema. Esses são os dados do esquema que causaram falhar os dados de entrada. É possível obter as informações de localização configurando o JsonSchemaFactory com um JsonNodeReader que usa o LocationJsonNodeFactoryFactory e usando JsonNodes.tokenLocationOf(schemaNode) . |
| Nó da instância | O JsonNode apontou pelo local da instância. Estes são os dados de entrada que falharam na validação. É possível obter as informações de localização configurando o JsonSchemaFactory com um JsonNodeReader que usa o LocationJsonNodeFactoryFactory e usando JsonNodes.tokenLocationOf(instanceNode) . |
| Erro | O erro. |
| Detalhes | Detalhes adicionais que podem ser definidos por implementações de validador de palavras -chave personalizadas. Isso não é usado pela biblioteca. |
Anotações contém as seguintes informações adicionais
| Tipo | Descrição |
|---|---|
| Valor | O valor da anotação gerado |
A biblioteca pode ser configurada para armazenar informações de linha e coluna nas instâncias JsonNode para os nós de instância e esquema. Isso afetará adversamente o desempenho e não será configurado por padrão.
Isso é feito configurando um JsonNodeReader que usa o LocationJsonNodeFactoryFactory no JsonSchemaFactory . As informações JsonLocation podem ser recuperadas usando 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 ());Esta biblioteca implementa os formatos de sinalização, lista e saída hierárquica definidos na especificação para saída legível por máquina para validação e anotação de esquema JSON.
A lista e os formatos de saída hierárquica são particularmente úteis para entender como o sistema chegou a um resultado específico.
| Formato de saída | Descrição |
|---|---|
| Padrão | Gera a lista de afirmações. |
| Booleano | Retorna true se a validação for bem -sucedida. Observe que a opção Fail Fast é ativada por padrão para este formato de saída. |
| Bandeira | Retorna um objeto OutputFlag com valid tendo true se a validação for bem -sucedida. Observe que a opção Fail Fast é ativada por padrão para este formato de saída. |
| Lista | Retorna um objeto OutputUnit com details com uma lista de objetos OutputUnit com as afirmações e anotações. Observe que as anotações não são coletadas por padrão e devem ser ativadas, pois afetará o desempenho. |
| Hierárquico | Retorna um objeto OutputUnit com uma hierarquia de objetos OutputUnit para o caminho de avaliação com as afirmações e anotações. Observe que as anotações não são coletadas por padrão e devem ser ativadas, pois afetará o desempenho. |
O exemplo a seguir mostra como gerar o formato de saída hierárquica com a coleta de anotação e os relatórios ativados e as afirmações de formato ativadas.
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 );
});A seguir, é apresentada a saída da amostra do formato hierárquico.
{
"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 "
}
} ]
} ]
}| Nome | Descrição | Valor padrão |
|---|---|---|
annotationCollectionEnabled | Controla se as anotações são coletadas durante o processamento. Observe que a coleta de anotações afetará adversamente o desempenho. | false |
annotationCollectionFilter | O predicado usado para controlar para qual palavra -chave coletar e relatar anotações. Isso exige que annotationCollectionEnabled seja true . | keyword -> false |
locale | O local para usar para gerar mensagens no ValidationMessage . Observe que esse valor é copiado do SchemaValidatorsConfig para cada execução. | Locale.getDefault() |
failFast | Se deve retornar a falha imediatamente quando uma afirmação é gerada. Observe que esse valor é copiado do SchemaValidatorsConfig para cada execução, mas é automaticamente definido como true para os formatos de saída booleanos e sinalizadores. | false |
formatAssertionsEnabled | O padrão é gerar afirmações de formato do rascunho 4 ao rascunho 7 e gerar apenas anotações do rascunho 2019-09. A configuração para true ou false substituirá o comportamento padrão. | null |
debugEnabled | Controla se o log de depuração está ativado para registrar as informações do nó ao processar. Observe que isso gerará muitos logs que afetarão o desempenho. | false |
| Nome | Descrição | Valor padrão |
|---|---|---|
applyDefaultsStrategy | A estratégia para aplicar padrões ao caminhar quando ausente ou nula é encontrada. | ApplyDefaultsStrategy.EMPTY_APPLY_DEFAULTS_STRATEGY |
cacheRefs | Se os esquemas carregados de árvores serão armazenados em cache e reutilizados para execuções subsequentes. Definir isso como false afetará o desempenho, mas pode ser necessário para evitar o uso de memória alto para o cache se vários aplicadores aninhados, como anyOf , oneOf allOf forem utilizados. | true |
discriminatorKeywordEnabled | Se a palavra -chave discriminator é tratada de acordo com o OpenAPI 3. | false |
errorMessageKeyword | A palavra -chave a ser usada para mensagens de erro personalizadas no esquema. Se não estiver definido, esses recursos estão desativados. Isso geralmente é definido como errorMessage ou message . | null |
executionContextCustomizer | Isso pode ser usado para personalizar o ExecutionContext gerado pelo JsonSchema para cada execução de validação. | null |
failFast | Se deve retornar a falha imediatamente quando uma afirmação é gerada. | false |
formatAssertionsEnabled | O padrão é gerar afirmações de formato do rascunho 4 ao rascunho 7 e gerar apenas anotações do rascunho 2019-09. A configuração para true ou false substituirá o comportamento padrão. | null |
javaSemantics | Se a semântica Java é usada para a palavra -chave type . | false |
locale | O local para usar para gerar mensagens no ValidationMessage . | Locale.getDefault() |
losslessNarrowing | Se o estreitamento sem perdas é usado para a palavra -chave type . | false |
messageSource | Isso é usado para recuperar as mensagens específicas do local. | DefaultMessageSource.getInstance() |
nullableKeywordEnabled | Se a palavra -chave nullable é tratada de acordo com o OpenAPI 3.0. Isso afeta as palavras -chave enum e type . | false |
pathType | O tipo de caminho a ser usado para relatar o local da instância e o caminho de avaliação. Defina como PathType.JSON_PATH para usar o caminho json. | PathType.JSON_POINTER |
preloadJsonSchema | Se o esquema será pré -carregado antes de processar qualquer entrada. Isso usará a memória, mas a execução da validação será mais rápida. | true |
preloadJsonSchemaRefMaxNestingDepth | A profundidade máxima do caminho da avaliação para pré -carregar ao pré -carregar refs. | 40 |
readOnly | Se o esquema é apenas leitura. Isso afeta a palavra -chave readOnly . | null |
regularExpressionFactory | A fábrica a ser usada para criar expressões regulares, por exemplo, JoniRegularExpressionFactory ou GraalJSRegularExpressionFactory . Isso exige que a dependência seja adicionada manualmente ao projeto ou uma ClassNotFoundException será lançada. | JDKRegularExpressionFactory.getInstance() |
schemaIdValidator | Isso é usado para personalizar como os valores $id são validados. Observe que a implementação padrão permite fragmentos não vazios, onde nenhum IRI básico é especificado e também permite valores não absolutos de IR $id no esquema raiz. | JsonSchemaIdValidator.DEFAULT |
strict | Isso é definido se as palavras -chave são rigorosas em sua validação. O que isso faz depende dos validadores individuais. | |
typeLoose | Se os tipos são interpretados de maneira solta. Se definido como true, um único valor pode ser interpretado como uma matriz de tamanho 1. As cordas também podem ser interpretadas como número, número inteiro ou booleano. | false |
writeOnly | Se o esquema é apenas gravação. Isso afeta a palavra -chave writeOnly . | null |
Quando a biblioteca cria um esquema da fábrica de esquema, ele cria uma instância de validador distinta para cada local no caminho da avaliação. Isso significa que, se houver $ref diferente que referente a mesma localização do esquema, diferentes instâncias do validador são criadas para cada caminho de avaliação.
Quando o esquema for criado, a biblioteca, por padrão, pré -carregará automaticamente todos os validadores necessários e resolverá referências. Isso pode ser desativado com a opção preloadJsonSchema no SchemaValidatorsConfig . Neste ponto, nenhuma exceção será lançada se uma referência não puder ser resolvida. Se houver referências cíclicas, apenas o primeiro ciclo será pré -carregado. Se você deseja garantir que todas as referências remotas possam ser resolvidas, o método initializeValidators precisa ser chamado ao JsonSchema que fará uma exceção se houver referências que não puderem ser resolvidas.
As instâncias para JsonSchemaFactory e o JsonSchema criadas a partir dele são projetadas para ser segura por threads, desde que sua configuração não seja modificada e deva ser armazenada em cache e reutilizada. Não reutilizar o JsonSchema significa que os dados do esquema precisam ser repetidos analisados com instâncias do validador criadas e referências resolvidas. Quando as referências forem resolvidas, os validadores criados serão armazenados em cache. Para esquemas que têm referências profundamente aninhadas, a memória necessária para os validadores pode ser muito alta; nesse caso, o cache pode precisar ser desativado usando a opção cacheRefs no SchemaValidatorsConfig . Desativar isso significará que os validadores das referências precisam ser recriados para cada execução de validação que afetará o desempenho.
A coleta de anotações afetará adversamente o desempenho da validação.
As especificações de rascunho anteriores contêm menos palavras -chave que podem impactar o desempenho. Por exemplo, o uso das palavras -chave unevaluatedProperties ou unevaluatedItems acionará a coleção de anotação nos validadores relacionados, como properties ou validadores items .
Isso não significa que o uso de um esquema com uma especificação de rascunho posterior causará automaticamente um impacto no desempenho. Por exemplo, o validador properties executará verificações para determinar se as anotações precisam ser coletadas e verifica se o meta-esquema contém a palavra-chave unevaluatedProperties e se a palavra-chave unevaluatedProperties existe adjacente ao caminho de avaliação.
A biblioteca assume que os esquemas que estão sendo carregados são confiáveis. Esse modelo de segurança assume o caso de uso em que os esquemas são acumulados com o aplicativo no caminho de classe.
| Emitir | Descrição | Mitigação |
|---|---|---|
| Carregamento de esquema | A biblioteca por padrão carregará esquemas do caminho de classe e pela Internet, se necessário. | Um DisallowSchemaLoader pode ser configurado para não permitir a recuperação do esquema. Alternativamente, um AllowSchemaLoader pode ser configurado para restringir a íris de recuperação que são permitidas. |
| Cache de esquema | A biblioteca, por padrão, pré -caras e cache de referências ao carregar esquemas. Embora exista uma profundidade máxima de nidificação quando os esquemas de pré -carregamento, ainda é possível construir um esquema que tenha um fã que consome muita memória do servidor. | Defina a opção cacheRefs no SchemaValidatorsConfig como false. |
| Expressões regulares | A biblioteca não valida se uma determinada expressão regular for suscetível à negação de serviço (reduz). | Um AllowRegularExpressionFactory pode ser configurado para executar a validação nas expressões regulares permitidas. |
| Erros de validação | A biblioteca, por padrão, tenta retornar todos os erros de validação. O uso de aplicadores como allOf com um grande número de esquemas pode resultar em um grande número de erros de validação que ocupam memória. | Definir a opção failFast no SchemaValidatorsConfig para retornar imediatamente quando o primeiro erro for encontrado. O OutputFormat.BOOLEAN ou OutputFormat.FLAG também podem ser usados. |
A Light-REST-4J, o Light-GraphQL-4J e o Light-Hybrid-4J usam esta biblioteca para validar a solicitação e a resposta com base nas especificações. Se você estiver usando outras estruturas, como a Spring Boot, poderá usar o OpenApivalIDator, um validador genérico do OpenAPI 3.0 com base na especificação OpenAPI 3.0.
Se você possui um projeto usando esta biblioteca, envie um PR para adicionar seu projeto abaixo.
Graças às seguintes pessoas que contribuíram para este projeto. Se você estiver usando esta biblioteca, considere ser um patrocinador para um dos colaboradores.
@stevehu
@Prashenth-Chaitanya
@fdutton
@valfirst
@Ballonwen
@jiachen1120
@ddobrin
@eskabetxe
@ehrmann
@prashenthjos
@Subhajitdas298
@Fwiesner
@rhwood
@Jawaff
@nitin1891
Para todos os colaboradores, visite https://github.com/networknt/json-schema-validator/graphs/contributores
Se você é um colaborador, junte -se aos patrocinadores do Github e mude o link para o painel de patrocinadores por meio de um PR.
