
Formats et contrats d’échange
JSON Merge Patch voyage : champs retirés et listes remplacées
Une petite correction peut retirer une consigne ou remplacer tous les équipements d’une offre. Préparez l’état initial, le changement demandé et le résultat attendu, puis vérifiez la portée du format de mise à jour utilisé.
Voir précisément ce qui disparaît dans une fiche
Exemple fictif : la fiche possède deux équipements et une ancienne consigne d’accès. Le changement demande le retrait de la consigne et la liste wifi seule. Le résultat montre pourquoi une liste incomplète peut retirer une information encore valable.
| État | Document pédagogique | Lecture métier |
|---|---|---|
| Avant | {"equipements":["wifi","piscine"],"acces":"Porte A"} | Deux équipements et une consigne. |
| Patch | {"equipements":["wifi"],"acces":null} | La liste est remplacée ; la consigne est retirée. |
| Après | {"equipements":["wifi"]} | La piscine et le champ accès ne figurent plus dans la fiche. |
- ConservéUn champ absent du patch reste inchangé dans un objet cible.
- RemplacéUne liste reçue devient la liste complète.
- Suppriménull retire le membre concerné de l’objet.
Le retrait de la piscine est voulu seulement si la liste reçue exprime bien l’état complet attendu. Le retrait d’accès mérite un contrôle distinct : l’équipe terrain doit savoir si la consigne est obsolète ou momentanément inconnue. Si votre modèle a besoin de conserver une propriété avec la valeur null, ne donnez pas à ce même document le sens de Merge Patch sans examiner le contrat. Après transformation, validez la fiche obtenue et relisez les écrans qui l’utilisent. Le simulateur associé permet de comparer ces documents localement.
Référence : RFC 7396, règles de JSON Merge Patch. Exemples fictifs ; les règles propres à une API doivent être confirmées auprès de son fournisseur.
Le repère documentaire et sa portée
Dans un objet Merge Patch, null retire un membre ; une liste remplace la liste entière. Un patch non objet remplace toute la cible. Transformation des valeurs JSON selon RFC 7396 ; ce mécanisme doit être explicitement supporté par l’API avant tout usage.
Confirmer le format avant d’interpréter le changement
Demandez le mécanisme de l’opération : document complet, format propre au fournisseur, JSON Merge Patch ou autre contrat. Une méthode HTTP PATCH ne suffit pas à établir le sens de son corps. Notez l’endpoint et le type de contenu attendu. Le guide et le simulateur ne prouvent pas qu’une API voyage accepte ce format.
Comparer les trois documents
Conservez la cible fictive, le patch demandé et le résultat attendu par l’équipe métier. Faites examiner les champs qui restent et ceux qui disparaissent. Une correction de description ne doit pas supprimer une information encore utile par accident. Le test doit montrer les différences lisibles, puis expliquer lesquelles sont voulues.
Préparer un remplacement de liste
Scénario fictif : une fiche contient trois équipements et le changement n’en mentionne plus qu’un. Demandez si le résultat attendu est une liste complète ou l’ajout d’un élément. Faites rejouer le cas avant de publier. Si l’application doit agir sur un élément identifié, choisissez l’opération documentée qui répond à ce besoin au lieu de supposer un comportement d’ajout.
Traiter les suppressions comme des décisions
Un champ retiré peut représenter une ancienne consigne, un prix ou un lien. Désignez qui peut demander ce retrait et qui doit relire ses conséquences dans les pages et documents. Si une donnée inconnue doit rester explicitement représentée par null, examinez un format adapté à cet usage. Gardez la suppression séparée d’une absence de nouvelle information.
Dossier d’exercice · données fictives
Tester un patch sur une copie avant de décider de son effet métier
Une fiche fictive contient un nom, une consigne et deux langues. Le patch retire la consigne, conserve le nom et remplace la liste des langues par le seul français. La démonstration compare les documents ; elle n’applique aucune modification à un catalogue ou à une réservation.
- Valeur conservéeAbsent
Le nom n’est pas mentionné dans le patch de l’exemple.
- Membre suppriménull
La consigne est retirée de l’objet.
- Remplacement entierListe
La nouvelle liste ne fusionne pas ses éléments avec l’ancienne.
| Changement | Résultat du modèle | Décision à rapprocher |
|---|---|---|
| Consigne à null | Propriété retirée | Retrait voulu ou information momentanément inconnue ? |
| Langues à [fr] | Liste finale à un élément | L’anglais est-il réellement retiré ? |
| Nom absent du patch | Nom conservé | S’agit-il bien de la bonne fiche ? |
| Patch entier égal à null | Document entier remplacé par null | Cette opération est-elle admise par le métier ? |
Ce que le rapprochement permet de comprendre
Un résultat conforme au mécanisme de fusion peut rester inacceptable pour l’exploitation. Préparer le diff, le périmètre et la validation métier avant toute utilisation sur une vraie ressource.
Simuler une fusion sur des documents fictifs
Le lecteur applique JSON Merge Patch dans cette page, sans envoi ni sauvegarde. Utilisez des exemples fictifs. Limites du lecteur : 16 000 caractères par document, 30 niveaux, 3 000 valeurs par document ; nombres finis et entiers représentables sans perte par JavaScript. Les décimaux suivent la précision des nombres JavaScript ; si une clé est répétée, seule sa dernière valeur est conservée. Ce lecteur n’est pas un validateur de contrat fournisseur.
Résultat de la copie de travail
{
"nom": "Visite démo",
"langues": [
"fr"
]
}Un champ retiré ou une liste remplacée reste un effet à faire valider pour le dossier. Le résultat ne signifie pas qu’une réservation a été modifiée.
Quatre situations à rejouer
Ouvrir un cas pour lire son résultat et les éléments à retrouver. Les chiffres, horaires et références des situations sont fictifs ; les règles de votre dossier restent à confirmer.
Un tableau contient un objet à compléter
Le patch fournit une liste avec un seul objet enrichi ; il ne complète pas automatiquement les autres objets de l’ancienne liste.
À retrouver ou à transmettre. Reconstituer la liste finale voulue et retrouver les identifiants avant validation.
L’objet cible est remplacé par une chaîne
Un patch non objet remplace toute la cible selon le mécanisme décrit.
À retrouver ou à transmettre. Distinguer résultat du format et contrat du champ. Une chaîne peut être un résultat technique valide mais un dossier métier invalide.
Le métier veut garder une valeur nulle
Dans un patch objet, null est utilisé pour supprimer un membre.
À retrouver ou à transmettre. Retrouver un autre format ou une convention adaptée si une vraie valeur nulle doit être conservée ; ne pas confondre suppression et donnée inconnue.
La cible réelle a changé depuis la copie
Le patch a été préparé sur une ancienne fiche alors qu’une autre personne a corrigé l’accès.
À retrouver ou à transmettre. Revalider la version et les préconditions de l’opération. Le simulateur local ne vérifie aucun état fournisseur.
IETF — RFC 7396, JSON Merge Patch · consultée le . Règles de fusion d’objet, suppression par null et remplacement des autres valeurs. Les fiches et décisions métier sont fictives.
Faire approuver le résultat avant application
Utilisez des exemples fictifs dans le simulateur local, puis conservez le résultat voulu et les limites. L’essai ne transmet aucune opération au fournisseur. Une application réelle exige les droits, la version courante, les contrôles métier et la possibilité de retrouver l’état avant changement. Le document final doit permettre à un collègue de relire ce qui sera retiré ou remplacé.
Approfondir le parcours : JSON Pointer : désigner le bon champ d’un catalogue
Une mise à jour partielle et une référence JSON Pointer répondent à des besoins différents. Avant de préparer une modification, retrouvez le champ réellement désigné, ses clés et son contexte. Une erreur de chemin ne doit pas devenir un effacement ou une valeur par défaut.
JSON Pointer : désigner le bon champ d’un catalogue · Rapprocher les preuves du parcours
JSON Merge Patch : distinguer suppression et remplacement
Le comportement porte sur la structure JSON, avant toute interprétation métier. Il ne faut pas lui attribuer les règles d’un autre format de patch.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Membre à null | Dans un patch objet, null demande le retrait du membre correspondant de la cible. | Ne pas utiliser cette écriture pour enregistrer simplement une valeur métier nulle. |
| Liste | Une liste fournie remplace la liste entière ; le format n’actualise pas un élément par son identifiant. | Vérifier l’effet sur toutes les prestations restantes avant un patch de dossier. |
| Patch non objet | Une valeur de patch qui n’est pas un objet remplace la cible entière. | Contrôler le type racine et l’autorisation de l’opération avant l’envoi. |
Un résultat JSON conforme ne prouve pas qu’une modification de réservation est acceptée par le fournisseur.
IETF — RFC 7396, traitement et exemples · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Sources et périmètre des faits documentés
La date de consultation figure avec chaque référence. Les méthodes d’essai et recommandations de ce guide sont éditoriales ; les conditions d’accès et d’usage se vérifient dans la documentation actuelle.
- IETF — RFC 7396, traitement et exemples : Un résultat JSON conforme ne prouve pas qu’une modification de réservation est acceptée par le fournisseur. (consultée le )
- RFC 7396, règles de JSON Merge Patch : Référence technique du format ; exemples métier fictifs. (consultée le )
- IETF — RFC 7396, JSON Merge Patch : Règles de fusion d’objet, suppression par null et remplacement des autres valeurs. Les fiches et décisions métier sont fictives. (consultée le )
Questions fréquentes
Questions utiles avant de décider
PATCH signifie-t-il automatiquement Merge Patch ?
Le format de corps doit être établi par l’API. La méthode HTTP ne suffit pas à choisir les règles de transformation.
Le simulateur modifie-t-il un catalogue fournisseur ?
Il calcule un résultat dans le navigateur à partir des deux textes fournis. Il n’envoie pas d’opération à une API.
Comment montrer une correction sans retirer les autres équipements ?
Préparez le résultat complet voulu et utilisez l’opération documentée pour cet usage. Faites relire la liste avant toute application.
Envoyer un équipement ajoute-t-il cet équipement à la liste ?
En JSON Merge Patch, une liste remplace la liste entière. Pour un ajout isolé, utilisez une opération explicitement documentée par l’API ou soumettez la liste complète voulue.




