# Règles de liaison JSON (JSON Binding Rules)

# Préface

Cette section contient des informations sur la manière d’utiliser ce document.

# Conventions Utilisées dans ce Document

Les conventions suivantes sont utilisées dans ce document pour identifier les types d’informations spécifiés.

Type d’information	Convention	Exemple
Éléments de l’API, tels que ressources	Gras	/authorization
Variables	Italique entre accolades	{ID}
Termes du glossaire	Italique à la première occurrence ; défini dans Glossaire	Le but de l’API est de permettre des transactions financières interopérables entre un Payeur (un payeur de fonds électroniques dans une transaction de paiement) situé dans un FSP (une entité qui fournit un service financier numérique à un utilisateur final) et un Bénéficiaire (un destinataire de fonds électroniques dans une opération de paiement) situé dans un autre FSP.
Documents de référence	Italique	Les informations utilisateur ne doivent, en général, pas être utilisées par les déploiements API ; les mesures de sécurité détaillées dans Signature API et Chiffrement API doivent être utilisées à la place.

# Informations sur la Version du Document

Version	Date	Description des modifications
1.0	2018-03-13	Version initiale

# Introduction

L’objectif de ce document est d’exprimer le modèle de données utilisé par l’API ouverte pour l’interopérabilité des Fournisseurs de Services Financiers (FSP) (ci-après appelée « l’API ») sous la forme de règles de liaison JSON Schema, ainsi que les règles de validation de leurs instances correspondantes.

Ce document complète et développe l’information fournie dans Open API for FSP Interoperability Specification. Les contenus de la spécification sont listés dans Vue d’ensemble de l’API FSPIOP.

Les types utilisés dans l’API PDP relèvent principalement de trois catégories :

Types de données et formats de base utilisés
Types d’éléments
Types complexes

Les différents types utilisés dans Définition de l’API, Modèle de Données et Spécification Open API, ainsi que les règles de transformation JSON auxquelles leurs instances doivent se conformer, sont identifiés dans les sections suivantes.

# Spécification Open API pour l’interopérabilité des FSP

La spécification Open API pour l’interopérabilité des FSP inclut les documents suivants.

# Documents Logiques

# Documents de Liaison REST Asynchrone

# Intégrité des Données, Confidentialité et Non-répudiation

# Documents Généraux

Glossaire

# Mots-clés et Utilisation

Les mots-clés utilisés dans les Schémas JSON et les règles sont dérivés de la Spécification JSON Schema^{1 (opens new window)}. Les types de mots-clés employés sont identifiés dans les sections Mots-clés de validation, Mots-clés de métadonnées et Instance-et-$ref. Comme expliqué plus en détail plus loin, certains de ces mots-clés spécifient des paramètres de validation tandis que d’autres sont plus descriptifs, comme les métadonnées. La description suivante précise, par exemple, si un champ DOIT^{2 (opens new window)} être présent dans la définition ou s’il est associé à un certain type de données.

# Mots-clés de validation

Cette section^{3 (opens new window)} fournit des descriptions des mots-clés utilisés pour la validation dans la Définition de l’API. Les mots-clés de validation dans un schéma imposent des exigences pour la validation réussie d’une instance.

# maxLength

La valeur de ce mot-clé DOIT être un entier non négatif. Une instance chaîne est valide vis-à-vis de ce mot-clé si sa longueur est inférieure ou égale à la valeur de ce dernier. La longueur d’une instance chaîne est le nombre de ses caractères selon la RFC 7159 [RFC7159].

# minLength

La valeur de ce mot-clé DOIT être un entier non négatif. Une instance chaîne est valide pour ce mot-clé si sa longueur est supérieure ou égale à la valeur de ce dernier. Omettre ce mot-clé a le même effet que de lui assigner la valeur 0.

# pattern

La valeur de ce mot-clé DOIT être une chaîne de caractères. Cette chaîne DEVRAIT être une expression régulière valide selon la syntaxe ECMA 262. Une instance chaîne est valide si l’expression régulière correspond avec succès. Rappel : les expressions régulières ne sont pas implicitement ancrées.

# items

La valeur de items DOIT être un schéma JSON valide ou un tableau de schémas valides. Ce mot-clé détermine comment les instances enfants sont validées pour les tableaux ; il ne valide pas directement l’instance elle-même. Si items est un schéma, la validation réussit si tous les éléments du tableau valident contre ce schéma. Si items est un tableau de schémas, la validation réussit si chaque élément valide contre le schéma à la même position. Omettre ce mot-clé a le même effet que de spécifier un schéma vide.

# maxItems

La valeur de ce mot-clé DOIT être un entier non négatif. Une instance de tableau est valide contre maxItems si sa taille est inférieure ou égale à cette valeur.

# minItems

La valeur de ce mot-clé DOIT être un entier non négatif. Une instance de tableau est valide contre minItems si sa taille est supérieure ou égale à cette valeur. Omettre ce mot-clé a le même effet que la valeur 0.

# required

La valeur de ce mot-clé DOIT être un tableau. Les éléments DOIVENT être des chaînes de caractères uniques. Une instance objet est valide contre ce mot-clé si chaque élément du tableau est le nom d’une propriété présente dans l’instance. Omettre ce mot-clé revient à avoir un tableau vide.

# properties

La valeur de properties DOIT être un objet. Chaque valeur de cet objet DOIT être un schéma JSON valide. Ce mot-clé définit comment les enfants sont validés pour les objets ; il ne valide pas l’instance elle-même. La validation réussit si, pour chaque nom commun entre l’instance et le schéma, l’instance enfant valide contre le schéma correspondant. Omettre ce mot-clé revient à un objet vide.

# enum

La valeur de ce mot-clé DOIT être un tableau. Il DEVRAIT inclure au moins un élément. Les éléments DEVRAIENT être uniques. Une instance valide contre ce mot-clé si sa valeur est égale à un des éléments du tableau. Les éléments peuvent être de toute valeur, y compris null.

# type

La valeur de ce mot-clé DOIT être une chaîne ou un tableau. Si c’est un tableau, les éléments DOIVENT être des chaînes uniques. Les chaînes DOIVENT être un des six types primitifs (null, boolean, object, array, number, ou string), ou integer pour les entiers. Une instance valide si et seulement si elle fait partie de l’un des ensembles listés pour ce mot-clé.

Cette spécification utilise le type string pour tous les types de base et d’éléments, mais applique des restrictions avec des expressions régulières via patterns. Les types complexes sont des objets et contiennent des propriétés de type élément ou objet à leur tour. Les types array servent à spécifier des listes, actuellement seulement utilisées dans des types complexes.

# Mots-clés de métadonnées

Cette section décrit les champs utilisés dans les définitions JSON des types. Elle précise si un champ DOIT être présent dans la définition et s’il est associé à un type de données principal.

# definitions

La valeur de ce mot-clé DOIT être un objet. Chaque membre DOIT être un schéma JSON valide. Ce mot-clé ne joue pas de rôle dans la validation. Il offre un emplacement standardisé pour inclure des schémas JSON dans un schéma plus général.

# title et description

La valeur des deux mots-clés DOIT être une chaîne. Ces deux mots-clés peuvent fournir à une interface utilisateur des informations sur les données produites. Un titre sera de préférence court, tandis qu’une description expliquera le but de l’instance décrite.

# Instance et $ref

Deux mots-clés, Instance et $ref sont utilisés dans les définitions JSON Schema ou les règles de transformation dans ce document, décrits dans Instance et Références de Schéma avec $ref. Instance n’est pas utilisé dans la Spécification Open API ; ce terme sert à décrire des règles de validation et de transformation dans ce document. $ref contient une URI comme référence à d’autres types ; il est utilisé dans la Spécification.

# Instance

JSON Schema interprète les documents selon un modèle de données. Une valeur JSON interprétée selon ce modèle est appelée une instance^{4 (opens new window)}. Une instance a un des six types primitifs, et une plage de valeurs selon le type :

null : Production JSON null.
boolean : Valeur true ou false de la production JSON.
object : Ensemble non ordonné de propriétés associant une chaîne à une instance (production object).
array : Liste ordonnée d’instances (production array JSON).
number : Nombre décimal en précision arbitraire, base-10, production number.
string : Suite de points de code Unicode (production string JSON).

Les espaces et le formatage sont hors du périmètre du JSON Schema. Comme un objet ne peut pas avoir deux propriétés avec la même clé, le comportement d’un document JSON essayant d’avoir deux propriétés de même nom est indéfini.

# Références de schéma avec le mot-clé $ref

Le mot-clé $ref^{5 (opens new window)} sert à référencer un schéma et permet de valider des structures récursives via l’auto-référence. Un objet schéma avec une propriété $ref DOIT être interprété comme référence. La valeur de $ref DOIT être une référence URI. Concernant l’URI de base courante, elle identifie l’URI d’un schéma à utiliser. Toutes autres propriétés d’un objet $ref DOIVENT être ignorées.

L’URI n’est pas un localisateur réseau, seulement un identifiant. Un schéma n’a pas besoin d’être téléchargeable à partir de l’adresse si c’est une URL réseau, et les implémentations ne DOIVENT PAS effectuer d’opération réseau quand elles rencontrent une URI réseau. Un schéma NE DOIT PAS tourner en boucle infinie sur un schéma. Par exemple, si deux schémas "#alice" et "#bob" ont une propriété "allOf" qui référence l’autre, un validateur naïf pourrait passer en boucle. Les schémas NE DOIVENT PAS utiliser de telles boucles récursives ; le comportement est indéfini.

On l’utilise avec la syntaxe "$ref" et il est mappé à une définition existante. La syntaxe de la valeur _$ref_, #/definitions/, indique que le type référencé vient de la section Définitions de la Spécification Open API (typiquement, les sections sont Paths, Definitions, Responses et Parameters). Un exemple se trouve en Liste 26, où les types pour les propriétés authentication et authenticationValue sont fournis par des références vers les types AuthenticationType et AuthenticationValue.

# Définitions JSON et exemples

Les définitions JSON et exemples sont fournis après la plupart des sections définissant les règles de transformation, si pertinent. Ils sont fournis au format JSON, tirés de la version JSON de la Spécification Open API. Les expressions régulières dans les exemples peuvent avoir de petites différences (parfois un ‘\’ supplémentaire) par rapport à celles des règles car les exemples sont issus de la version JSON alors que les règles viennent de la spécification standard Open API (Swagger). Ils sont fournis dans la section concernée sous forme de Liste numérotée. Par exemple, Liste 1 fournit la version JSON de la définition du type de données Amount.

Pour chaque type de données, une description du schéma JSON extrait de la Spécification Open API et (si pertinent) un exemple pour ce type sont fournis. Après la description du schéma, viennent les règles de transformation qui s’appliquent à une instance de ce type particulier.

# Types d’éléments et types de base

Cette section contient les définitions et règles de transformation pour les formats de base et les types éléments utilisés par l’API comme spécifié dans API Definition et API Data Model. Ces définitions sont basiques dans le contexte de la spécification API, mais pas dans la spécification technique Open API. Souvent, ces types de données de base sont dérivés des types de base supportés par Open API, comme le type string.

# Type de données Amount

Cette section fournit la définition JSON Schema pour le type de données Amount. Liste 1 fournit le schéma JSON pour le type Amount.

Paire clé-valeur JSON avec Nom "title" et Valeur "Amount"
Paire clé-valeur JSON avec Nom "type" et Valeur "string"
Paire clé-valeur JSON avec Nom "pattern" et Valeur "^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])?$"
Paire clé-valeur JSON avec Nom "description" et Valeur "Le type de données Amount de l’API est une chaîne JSON dans un format canonique, restreint par une expression régulière pour des raisons d’interopérabilité. Ce format n’autorise pas de zéros en fin, mais permet un montant sans unité mineure de devise. Seules quatre décimales au plus dans l’unité mineure ; aucune valeur négative n’est permise. Pas plus de 18 chiffres dans l’unité majeure."

# Liste 1

"Amount": {
    "title": "Amount", 
    "type": "string", 
    "pattern":
    "^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])?$",
    "maxLength": 32, 
    "description": "Le type de données Amount de l’API est une chaîne JSON dans un format canonique, restreint par une expression régulière pour des raisons d’interopérabilité." 
}

Liste 1 -- JSON Schema pour le type Amount

Les règles de transformation pour une instance du type Amount sont les suivantes :

Une instance du type Amount DOIT être de type string.
L’instance DOIT correspondre à l’expression régulière ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])?$
La longueur de cette instance est limitée comme ci-dessus à 23, avec 18 chiffres pour l’unité majeure et 4 pour l’unité mineure. Exemples valides : 124.45, 5, 5.5, 4.4444, 0.5, 0, 181818181818181818

← Cas d’utilisation Règles du système →