Inleiding tot JSON-schema in Java

1. Overzicht

JSON-schema is een declaratieve taal voor het valideren van het formaat en de structuur van een JSON-object. Het stelt ons in staat om het aantal speciale primitieven te specificeren om precies te beschrijven wat geldig is JSON-object zal lijken op.

De JSON-schema specificatie is onderverdeeld in drie delen:

  • JSON Schema Core: de JSON Schema Core-specificatie is waar de terminologie voor een schema wordt gedefinieerd.
  • JSON Schema Validation: De JSON Schema Validation-specificatie is het document dat de geldige manieren definieert om validatiebeperkingen te definiëren. Dit document definieert ook een set sleutelwoorden die kunnen worden gebruikt om validaties voor een JSON API te specificeren. In de volgende voorbeelden gebruiken we enkele van deze trefwoorden.
  • JSON Hyper-Schema: dit is een andere uitbreiding van de JSON Schema-specificatie, waarin de hyperlink- en hypermedia-gerelateerde sleutelwoorden zijn gedefinieerd.

2. Een JSON-schema definiëren

Nu we hebben gedefinieerd wat een JSON-schema wordt gebruikt voor, laten we een JSON-object en de daarbij behorende JSON-schema het beschrijven.

Het volgende is eenvoudig JSON-object vertegenwoordigt een productcatalogus:

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

We zouden haar kunnen definiëren JSON-schema als volgt:

{"$ schema": "//json-schema.org/draft-04/schema#", "title": "Product", "description": "Een product uit de catalogus", "type": "object" , "properties": {"id": {"description": "De unieke identificatie voor een product", "type": "integer"}, "name": {"description": "Naam van het product", " type ":" string "}," price ": {" type ":" number "," minimum ": 0," exclusiveMinimum ": true}}," required ": [" id "," name "," price "]}

Zoals we kunnen zien a JSON-schema is een JSON-document, en dat document MOET een object zijn. Objectleden (of eigenschappen) gedefinieerd door JSON-schema worden genoemd trefwoorden.

Laten we de trefwoorden uitleggen die we in ons voorbeeld hebben gebruikt:

  • De $ schema trefwoord stelt dat dit schema is geschreven volgens de v4-conceptspecificatie.
  • De titel en Omschrijving trefwoorden zijn alleen beschrijvend, in die zin dat ze geen beperkingen toevoegen aan de gegevens die worden gevalideerd. De bedoeling van het schema wordt aangegeven met deze twee sleutelwoorden: beschrijft een product.
  • De type trefwoord definieert de eerste beperking op onze JSON data: het moet zijn een JSON-object.

Ook kan een JSON-schema eigenschappen bevatten die geen schema-sleutelwoorden zijn. In ons geval ID kaart, naam, prijszullen leden (of eigenschappen) zijn van de JSON-object.

Voor elke eigenschap kunnen we de type. We hebben gedefinieerd ID kaart en naam net zo draaden prijs net zo aantal. In JSON-schema een aantal kan een minimum hebben. Standaard is dit minimum inclusief, dus we moeten specificeren exclusief Minimum.

eindelijk, de Schema vertelt dat ID kaart, naam, en prijs zijn verplicht.

3. Validatie met JSON-schema

Met onze JSON-schema op de plaats zetten we kunnen valideren onze JSON-object.

Er zijn veel bibliotheken om deze taak uit te voeren. Voor ons voorbeeld hebben we gekozen voor de Java json-schemabibliotheek.

Allereerst moeten we de volgende afhankelijkheid toevoegen aan onze pom.xml:

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

Ten slotte kunnen we een paar eenvoudige testcases schrijven om onze te valideren JSON-object:

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

In dit geval gegooid ValidationException zal wijzen naar #/prijs. Als je naar de console kijkt, wordt de volgende uitvoer afgedrukt:

# / prijs: 0,0 is niet hoger dan 0 

De tweede test ziet er als volgt uit:

@Test openbare ongeldige gegevenValidInput_whenValidating_thenValid () gooit ValidationException {JSONObject jsonSchema = nieuw JSONObject (nieuw JSONTokener (JSONSchemaTest.class.getResourceAsStream ("/ schema.json"))); JSONObject jsonSubject = nieuw JSONObject (nieuwe JSONTokener (JSONSchemaTest.class.getResourceAsStream ("/ product_valid.json"))); Schemaschema = SchemaLoader.load (jsonSchema); schema.validate (jsonSubject); }

Omdat we een geldig JSON-object, wordt er geen validatiefout gegenereerd.

4. Conclusie

In dit artikel hebben we gedefinieerd wat een JSON-schema is en welke relevante sleutelwoorden ons helpen ons schema te definiëren.

Koppeling a JSON-schema met de bijbehorende JSON-object vertegenwoordiging kunnen we een of andere validatietaak uitvoeren.

Een eenvoudige testcase van dit artikel is te vinden in het GitHub-project.