Introduction à JSON Schema

Introduction à JSON Schema

A quoi ça sert?

JSON Schema permet de spécifier et de valider la structure de données JSON.

Pour le définir simplement, on peut dire que JSON Schema est à JSON, ce qu’est XSD à XML.

C’est à la fois lisible pour les développeurs, mais également pour les programmes.

Quand utiliser JSON Schema?

Dès que l’on désire spécifier ou valider le format d’un document JSON, on peut utiliser JSON Schema!

On peut donc utiliser JSON Schema lorsque l’on écrit une API reposant sur des données JSON.

Dans ce cadre, JSON Schema va répondre à deux problématiques: Valider les données d’entrée de notre API, ainsi que décrire le format d’entrée à destination des développeurs, pouvant servir de documentation.

On retrouve de nombreuses librairies dans les différents langages de programmation qui permettent de valider la structure de données au format JSON.

Et concrètement ?

Le plus simple pour comprendre JSON Schema est de voir un exemple!

Prenant en exemple, une API User qui permet d’ajouter des utilisateurs. Exemple de données JSON qu’elle prend en entrée:

{
	"name": "Cyril",
	"job": "développeur"
}

Et voici un JSON Schema correspondant à notre exemple:

{
	"definitions": {},
	"$schema": "http://json-schema.org/draft-07/schema#", 
	"$id": "https://example.com/object1610898367.json", 
	"title": "Root", 
	"type": "object",
	"properties": {
		"name": {
			"$id": "#root/name", 
			"title": "Name", 
			"type": "string"
		},
		"job": {
			"$id": "#root/job", 
			"title": "Job", 
			"type": "string"
		}
	}
}

Le format est assez simple à lire. Voyons ensemble les principaux attributs:

  • $schema: C’est la version de JSON Schema. Comme vous pouvez le voir, nous sommes encore à une version Draft!
  • $id: ID unique de notre schema.
  • properties: C’est un tableau contenant les attributs de notre structure JSON.
  • « type »: Type de données. Objets (object), tableaux (array), string, …

Il est possible d’indiquer plus de chose dans un JSON Schema:

{
	"definitions": {},
	"$schema": "http://json-schema.org/draft-07/schema#", 
	"$id": "https://example.com/object1610898367.json", 
	"title": "Root", 
	"type": "object",
	"required": [
		"name",
		"job"
	],
	"properties": {
		"name": {
			"$id": "#root/name", 
			"title": "Name", 
			"type": "string",
			"default": "",
			"examples": [
				"Cyril"
			],
			"pattern": "^.*$"
		},
		"job": {
			"$id": "#root/job", 
			"title": "Job", 
			"type": "string",
			"default": "",
			"examples": [
				"developer"
			],
			"pattern": "^.*$"
		}
	}
}

On a de nouveaux attributs:

  • required: Cela permet d’indiquer les attributs obligatoires.
  • examples: On peut mettre des exemples, c’est pratique pour les documentations.
  • patern: On peut indiquer des expressions régulières pour les string.

Et voilà, on a fini cette petite introduction à JSON Schema. Faîtes un petit tour sur le site officiel de JSON Schema.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *