Téléchargement json schema validator - Téléchargement du code source json schema validator

Il s'agit d'une implémentation Java du schéma JSON Core Draft V4, V6, V7, V2019-09 et V2020-12 pour la validation du schéma JSON. Cette implémentation prend en charge la personnalisation des méta-schémas, des vocabulaires, des mots clés et des formats.

De plus, la validation de la demande / réponse OpenAPI 3 est prise en charge avec l'utilisation du méta-schema approprié. Pour les utilisateurs qui souhaitent collecter des informations à partir d'un nœud JSON basé sur le schéma, les marcheurs peuvent aider. L'analyseur JSON utilisé est le Parser Jackson. Comme il s'agit d'un composant clé de notre cadre de microservices LIGHT-4J pour valider la demande / réponse par rapport aux spécifications OpenAPI pour le schéma Light-Rest-4J et RPC pour la lumière-hybride-4J au moment de l'exécution, les performances sont l'aspect le plus important de la conception.

Compatibilité des spécifications du schéma JSON

Des informations sur le support de compatibilité pour chaque version, y compris les problèmes connus, peuvent être trouvés dans le document de compatibilité avec les versions de schéma JSON.

Depuis le projet 2019-09, le mot-clé format ne génère des annotations que par défaut et ne génère pas d'affirmations.

Ce comportement peut être remplacé pour générer des affirmations en définissant le setFormatAssertionsEnabled sur true dans SchemaValidatorsConfig ou ExecutionConfig .

Mise à niveau vers de nouvelles versions

Cette bibliothèque peut contenir des modifications de rupture dans les versions de versions minor qui peuvent nécessiter des modifications de code.

Des informations sur les modifications notables ou de rupture lors de la mise à niveau de la bibliothèque peuvent être trouvées dans le document de mise à niveau vers de nouveaux versions.

La page des versions contiendra des informations sur les dernières versions.

En comparant les autres implémentations

Le projet de comparaison de validation du schéma JSON de Creek a une comparaison informative des implémentations de validation du schéma basées sur JVM qui compare à la fois les caractéristiques fonctionnelles et de performance d'un certain nombre d'implémentations Java différentes.

Comparaison fonctionnelle
Comparaison des performances

Le projet Bowtie a un rapport qui compare les caractéristiques fonctionnelles des différentes implémentations, y compris les implémentations non java, mais ne fait aucune analyse comparative de performance.

Pourquoi cette bibliothèque

Performance

Cela devrait être la mise en œuvre du validateur Java JSON le plus rapide.

Ce qui suit est la référence des résultats du projet Perftest du schéma JSON qui utilise le harnais de microbenchmarché Java.

Notez que les résultats de référence dépendent fortement des charges de travail et des schémas de données d'entrée utilisées pour la validation.

Dans ce cas, cette charge de travail utilise la spécification du projet 4 et teste largement les performances du mot-clé d'évaluation des properties . Vous pouvez vous référer aux résultats de la comparaison des performances des implémentations de validation du schéma JSON basées sur JVM pour les résultats de référence pour des charges de travail plus typiques

Si les performances sont une considération importante, les échantillons de charges de travail spécifiques doivent être comparés, car il existe différentes caractéristiques de performance lorsque certains mots clés sont utilisés. Par exemple, l'utilisation du mot-clé unevaluatedProperties ou unevaluatedItems le mot-clé déclenchera la collection d'annotation dans les validateurs associés, tels que les properties ou les validateurs items , et la collection d'annotation affectera négativement les performances.

Networknt 1.4.1

 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

Everit 1.14.1

 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

Fonctionnalité

Cette implémentation est testée contre la suite de tests de schéma JSON. Comme les tests sont continuellement ajoutés à la suite, ces résultats des tests peuvent ne pas être courants.

Implémentations	Dans l'ensemble	Draft_03	Draft_04	Draft_06	Draft_07	Draft_2019_09	Draft_2020_12
Networknt	Pass: R: 4803 (100,0%) O: 2372 (100,0%) Échec: R: 0 (0,0%) O: 0 (0,0%)		Pass: R: 610 (100,0%) O: 251 (100,0%) Échec: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 822 (100,0%) O: 318 (100,0%) Échec: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 906 (100,0%) O: 541 (100,0%) Échec: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 1220 (100,0%) O: 625 (100,0%) Échec: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 1245 (100,0%) O: 637 (100,0%) Échec: R: 0 (0,0%) O: 0 (0,0%)

Notez que cela utilise le JoniRegularExpressionFactory pour les tests regex pattern et format .

Analyser Jackson

Cette bibliothèque utilise Jackson qui est un analyseur Java JSON qui est largement utilisé dans d'autres projets. Si vous utilisez déjà le Jackson Parser dans votre projet, il est naturel de choisir cette bibliothèque plutôt que d'autres pour la validation du schéma.

Support YAML

La bibliothèque fonctionne avec JSON et YAML sur les définitions de schéma et les données d'entrée.

Support OpenAPI

La spécification OpenAPI 3.0 utilise le schéma JSON pour valider la demande / réponse, mais il existe des différences. Avec un fichier de configuration, vous pouvez permettre à la bibliothèque de travailler avec la validation OpenAPI 3.0.

Dépendances minimales

En suivant le principe de conception de la plate-forme lumineuse, cette bibliothèque a des dépendances minimales pour s'assurer qu'il n'y a pas de conflits de dépendance lors de son utilisation.

Dépendances requises

Voici les dépendances qui seront automatiquement incluses lorsque cette bibliothèque sera incluse.

< 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 >

Dépendances facultatives

Voici les dépendances facultatives qui peuvent être requises pour certaines options.

Ceux-ci ne sont pas automatiquement inclus et la définition de l'option pertinente sans ajouter que la bibliothèque se traduira par une 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 >

Dépendances exclues

Les dépendances requises suivantes sont automatiquement incluses, mais peuvent être explicitement exclues si elles ne sont pas requises.

La dépendance YAML peut être exclue si cela n'est pas requis. Tenter de traiter des schémas ou une entrée qui sont YAML se traduiront par une 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 >

La dépendance à l'ETHLO peut être exclue si une validation précise du format date-time n'est pas requise. Le format date-time utilisera ensuite java.time.OffsetDateTime pour déterminer si la date-time est valide.

< dependency >
    < groupId >com.networknt</ groupId >
    < artifactId >json-schema-validator</ artifactId >
    < exclusions >
        < exclusion >
            < groupId >com.ethlo.time</ groupId >
            < artifactId >itu</ artifactId >
        </ exclusion >
    </ exclusions >
</ dependency >

Communauté

Cette bibliothèque est très active avec beaucoup de contributeurs. De nouvelles fonctionnalités et correctifs de bogues sont gérés rapidement par les membres de l'équipe. Parce qu'il s'agit d'une dépendance essentielle du cadre Light-4J dans la même organisation GitHub, elle sera évoluée et maintenue avec le cadre.

Condition préalable

La bibliothèque prend en charge Java 8 et plus. Si vous souhaitez construire à partir du code source, vous devez installer JDK 8 localement. Pour prendre en charge plusieurs versions de JDK, vous pouvez utiliser SDKMAN

Usage

Ajouter la dépendance

Ce package est disponible sur Maven Central.

Maven:

< dependency >
    < groupId >com.networknt</ groupId >
    < artifactId >json-schema-validator</ artifactId >
    < version >1.5.3</ version >
</ dependency >

Gradle:

 dependencies {
    implementation ( group : 'com.networknt' , name : 'json-schema-validator' , version : '1.5.3' );
}

Valider les entrées contre un schéma

L'exemple suivant montre comment les entrées sont validées par rapport à un schéma. Il comprend les étapes suivantes.

Création d'une usine de schéma avec le dialecte de schéma par défaut et comment les schémas peuvent être récupérés.
- Configuration de la cartographie du $id dans un URI de récupération à l'aide de schemaMappers .
- Configuration de la façon dont les schémas sont chargés à l'aide de l'URI de récupération à l'aide schemaLoaders . Par exemple, une Map<String, String> schemas contenant un mappage de l'URI de récupération vers les données de schéma comme une String peut en configurer à l'aide builder.schemaLoaders(schemaLoaders -> schemaLoaders.schemas(schemas)) . Cela accepte également une Function<String, String> schemaRetrievalFunction .
Création d'une configuration pour contrôler le comportement du validateur.
Chargement d'un schéma à partir d'un emplacement de schéma avec la configuration du validateur.
Utilisation du schéma pour valider les données ainsi que la définition de toute configuration spécifique à l'exécution comme par exemple le paramètre ou si des affirmations de format sont activées.

 // 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 );
});

Valider un schéma contre un méta-schema

L'exemple suivant montre comment un schéma est validé contre un méta-schema.

Ceci est en fait la même que la validation des entrées par rapport à un schéma, sauf dans ce cas, l'entrée est le schéma et le schéma utilisé est le méta-schema.

Notez que les méta-schemas pour le projet 4, le projet 6, le projet 7, le projet 2019-09 et le projet 2020-12 sont regroupées avec la bibliothèque et ces ressources de ClassPath seront utilisées par défaut.

 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 );
});

Résultats et formats de sortie

Résultats

Les types de résultats suivants sont générés par la bibliothèque.

Taper Description

Affirmation Erreurs de validation générées par un mot-clé sur une instance de données d'entrée particulière. Ceci est généralement décrit dans un ValidationMessage ou dans une OutputUnit . Notez que depuis le projet 2019-09, le mot-clé format ne génère plus les affirmations par défaut et ne génère à la place que des annotations, sauf si vous configurez en utilisant une option de configuration ou en utilisant un méta-schema qui utilise le vocabulaire approprié.

Annotations Informations supplémentaires générées par un mot-clé pour une instance de données d'entrée particulière. Ceci est généralement décrit dans une OutputUnit . La collecte et les rapports d'annotation sont désactivés par défaut. Les annotations requises par des mots-clés tels que unevaluatedProperties ou unevaluatedItems sont toujours collectées à des fins d'évaluation et ne peuvent pas être désactivées mais ne seront signalées que si elles sont configurées pour le faire.

Taper	Description
Affirmation	Erreurs de validation générées par un mot-clé sur une instance de données d'entrée particulière. Ceci est généralement décrit dans un `ValidationMessage` ou dans une `OutputUnit` . Notez que depuis le projet 2019-09, le mot-clé `format` ne génère plus les affirmations par défaut et ne génère à la place que des annotations, sauf si vous configurez en utilisant une option de configuration ou en utilisant un méta-schema qui utilise le vocabulaire approprié.
Annotations	Informations supplémentaires générées par un mot-clé pour une instance de données d'entrée particulière. Ceci est généralement décrit dans une `OutputUnit` . La collecte et les rapports d'annotation sont désactivés par défaut. Les annotations requises par des mots-clés tels que `unevaluatedProperties` ou `unevaluatedItems` sont toujours collectées à des fins d'évaluation et ne peuvent pas être désactivées mais ne seront signalées que si elles sont configurées pour le faire.

Les informations suivantes sont utilisées pour décrire les deux types de résultats.

Taper	Description
Chemin d'évaluation	Il s'agit de l'ensemble des clés de la racine à travers laquelle l'évaluation passe pour atteindre le schéma pour évaluer l'instance. Cela inclut `$ref` et `$dynamicRef` . par exemple, par exemple `/properties/bar/$ref/properties/bar-prop`
Emplacement du schéma	Il s'agit de l'IRI canonique du schéma plus le fragment de pointeur JSON vers le schéma qui a été utilisé pour évaluer l'instance. par exemple, par exemple `https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop`
Emplacement d'instance	Il s'agit du fragment de pointeur JSON vers les données d'instance qui ont été évaluées. par exemple, par exemple `/bar/bar-prop`

Les affirmations contient les informations supplémentaires suivantes

Taper	Description
Message	Le message d'erreur de validation.
Code	Le code d'erreur.
Clé de message	La clé de message utilisée pour générer le message de localisation.
Arguments	Les arguments utilisés pour générer le message.
Taper	Le mot-clé qui a généré le message.
Propriété	Le nom de la propriété qui a provoqué l'erreur de validation par exemple pour le mot-clé `required` . Notez que cela ne fait pas partie de l'emplacement d'instance car cela pointe vers le nœud d'instance.
Nœud de schéma	Le `JsonNode` pointé par l'emplacement du schéma. Il s'agit des données de schéma qui ont fait échouer les données d'entrée. Il est possible d'obtenir les informations de localisation en configurant le `JsonSchemaFactory` avec un `JsonNodeReader` qui utilise le `LocationJsonNodeFactoryFactory` et à l'aide `JsonNodes.tokenLocationOf(schemaNode)` .
Nœud d'instance	Le `JsonNode` pointé par l'emplacement de l'instance. Il s'agit des données d'entrée qui ont échoué la validation. Il est possible d'obtenir les informations de localisation en configurant le `JsonSchemaFactory` avec un `JsonNodeReader` qui utilise le `LocationJsonNodeFactoryFactory` et à l'aide `JsonNodes.tokenLocationOf(instanceNode)` .
Erreur	L'erreur.
Détails	Détails supplémentaires qui peuvent être définis par les implémentations de validateurs de mots clés personnalisés. Ceci n'est pas utilisé par la bibliothèque.

Les annotations contient les informations supplémentaires suivantes

Taper	Description
Valeur	La valeur d'annotation générée

Informations sur la ligne et la colonne

La bibliothèque peut être configurée pour stocker les informations de ligne et de colonne dans les instances JsonNode pour l'instance et les nœuds de schéma. Cela affectera négativement les performances et n'est pas configuré par défaut.

Cela se fait en configurant un JsonNodeReader qui utilise le LocationJsonNodeFactoryFactory sur le JsonSchemaFactory . Les informations JsonLocation peuvent ensuite être récupérées à l'aide de 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 ());

Formats de sortie

Cette bibliothèque implémente l'indicateur, la liste et les formats de sortie hiérarchiques définis dans la spécification pour la sortie lisible par machine pour la validation et l'annotation du schéma JSON.

La liste et les formats de sortie hiérarchiques sont particulièrement utiles pour comprendre comment le système est arrivé à un résultat particulier.

Format de sortie	Description
Défaut	Génère la liste des affirmations.
Booléen	Renvoie `true` si la validation est réussie. Notez que l'option FAIL FAST est activée par défaut pour ce format de sortie.
Drapeau	Renvoie un objet `OutputFlag` avec `valid` ayant `true` si la validation est réussie. Notez que l'option FAIL FAST est activée par défaut pour ce format de sortie.
Liste	Renvoie un objet `OutputUnit` avec `details` avec une liste d'objets `OutputUnit` avec les assertions et les annotations. Notez que les annotations ne sont pas collectées par défaut et elles doivent être activées car elles auront un impact sur les performances.
Hiérarchique	Renvoie un objet `OutputUnit` avec une hiérarchie d'objets `OutputUnit` pour le chemin d'évaluation avec les assertions et les annotations. Notez que les annotations ne sont pas collectées par défaut et elles doivent être activées car elles auront un impact sur les performances.

L'exemple suivant montre comment générer le format de sortie hiérarchique avec la collection d'annotation et les rapports activés et les assertions de format activées.

 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 );
});

Ce qui suit est l'échantillon de sortie du format hiérarchique.

{
  "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 "
      }
    } ]
  } ]
}

Configuration

Configuration d'exécution

Nom	Description	Valeur par défaut
`annotationCollectionEnabled`	Contrôle si les annotations sont collectées pendant le traitement. Notez que la collecte d'annotations affectera négativement les performances.	`false`
`annotationCollectionFilter`	Le prédicat utilisé pour contrôler le mot-clé à collectionner et signaler les annotations. Cela nécessite `annotationCollectionEnabled` pour être `true` .	`keyword -> false`
`locale`	Le lieu à utiliser pour générer des messages dans le `ValidationMessage` . Notez que cette valeur est copiée à partir de `SchemaValidatorsConfig` pour chaque exécution.	`Locale.getDefault()`
`failFast`	Il faut retourner l'échec immédiatement lorsqu'une affirmation est générée. Notez que cette valeur est copiée à partir de `SchemaValidatorsConfig` pour chaque exécution, mais est automatiquement définie sur `true` pour les formats de sortie booléens et de drapeau.	`false`
`formatAssertionsEnabled`	La valeur par défaut consiste à générer des assertions de format du projet 4 à la brouillon 7 et à générer uniquement des annotations à partir du projet 2019-09. Le réglage sur `true` ou `false` remplacera le comportement par défaut.	`null`
`debugEnabled`	Contrôle si la journalisation de débogage est activée pour enregistrer les informations du nœud lors du traitement. Notez que cela générera de nombreux journaux qui affecteront les performances.	`false`

Configuration des validateurs de schéma

Nom	Description	Valeur par défaut
`applyDefaultsStrategy`	La stratégie pour appliquer les défauts de défaut lors de la marche lorsqu'il est manqué ou nul les nœuds sont rencontrés.	`ApplyDefaultsStrategy.EMPTY_APPLY_DEFAULTS_STRATEGY`
`cacheRefs`	La question de savoir si les schémas chargés des arbitres seront mis en cache et réutilisés pour les courses suivantes. Le réglage sur `false` affectera les performances, mais peut être nécessaire pour éviter une utilisation élevée de la mémoire pour le cache si plusieurs applicateurs imbriqués comme `anyOf` , `oneOf` et `allOf` sont utilisés.	`true`
`discriminatorKeywordEnabled`	Si le mot-clé `discriminator` est géré selon OpenAPI 3.	`false`
`errorMessageKeyword`	Le mot-clé à utiliser pour les messages d'erreur personnalisés dans le schéma. Si vous ne réglez pas, ces fonctionnalités sont désactivées. Ceci est généralement défini sur `errorMessage` ou `message` .	`null`
`executionContextCustomizer`	Ceci peut être utilisé pour personnaliser l' `ExecutionContext` généré par le `JsonSchema` pour chaque exécution de validation.	`null`
`failFast`	Il faut retourner l'échec immédiatement lorsqu'une affirmation est générée.	`false`
`formatAssertionsEnabled`	La valeur par défaut consiste à générer des assertions de format du projet 4 à la brouillon 7 et à générer uniquement des annotations à partir du projet 2019-09. Le réglage sur `true` ou `false` remplacera le comportement par défaut.	`null`
`javaSemantics`	Si Java Semantics est utilisée pour le mot-clé `type` .	`false`
`locale`	Le lieu à utiliser pour générer des messages dans le `ValidationMessage` .	`Locale.getDefault()`
`losslessNarrowing`	La question de savoir si un rétrécissement sans perte est utilisé pour le mot-clé `type` .	`false`
`messageSource`	Ceci est utilisé pour récupérer les messages spécifiques aux paramètres régionaux.	`DefaultMessageSource.getInstance()`
`nullableKeywordEnabled`	Si le mot clé `nullable` est géré selon OpenAPI 3.0. Cela affecte les mots clés `enum` et `type` .	`false`
`pathType`	Le type de chemin à utiliser pour signaler l'emplacement d'instance et le chemin d'évaluation. Réglé sur `PathType.JSON_PATH` pour utiliser le chemin JSON.	`PathType.JSON_POINTER`
`preloadJsonSchema`	Si le schéma sera préchargé avant de traiter une entrée. Cela utilisera la mémoire mais l'exécution de la validation sera plus rapide.	`true`
`preloadJsonSchemaRefMaxNestingDepth`	La profondeur maximale du chemin d'évaluation vers la précharge lors du préchargement des réf.	`40`
`readOnly`	Si le schéma est lu seulement. Cela affecte le mot-clé `readOnly` .	`null`
`regularExpressionFactory`	L'usine à utiliser pour créer des expressions régulières, par exemple, `JoniRegularExpressionFactory` ou `GraalJSRegularExpressionFactory` . Cela nécessite que la dépendance soit ajoutée manuellement au projet ou une `ClassNotFoundException` sera lancée.	`JDKRegularExpressionFactory.getInstance()`
`schemaIdValidator`	Ceci est utilisé pour personnaliser comment les valeurs `$id` sont validées. Notez que l'implémentation par défaut permet des fragments non vides où aucun IRI de base n'est spécifié et permet également les valeurs IRI `$id` non absolute dans le schéma racine.	`JsonSchemaIdValidator.DEFAULT`
`strict`	Ceci est défini si les mots clés sont stricts dans leur validation. Ce que cela dépend dépend des validateurs individuels.
`typeLoose`	Si les types sont interprétés de manière lâche. Si elle est définie sur true, une seule valeur peut être interprétée comme un tableau de taille 1. Les cordes peuvent également être interprétées comme un nombre, un entier ou un booléen.	`false`
`writeOnly`	Si le schéma est uniquement écrit. Cela affecte le mot-clé `writeOnly` .	`null`

Considérations de performance

Lorsque la bibliothèque crée un schéma à partir de l'usine de schéma, elle crée une instance de validateur distincte pour chaque emplacement sur le chemin d'évaluation. Cela signifie que s'il y a différents $ref qui font référence au même emplacement de schéma, différentes instances de validateur sont créées pour chaque chemin d'évaluation.

Lorsque le schéma est créé, la bibliothèque préchargera automatiquement tous les validateurs nécessaires et résoudra les références. Cela peut être désactivé avec l'option preloadJsonSchema dans le SchemaValidatorsConfig . À ce stade, aucune exception ne sera lancée si une référence ne peut pas être résolue. S'il y a des références cycliques, seul le premier cycle sera préchargé. Si vous souhaitez vous assurer que les références à distance peuvent toutes être résolues, la méthode initializeValidators doit être appelée sur le JsonSchema qui lancera une exception s'il existe des références qui ne peuvent pas être résolues.

Les instances pour JsonSchemaFactory et le JsonSchema créées à partir de celui-ci sont conçues pour être en file d'attente à condition que sa configuration ne soit pas modifiée et doit être mise en cache et réutilisée. Ne pas réutiliser le JsonSchema signifie que les données de schéma doivent être répétées avec les instances de validateur créées et les références résolues. Lorsque les références sont résolues, les validateurs créés seront mis en cache. Pour les schémas qui ont des références profondément imbriquées, la mémoire nécessaire pour les validateurs peut être très élevée, auquel cas la mise en cache peut devoir être désactivée en utilisant l'option cacheRefs dans le SchemaValidatorsConfig . La désactivation signifiera que les validateurs des références doivent être recréés pour chaque exécution de validation qui aura un impact sur les performances.

La collecte d'annotations affectera négativement les performances de validation.

Les spécifications de projet précédents contiennent moins de mots clés qui peuvent potentiellement avoir un impact sur les performances. Par exemple, l'utilisation du mot-clé unevaluatedProperties ou unevaluatedItems le mot-clé déclenchera la collection d'annotation dans les validateurs associés, tels que les properties ou les validateurs items .

Cela ne signifie pas que l'utilisation d'un schéma avec un projet ultérieur de spécification entraînera automatiquement un impact sur les performances. Par exemple, le validateur properties effectuera des vérifications pour déterminer si les annotations doivent être collectées, et vérifie si le méta-schema contient le mot-clé de propriétés unevaluatedProperties et si le mot-clé unevaluatedProperties existait le chemin d'évaluation.

Considérations de sécurité

La bibliothèque suppose que les schémas en cours de charge sont fiables. Ce modèle de sécurité suppose le cas d'utilisation où les schémas sont regroupés avec l'application sur le chemin de classe.

Problème	Description	Atténuation
Chargement du schéma	La bibliothèque par défaut chargera les schémas du chemin de classe et sur Internet si nécessaire.	Un `DisallowSchemaLoader` peut être configuré pour ne pas permettre la récupération du schéma. Alternativement, un permet de configurer `AllowSchemaLoader` permet de restreindre l'iris de récupération autorisé.
Cache de schéma	La bibliothèque par défaut précharge et cache références lors du chargement des schémas. Bien qu'il existe une profondeur de nidification maximale lors du préchargement des schémas, il est toujours possible de construire un schéma qui a un ventilateur qui consomme beaucoup de mémoire du serveur.	Définissez l'option `cacheRefs` dans `SchemaValidatorsConfig` sur FALSE.
Expressions régulières	La bibliothèque ne valide pas si une expression régulière donnée est sensible au déni de service (redos).	Un `AllowRegularExpressionFactory` peut être configuré pour effectuer une validation sur les expressions régulières autorisées.
Erreurs de validation	La bibliothèque tente par défaut de renvoyer toutes les erreurs de validation. L'utilisation d'applicateurs tels que `allOf` avec un grand nombre de schémas peut entraîner un grand nombre d'erreurs de validation en prenant de la mémoire.	Définissez l'option `failFast` dans `SchemaValidatorsConfig` pour revenir immédiatement lorsque la première erreur est rencontrée. Le `OutputFormat.BOOLEAN` ou `OutputFormat.FLAG` peut également être utilisé.

Démarrage rapide

Personnalisation de la récupération du schéma

Personnalisation des méta-schémas, des vocabulaires, des mots clés et des formats

Spécification OpenAPI

Validateurs

Configuration

Version de spécification

Validation YAML

Contexte collecteur

JSON Schema Walkers et Walkisteners

Expressions régulières

Messages d'erreur personnalisés

Langue multiple

Validation du métaschema

Validation des durées RFC 3339

Projets

La lumière-reest-4J, la lumière-graphql-4j et la lumière-hybride-4J utilisent cette bibliothèque pour valider la demande et la réponse en fonction des spécifications. Si vous utilisez d'autres frameworks comme Spring Boot, vous pouvez utiliser l'OpenAvalidator, un validateur générique OpenAPI 3.0 basé sur la spécification OpenAPI 3.0.

Si vous avez un projet utilisant cette bibliothèque, veuillez soumettre un PR pour ajouter votre projet ci-dessous.

Contributeurs

Grâce aux personnes suivantes qui ont contribué à ce projet. Si vous utilisez cette bibliothèque, veuillez considérer comme un sponsor pour l'un des contributeurs.

@stevehu

@ prashanth-chaitanya

@fdutton

@ValFirst

@Balloonwen

@ Jiachen1120

@ddobrin

@eskabetxe

@ehrmann

@prashanthjos

@ Subhajitdas298

@Fwiesner

@rhwood

@jawaff

@ nitin1891

Pour tous les contributeurs, veuillez visiter https://github.com/networknt/json-schema-validator/graphs/Contributeurs

Si vous êtes contributeur, veuillez rejoindre les sponsors GitHub et passer le lien vers votre tableau de bord des sponsors via un RP.

json schema validator

Compatibilité des spécifications du schéma JSON

Mise à niveau vers de nouvelles versions

En comparant les autres implémentations

Pourquoi cette bibliothèque

Performance

Networknt 1.4.1

Everit 1.14.1

Fonctionnalité

Analyser Jackson

Support YAML

Support OpenAPI

Dépendances minimales

Dépendances requises

Dépendances facultatives

Dépendances exclues

Communauté

Condition préalable

Usage

Ajouter la dépendance

Maven:

Gradle:

Valider les entrées contre un schéma

Valider un schéma contre un méta-schema

Résultats et formats de sortie

Résultats

Informations sur la ligne et la colonne

Formats de sortie

Configuration

Configuration d'exécution

Configuration des validateurs de schéma

Considérations de performance

Considérations de sécurité

Démarrage rapide

Personnalisation de la récupération du schéma

Personnalisation des méta-schémas, des vocabulaires, des mots clés et des formats

Spécification OpenAPI

Validateurs

Configuration

Version de spécification

Validation YAML

Contexte collecteur

JSON Schema Walkers et Walkisteners

Expressions régulières

Messages d'erreur personnalisés

Langue multiple

Validation du métaschema

Validation des durées RFC 3339

Projets

Contributeurs

Sponsors

Sponsors individuels

Sponsors de la société