Introduction au schéma JSON en Java

1. Vue d'ensemble

JSON Schema est un langage déclaratif pour valider le format et la structure d'un objet JSON . Cela nous permet de spécifier le nombre de primitives spéciales pour décrire exactement à quoi ressemblera un objet JSON valide.

La spécification du schéma JSON est divisée en trois parties:

  • JSON Schema Core: la spécification JSON Schema Core est l'endroit où la terminologie d'un schéma est définie.
  • Validation de schéma JSON: la spécification de validation de schéma JSON est le document qui définit les méthodes valides pour définir les contraintes de validation. Ce document définit également un ensemble de mots-clés pouvant être utilisés pour spécifier des validations pour une API JSON. Dans les exemples qui suivent, nous utiliserons certains de ces mots clés.
  • Hyper-schéma JSON: il s'agit d'une autre extension de la spécification de schéma JSON, dans laquelle les mots-clés liés aux liens hypertexte et hypermédia sont définis.

2. Définition d'un schéma JSON

Maintenant que nous avons défini à quoi sert un schéma JSON , créons un objet JSON et le schéma JSON correspondant le décrivant.

Voici un simple objet JSON représentant un catalogue de produits:

{ "id": 1, "name": "Lampshade", "price": 0 }

Nous pourrions définir son schéma JSON comme suit:

{ "$schema": "//json-schema.org/draft-04/schema#", "title": "Product", "description": "A product from the catalog", "type": "object", "properties": { "id": { "description": "The unique identifier for a product", "type": "integer" }, "name": { "description": "Name of the product", "type": "string" }, "price": { "type": "number", "minimum": 0, "exclusiveMinimum": true } }, "required": ["id", "name", "price"] }

Comme nous pouvons le voir, un schéma JSON est un document JSON , et ce document DOIT être un objet. Les membres d'objets (ou propriétés) définis par le schéma JSON sont appelés des mots-clés .

Expliquons les mots-clés que nous avons utilisés dans notre exemple:

  • Le mot clé $ schema indique que ce schéma est écrit conformément à la spécification provisoire v4.
  • Les mots clés de titre et de description sont uniquement descriptifs, en ce sens qu'ils n'ajoutent pas de contraintes aux données en cours de validation. L'intention du schéma est indiquée avec ces deux mots-clés: décrit un produit.
  • Le mot-clé type définit la première contrainte sur nos données JSON : il doit s'agir d' un objet JSON .

De plus, un schéma JSON PEUT contenir des propriétés qui ne sont pas des mots-clés de schéma. Dans notre cas, id , nom , prix seront des membres (ou propriétés) de l' objet JSON .

Pour chaque propriété, nous pouvons définir le type . Nous avons défini l' identifiant et le nom comme une chaîne et le prix comme un nombre . Dans le schéma JSON, un nombre peut avoir un minimum. Par défaut, ce minimum est inclusif, nous devons donc spécifier exclusiveMinimum .

Enfin, le schéma indique que l' identifiant , le nom et le prix sont requis .

3. Validation avec le schéma JSON

Avec notre schéma JSON mis en place, nous pouvons valider notre objet JSON .

Il existe de nombreuses bibliothèques pour accomplir cette tâche. Pour notre exemple, nous avons choisi la bibliothèque Java json-schema.

Tout d'abord, nous devons ajouter la dépendance suivante à notre pom.xml :

 org.everit.json org.everit.json.schema 1.3.0  

Enfin, nous pouvons écrire quelques cas de test simples pour valider notre objet JSON:

@Test public void givenInvalidInput_whenValidating_thenInvalid() throws ValidationException { JSONObject jsonSchema = new JSONObject( new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/schema.json"))); JSONObject jsonSubject = new JSONObject( new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/product_invalid.json"))); Schema schema = SchemaLoader.load(jsonSchema); schema.validate(jsonSubject); }

Dans ce cas, ValidationException lancée pointera vers # / price. Si vous regardez la console, elle imprimera la sortie suivante:

#/price: 0.0 is not higher than 0 

Le deuxième test ressemble à ce qui suit:

@Test public void givenValidInput_whenValidating_thenValid() throws ValidationException { JSONObject jsonSchema = new JSONObject( new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/schema.json"))); JSONObject jsonSubject = new JSONObject( new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/product_valid.json"))); Schema schema = SchemaLoader.load(jsonSchema); schema.validate(jsonSubject); }

Étant donné que nous utilisons un objet JSON valide , aucune erreur de validation ne sera générée.

4. Conclusion

Dans cet article, nous avons défini ce qu'est un schéma JSON et quels sont les mots clés pertinents qui nous aident à définir notre schéma.

En couplant un schéma JSON avec sa représentation d' objet JSON correspondante, nous pouvons effectuer une tâche de validation.

Un cas de test simple de cet article peut être trouvé dans le projet GitHub.