Guides pratiques approfondis

Conserver une version reproductible de données publiques

Relier fichier source, date, schéma et transformations : préparer un jeu de données que l’on peut retrouver, comparer et réutiliser sans confondre mise à jour, correction et changement de périmètre.

Mise à jour :

Contrôle de fichiers et de tableaux sur un poste de travail organisé.

Illustration générée par IA

Un autre lecteur peut-il reconstruire le résultat ?

Un lien vers une base évolutive ne décrit pas les données réellement utilisées. Une correction peut modifier une ancienne série, un export perdre des zéros initiaux et une nouvelle colonne changer le sens d’un total. Conserver une version utile signifie expliquer la matière de départ et le chemin suivi. L’objectif est la reproductibilité du travail décrit, pas une garantie universelle sur la qualité de la source.

  1. Définir le périmètre

    Nommer producteur, dataset, territoire, population, période et filtres. Distinguer date d’observation, de publication et de téléchargement. Un export reçu aujourd’hui peut décrire une période ancienne. Écrire la question à laquelle le jeu doit répondre et les exclusions qui comptent pour l’interprétation.

  2. Conserver l’entrée utilisée

    Enregistrer URL ou paramètres publics, date de récupération et fichier reçu lorsque les conditions le permettent. Attribuer un identifiant de version et calculer une empreinte du fichier. L’empreinte aide à distinguer deux fichiers ; elle ne prouve pas que leurs valeurs sont exactes. Conserver les informations de licence.

  3. Décrire le schéma

    Documenter champs, types, unités, clés et valeurs manquantes. Pour un CSV, vérifier séparateur, encodage, guillemets et retours à la ligne selon l’export réel. Garder comme texte les identifiants qui exigent leurs zéros initiaux. Distinguer zéro, valeur absente et valeur non applicable.

  4. Tracer les transformations

    Noter filtres, normalisations, rapprochements, conversions et règles de dédoublonnage dans leur ordre. Séparer entrée brute et sortie préparée. Pour chaque rapprochement, retenir la clé et les cas non résolus. Un nom similaire ne suffit pas à fusionner deux entités. Documenter les choix plutôt que les masquer dans le fichier final.

  5. Comparer les versions

    Mesurer lignes ajoutées, retirées ou modifiées sur une clé stable lorsque celle-ci existe. Vérifier aussi structure, unités et définitions. Une évolution du nombre de lignes ne démontre pas une évolution du phénomène : elle peut venir du filtre, de la couverture ou d’une révision du producteur.

  6. Préparer la réutilisation

    Associer résultat, version source, étapes et limites. Vérifier que les liens permettent de retrouver le producteur et le contexte. Prévoir une nouvelle collecte avec critères de comparaison. Conserver une ancienne version séparément si elle soutient une conclusion publiée, en respectant les conditions et données qu’elle contient.

Atelier de lecture

Une valeur révisée ne réécrit pas ce qui était connu

Le jeu DEMO est fictif. Ses versions permettent de distinguer une analyse historique d’une analyse utilisant les données corrigées.

Données et traces fictives pour apprendre : aucun résultat présenté ici ne provient d’un service interrogé en direct.

80 en avril, 82 après correction en juin

La même clé et la même période figurent dans les deux fichiers. Le producteur fictif publie une note corrigeant la valeur. Une modification ultérieure de la notice ne touche pas le CSV.

Si le tableau dépasse l’écran, faites-le défiler horizontalement ; les flèches du clavier fonctionnent lorsque la zone est sélectionnée.

80 en avril, 82 après correction en juin
État fictifPièce disponibleCe qui changeUsage à annoncer
Version v1 disponible en avrilValeur 80 pour la clé étudiéeÉtat publié avant correctionPour décrire ce qui était accessible en avril, citer v1.
Version v2 publiée en juinValeur corrigée 82, note de révisionObservation passée corrigée, pas nouvel événementPour une analyse révisée, citer v2 et signaler la correction.
Notice retouchée après v2Description clarifiée, CSV inchangé dans le casMétadonnées seulementNe pas déduire une nouvelle valeur de la date de notice.
Deux analyses conservéesRésultat historique avec v1 ; résultat révisé avec v2Question temporelle et version sourceNe pas mélanger les versions sans l’indiquer.

Faut-il remplacer silencieusement le résultat d’avril ?

Ouvrir chaque proposition pour comparer son diagnostic. Plusieurs contrôles peuvent rester nécessaires.

Oui : seul le fichier le plus récent mérite une trace

Non. La version ancienne peut être nécessaire pour comprendre la conclusion publiée à cette date.

Non : garder la question, la version et la correction explicites

Oui. Séparer ce qui était connu en avril de l’analyse révisée en juin ; relier les sorties à leur entrée.

Une empreinte identique certifie la qualité de la donnée

Non. Elle renseigne sur les octets comparés à une référence, pas sur la justesse du nombre ni sa représentativité.

Trace fictive de versionnement

Jeu : DEMO ; clé et période inchangées
v1 : disponible en avril ; valeur=80
v2 : publiée en juin ; valeur corrigée=82
Motif : correction documentée par le producteur fictif
Notice suivante : description seule, CSV inchangé
Sorties : historique lié à v1 ; révisé lié à v2

La trace conserve les deux questions analytiques. Les empreintes identifient les fichiers utilisés sans transformer une version conservée en version vraie.

Documentation des règles, distincte des exemples fictifs

Comparer avec les autres situations et exercices

Les identifiants changent après ouverture

Un logiciel interprète une colonne comme nombre et retire les zéros initiaux. Repartir de l’export brut, imposer le type texte pour cette clé et vérifier les rapprochements. Reformater visuellement une valeur déjà altérée ne reconstitue pas forcément l’identifiant original.

Une série historique est révisée

Le fichier nouveau remplace aussi des valeurs anciennes. Comparer sur période et clé, conserver les deux versions et lire les notes du producteur. Distinguer correction des observations et arrivée de nouvelles observations avant de décrire une tendance.

Le fichier grossit sans amélioration mesurée

L’export couvre désormais davantage de territoires ou catégories. Comparer le périmètre commun, puis présenter séparément l’extension. Documenter les changements de champ et les valeurs manquantes au lieu de traiter toutes les lignes comme directement comparables.

Comparer sans confondre absence et modification

Exemple fictif : A passe de 10 à 11, B disparaît et C arrive. Sur la clé id, le résultat compte une clé ajoutée, une retirée et une ligne commune modifiée. Si une colonne apparaît, elle est listée séparément ; aucune ancienne valeur ne lui est inventée. Un simple réordonnancement donne zéro modification.

Exercice corrigé

Décomposer une hausse entre révision et ajout

Exemple fictif : les valeurs et documents servent à apprendre la méthode, sans décrire un organisme réel.

Clé unique, champ additif et dictionnaire inchangé. Aucun objet n’est supprimé ; « absent » signifie clé absente de cette version.

Si le tableau dépasse l’écran, faites-le défiler horizontalement ; les flèches du clavier fonctionnent lorsque la zone est sélectionnée.

Données de départ
CléVersion V1Version V2
A1010
B2025
CAbsent5

À vous de vérifier

  1. Comparer les lignes sur leur clé exacte.
  2. Séparer modification de B et ajout de C.
  3. Réconcilier la différence des totaux.
Lire le corrigé

Corrigé et décision

V1 totalise 30 et V2 40 : +10. Sur les clés communes, la révision de B explique +5 ; la nouvelle clé C ajoute +5. A est inchangée. La hausse de 33,33 % du total ne doit pas être attribuée entièrement à la progression des objets déjà présents.

Si le cas change

Si l’unité ou la définition change en V2, suspendre cette décomposition jusqu’à la vérification de comparabilité.

Trace à conserver

Garder exports et empreintes, dictionnaires, clés ajoutées/modifiées et formule de réconciliation.

Preuve à conserver

  • Producteur, URL, paramètres publics, licence et dates distinctes.
  • Version du fichier, empreinte, schéma, unités et conventions de valeurs manquantes.
  • Transformations ordonnées, clés de rapprochement et cas non résolus.
  • Comparaison des versions, résultat reconstruit et limites d’interprétation.

Références officielles

Protocoles connexes

Points à vérifier avant de conclure

  • Un identifiant conserve-t-il exactement ses caractères après import et export, notamment ses zéros initiaux ?
  • La comparaison sépare-t-elle changements de valeurs, de schéma et de couverture plutôt que de résumer tout écart par un nombre de lignes ?
  • Un autre lecteur peut-il reconstruire la sortie à partir de la version conservée et de l’ordre des transformations documentées ?

Questions fréquentes

Faut-il sauvegarder chaque export ?

Conserver les versions nécessaires au travail et aux conclusions publiées selon une règle définie. Éviter les copies sans rôle et respecter les conditions de conservation et de réutilisation.

Une empreinte garantit-elle la qualité ?

Non. Elle sert à reconnaître un contenu de fichier et à repérer un changement, pas à valider sa source, son interprétation ou ses valeurs.

Peut-on fusionner des lignes sur le nom ?

Vérifier d’abord la clé, le contexte et les homonymes. Une règle de rapprochement doit prévoir les cas ambigus et conserver une trace des fusions.

Comment afficher une donnée corrigée ?

Indiquer la version et la correction pertinente, puis distinguer le résultat révisé du résultat publié auparavant. Ne pas présenter une révision comme une nouvelle observation.

Pourquoi refuser une clé répétée ?

Deux lignes avec le même identifiant rendent le rapprochement ambigu. Examinez leur grain, leur période et leur provenance, puis définissez une clé composée si nécessaire. Ne supprimez pas une ligne avant d’avoir établi s’il s’agit d’un doublon ou d’une observation distincte.

Que conserver avec une version de données ?

Le fichier, sa provenance, sa date, son empreinte et la documentation utile. Ajouter les règles de transformation et la référence des résultats produits facilite une reproduction et une comparaison ultérieures.

REPÈRES DOCUMENTÉS

Provenance PROV : relier une version, un traitement et une responsabilité

Le modèle PROV-O du W3C aide à décrire comment un document ou un jeu de données a été produit. Les flèches du schéma suivent le sens des propriétés PROV, pas un ordre chronologique de lecture de gauche à droite. E0, A et E1 sont des repères pédagogiques et ne représentent pas des ressources réelles.

E0 · EntityA · ActivityE1 · EntityusedwasGeneratedBywasDerivedFrom
Provenance PROV : relier une version, un traitement et une responsabilité
RepèreValeur ou formeCe que cela désigne
prov:EntityDonnées ou document dans un état décritUne entité peut représenter un document ou des données dans un état décrit. Donner des identifiants distincts aux versions permet de dire laquelle a été utilisée ; une URL qui change de contenu ne suffit pas à décrire toutes ses versions.
prov:ActivityProcessus dans le tempsUne activité représente un processus qui se déroule dans le temps et agit sur des entités : transformation, calcul ou publication, selon le cas décrit. Elle n’est pas l’objet produit par ce processus.
prov:AgentPersonne, organisation ou agent logicielUn agent porte une forme de responsabilité. wasAttributedTo relie une entité à un agent ; wasAssociatedWith relie une activité à un agent. Ces relations ne prouvent pas une licence ni une responsabilité juridique exhaustive.
prov:usedActivity → EntityLa propriété part de l’activité vers l’entité utilisée. Dans le schéma, A utilise E0. Garder ce sens évite de décrire par erreur la source comme un processus exécuté par le fichier final.
prov:wasGeneratedByEntity → ActivityLa propriété part de l’entité générée vers l’activité. Dans le schéma, E1 a été générée par A ; ce n’est pas une relation entre deux versions à confondre avec une dérivation.
prov:wasDerivedFromEntity → EntityLa propriété part du résultat vers une entité source. Elle indique une dérivation, sans fournir à elle seule la formule, les paramètres, les poids d’une agrégation ni une preuve de fidélité.
prov:wasRevisionOfEntity → EntityUne révision est un cas plus précis de dérivation où le résultat est une version révisée de l’original et en conserve un contenu substantiel. Ne pas déclarer toute simple citation comme une révision du document cité.
prov:wasQuotedFromEntity → EntityUn passage est répété depuis une source plus longue. Conserver aussi le passage exact et son repère ; la relation seule ne localise pas les mots.

Citation, traduction ou révision ?

Quatre cas fictifs montrent pourquoi le lien doit décrire la transformation réelle. Le résultat est le sujet de chaque relation ; la source ou l’agent est à droite.

Un extrait recopié

quote → prov:wasQuotedFrom → source-v1

Un passage est répété depuis une source plus longue. Conserver aussi le passage exact et son repère ; la relation seule ne localise pas les mots.

Une traduction

translation → prov:wasDerivedFrom → source-v1

La traduction constitue une nouvelle entité dérivée. Conserver langue source, langue cible, version et contrôle de fidélité ; un texte traduit ne doit pas se présenter comme l’extrait original.

Une correction du document

source-v2 → prov:wasRevisionOf → source-v1

La version corrigée reprend une part substantielle de la précédente. Garder les deux états et les changements ; le lien ne dit pas quelle version est exacte.

L’attribution du résultat

analysis → prov:wasAttributedTo → editor

L’entité est attribuée à un agent. Pour la responsabilité d’un traitement, employer Activity → prov:wasAssociatedWith → Agent. Une attribution ne suffit pas à établir des droits de réutilisation.

La provenance décrit une chaîne déclarée. Elle ne transforme ni une traduction en preuve indépendante, ni une attribution en validation du contenu.

À retenir pour le dossier

Décrire entrées, sortie, activité et agent quand ils sont connus, sans inventer les éléments manquants. Une chaîne de provenance documente une affirmation de transformation ; elle ne valide pas automatiquement le calcul, les droits ou l’authenticité des fichiers. Associer version, date et référence à la source pour permettre un examen indépendant.

Un lien wasDerivedFrom suffit-il pour reproduire un indicateur ?

Non. Il signale une source, mais la reproduction demande aussi les versions exactes, les filtres, la formule, les paramètres et les conventions de valeurs absentes. Plusieurs méthodes peuvent dériver des résultats différents d’une même source.

Documentation primaire

Documentation consultée le .

REPÈRES DOCUMENTÉS

Assembler des fragments : couverture, trous et identité de représentation

Additionner les longueurs reçues peut masquer un téléchargement incomplet : un chevauchement compte plusieurs fois les mêmes positions. Il faut calculer l’union des intervalles, puis la comparer à la représentation visée. Ce contrôle géométrique reste distinct du contrôle des octets et de leur provenance.

Assembler des fragments : couverture, trous et identité de représentation
RepèreValeur ou formeCe que cela désigne
0-399,300-599,700-999Σ = 1000; ∪ = 900Avec L = 1 000, les fragments 0–399, 300–599 et 700–999 totalisent 1 000 octets déclarés. Leur union couvre seulement 900 positions : 600–699 manque et 100 réceptions d’octets sont redondantes.
0-499,500-999∪ = 1000Les intervalles adjacents se réunissent sans trou : 0–499 et 500–999 couvrent 1 000 positions. Répéter trois fois un même octet ajoute deux réceptions redondantes, pas deux positions distinctes chevauchées.
Content-Rangefirst ≤ last < LUn Content-Range de réponse doit avoir une fin au moins égale au début et une longueur totale, si connue, strictement supérieure à cette fin. Une longueur inconnue notée * ne permet pas de conclure à une couverture totale.
ETagstrong validatorLe rapprochement de fragments exige la même représentation. Pour combiner des réponses partielles en cache, RFC 9111 demande un validateur fort commun et les conditions de recombinaison HTTP. Une URL ou une taille identique ne remplace pas ce contrôle.
If-Rangestrong comparisonIf-Range utilise une comparaison forte d’ETag. Un client ne doit pas y envoyer un ETag faible ; si la condition échoue, Range est ignoré et le transfert complet est demandé. Une date n’est admissible que sous les conditions de validateur fort prévues par HTTP.

Contrôler la couverture de fragments

Exemples pédagogiques originaux ; aucune mesure d’un serveur réel.

L : entier de 1 à 1 000 000 000 000. De 1 à 20 intervalles a-b inclusifs, un par ligne ; bornes dans la représentation. Lignes vides ignorées, espaces et tabulations autour des lignes autorisés. 2 000 caractères maximum ; pas d’en-tête HTTP.

Calcul local dans votre navigateur ; aucune donnée saisie n’est transmise ni conservée.

Calcul actualisé.

Somme des longueurs déclarées
1000
Positions distinctes couvertes
900
Réceptions d’octets redondantes
100
Positions manquantes
100

Couverture arithmétique uniquement : l’identité de représentation et l’intégrité des octets restent à vérifier.

Couverture de la représentationBarre de gauche à droite : positions de 0 à L − 1. Les segments pleins sont couverts, les segments hachurés manquent. Le tableau donne les bornes exactes ; les très petites plages peuvent être imperceptibles à cette échelle.0999
Barre de gauche à droite : positions de 0 à L − 1. Les segments pleins sont couverts, les segments hachurés manquent. Le tableau donne les bornes exactes ; les très petites plages peuvent être imperceptibles à cette échelle.
Union des fragments
Intervalle inclusifLongueur
0–599600
700–999300
Intervalles manquants
Intervalle inclusifLongueur
600–699100

Règles de calcul

sum = Σ(lastᵢ − firstᵢ + 1)
unique = |∪ intervals|
redundant = sum − unique
missing = L − unique
Huit cas de couverture
Huit cas de couverture
LFragments déclarés (a-b, un par ligne)Somme des longueurs déclaréesPositions distinctes couvertesRéceptions d’octets redondantesPositions manquantesIntervalles manquants
10000–399; 300–599; 700–9991000900100100600–699
10000–499; 500–9991000100000Aucun
10000–999; 0–9992000100010000Aucun
100–0; 0–0; 0–031291–9
109–9; 0–022081–8
102–7; 3–486240–1; 8–9
10–01100Aucun
10000000000000–999999999998; 999999999999–9999999999991000000000000100000000000000Aucun

À retenir pour le dossier

La couverture suppose des positions déclarées appartenant à une même représentation. L’outil ne lit aucun fichier, ne vérifie ni ETag, ni Content-Encoding, ni cache, ni empreinte, et ne prouve pas que les octets d’un chevauchement sont égaux. Une couverture complète n’est pas un certificat d’intégrité.

Un ETag identique suffit-il à authentifier un document ?

Non. Un ETag est un validateur HTTP, pas nécessairement une empreinte cryptographique ni une signature d’auteur. Vérifier aussi la variante, les longueurs et les octets effectivement reçus ; consigner séparément les éléments de provenance et les contrôles d’intégrité.

Documentation primaire

Documentation consultée le .

REPÈRES DOCUMENTÉS

JSON Patch : suivre les opérations sur le document courant

Une liste JSON Patch s’évalue dans l’ordre. Chaque chemin vise le document produit par les opérations précédentes, pas une photographie permanente du document initial. Les parcours ci-dessous montrent les états de calcul et les conditions d’arrêt sur neuf exemples originaux.

JSON Patch : suivre les opérations sur le document courant
RepèreValeur ou formeCe que cela désigne
addinsert / replaceadd insère à un indice de tableau et décale les éléments suivants ; le tiret final ajoute après le dernier élément. Dans un objet, add remplace aussi un membre existant. Le conteneur parent doit exister.
remove / replaceexisting targetremove et replace exigent que la cible existe. Retirer un élément de tableau décale les indices supérieurs vers la gauche : le même chemin peut ensuite désigner un autre élément.
moveremove → addmove retire d’abord la valeur de from, puis l’ajoute à path dans le document ainsi modifié. Déplacer un élément vers une position ultérieure ne permet pas de réutiliser aveuglément les anciens indices. Un déplacement vers un descendant propre est interdit.
copy / testvalue / equalitycopy ajoute la valeur référencée sans lier les deux emplacements. test compare une valeur selon les règles JSON ; il n’écrit rien et son échec arrête l’évaluation. L’ordre des membres d’un objet n’est pas significatif pour cette égalité.
HTTP PATCHatomicUne erreur arrête la séquence. Dans une requête HTTP PATCH, l’ensemble des changements doit être appliqué atomiquement : si le patch échoue, aucun changement n’est appliqué. Les états intermédiaires du lecteur servent à expliquer le calcul, pas à représenter des écritures déjà validées.
Content-Typepatch formatContent-Type distingue application/json-patch+json de application/merge-patch+json. Le support de PATCH seul ne garantit pas le support des deux formats. Une précondition HTTP comme If-Match peut prévenir une modification sur une version périmée ; test ne la remplace pas automatiquement.

Lire une séquence JSON Patch

Exemples pédagogiques originaux ; aucun document réel n’est modifié.

Choisissez un parcours et une étape. Chaque opération vise le résultat précédent. En cas d’échec, le lecteur réaffiche la cible initiale pour illustrer l’atomicité HTTP ; les étapes suivantes ne sont pas exécutées.

Lecture de parcours prédéfinis ; aucun patch libre n’est exécuté ici.

État initial · 0 / 2

Cible initiale

{
    "items": [
        "A",
        "B",
        "C"
    ]
}

Opération

Aucune opération à cette étape.

État du calcul

{
    "items": [
        "A",
        "B",
        "C"
    ]
}
Neuf parcours avec tous leurs états
Retrait et décalage d’indices
  1. État initial

    Aucune opération à cette étape.

    État du calcul

    {
        "items": [
            "A",
            "B",
            "C"
        ]
    }
  2. État intermédiaire, non validé

    Opération

    {
        "op": "remove",
        "path": "/items/0"
    }

    État du calcul

    {
        "items": [
            "B",
            "C"
        ]
    }
  3. Séquence réussie

    Opération

    {
        "op": "replace",
        "path": "/items/1",
        "value": "X"
    }

    État du calcul

    {
        "items": [
            "B",
            "X"
        ]
    }
Insertion et ajout final
  1. État initial

    Aucune opération à cette étape.

    État du calcul

    [
        "A",
        "C"
    ]
  2. État intermédiaire, non validé

    Opération

    {
        "op": "add",
        "path": "/1",
        "value": "B"
    }

    État du calcul

    [
        "A",
        "B",
        "C"
    ]
  3. Séquence réussie

    Opération

    {
        "op": "add",
        "path": "/-",
        "value": "D"
    }

    État du calcul

    [
        "A",
        "B",
        "C",
        "D"
    ]
Valeur null puis suppression
  1. État initial

    Aucune opération à cette étape.

    État du calcul

    {
        "note": "old",
        "keep": true
    }
  2. État intermédiaire, non validé

    Opération

    {
        "op": "replace",
        "path": "/note",
        "value": null
    }

    État du calcul

    {
        "note": null,
        "keep": true
    }
  3. Séquence réussie

    Opération

    {
        "op": "remove",
        "path": "/note"
    }

    État du calcul

    {
        "keep": true
    }
Copie sans liaison
  1. État initial

    Aucune opération à cette étape.

    État du calcul

    {
        "source": {
            "n": 1
        }
    }
  2. État intermédiaire, non validé

    Opération

    {
        "op": "copy",
        "from": "/source",
        "path": "/backup"
    }

    État du calcul

    {
        "source": {
            "n": 1
        },
        "backup": {
            "n": 1
        }
    }
  3. Séquence réussie

    Opération

    {
        "op": "replace",
        "path": "/source/n",
        "value": 2
    }

    État du calcul

    {
        "source": {
            "n": 2
        },
        "backup": {
            "n": 1
        }
    }
Déplacement après retrait
  1. État initial

    Aucune opération à cette étape.

    État du calcul

    [
        "A",
        "B",
        "C",
        "D"
    ]
  2. Séquence réussie

    Opération

    {
        "op": "move",
        "from": "/1",
        "path": "/3"
    }

    État du calcul

    [
        "A",
        "C",
        "D",
        "B"
    ]
Échec de test et atomicité
  1. État initial

    Aucune opération à cette étape.

    État du calcul

    {
        "rev": 1,
        "label": "A"
    }
  2. État intermédiaire, non validé

    Opération

    {
        "op": "replace",
        "path": "/label",
        "value": "B"
    }

    État du calcul

    {
        "rev": 1,
        "label": "B"
    }
  3. Échec : aucun changement appliqué dans HTTP PATCH

    Opération

    {
        "op": "test",
        "path": "/rev",
        "value": 2
    }

    État du calcul

    {
        "rev": 1,
        "label": "A"
    }
  4. Non exécutée après l’échec

    Opération

    {
        "op": "add",
        "path": "/extra",
        "value": true
    }

    État du calcul

    {
        "rev": 1,
        "label": "A"
    }
Parent absent
  1. État initial

    Aucune opération à cette étape.

    État du calcul

    {
        "a": []
    }
  2. Échec : aucun changement appliqué dans HTTP PATCH

    Opération

    {
        "op": "add",
        "path": "/missing/x",
        "value": 1
    }

    État du calcul

    {
        "a": []
    }
Échappement du chemin et racine
  1. État initial

    Aucune opération à cette étape.

    État du calcul

    {
        "a/b": {
            "~key": 1
        }
    }
  2. État intermédiaire, non validé

    Opération

    {
        "op": "test",
        "path": "/a~1b/~0key",
        "value": 1
    }

    État du calcul

    {
        "a/b": {
            "~key": 1
        }
    }
  3. Séquence réussie

    Opération

    {
        "op": "add",
        "path": "",
        "value": [
            "root"
        ]
    }

    État du calcul

    [
        "root"
    ]
add sur une propriété existante
  1. État initial

    Aucune opération à cette étape.

    État du calcul

    {
        "x": 1
    }
  2. Séquence réussie

    Opération

    {
        "op": "add",
        "path": "/x",
        "value": 2
    }

    État du calcul

    {
        "x": 2
    }

À retenir pour le dossier

Ce lecteur déroule des parcours documentés ; il n’est pas un exécuteur universel de JSON Patch. Il ne contacte pas de serveur et ne promet aucun code de réponse. L’atomicité présentée est celle d’HTTP PATCH ; une bibliothèque locale doit annoncer sa propre gestion des erreurs et des mutations.

Le mot PATCH annonce-t-il à lui seul comment traiter le corps ?

Non. Il faut le type de média et le contrat de la ressource. Accept-Patch peut annoncer les formats acceptés. Ni le nom de la méthode ni un exemple local ne prouvent que l’API distante accepte ce format ou autorise la modification.

Documentation primaire

Documentation consultée le .

REPÈRES DOCUMENTÉS

SemVer : comparer la priorité sans inventer une identité

SemVer 2.0.0 définit une grammaire et un ordre de priorité pour les versions de logiciels qui déclarent une API publique. Le comparer comme une simple chaîne ou un nombre décimal produit des erreurs. Une date de jeu de données ou un nom de tag n’adopte pas automatiquement ce contrat.

SemVer : comparer la priorité sans inventer une identité
RepèreValeur ou formeCe que cela désigne
MAJOR.MINOR.PATCH0 | [1-9][0-9]*Le noyau contient trois entiers non négatifs : MAJOR.MINOR.PATCH. Les zéros initiaux sont interdits, sauf pour le chiffre 0 seul. Le tag v1.2.3 peut désigner une publication, mais sa chaîne complète n’est pas une version SemVer stricte.
1.9.0 / 1.10.0numericLes trois nombres du noyau se comparent numériquement, de gauche à droite. Ainsi 1.9.0 précède 1.10.0. Leur longueur n’est pas bornée par SemVer : l’outil compare les chiffres sans les convertir en nombres à virgule flottante.
-alpha.1pre-releaseÀ noyau égal, une préversion précède la version normale. Ses identifiants séparés par des points ne sont pas vides. Un identifiant purement numérique n’accepte pas de zéro initial ; un identifiant contenant une lettre ou un tiret suit un autre cas.
-2 / -alphanumeric < non-numericDeux identifiants numériques se comparent numériquement ; les autres se comparent selon l’ordre ASCII. Un identifiant numérique précède un identifiant non numérique. Si tous les identifiants communs sont égaux, la préversion ayant davantage d’identifiants est prioritaire.
+001ignored in precedenceLes métadonnées après + ne participent jamais à la priorité. Contrairement aux identifiants numériques de préversion, elles peuvent contenir 001. Deux chaînes différentes peuvent donc avoir la même priorité, sans désigner des fichiers identiques ni des artefacts interchangeables.

Comparer deux versions SemVer

Exemples pédagogiques originaux ; aucune version réelle n’est évaluée.

Deux versions SemVer 2.0.0 strictes, 256 caractères ASCII maximum chacune. Aucun espace, préfixe v ou opérateur de contrainte. Les identifiants numériques sont comparés exactement, sans arrondi.

Calcul local dans le navigateur ; aucune saisie n’est transmise ni conservée.

A précède B dans l’ordre SemVer.

1.9.0 < 1.10.0

Premier critère décisif : MINOR

Composants des versions
ComposantVersion AVersion B
MAJOR11
MINOR910
PATCH00
PréversionAucunAucun
Métadonnées de constructionAucunAucun
Dix comparaisons de priorité
Dix comparaisons de priorité
Version A< / = / >Version BPremier critère décisif
1.9.0<1.10.0MINOR
2.0.0>1.99.99MAJOR
1.0.9<1.0.10PATCH
1.2.3-rc.9<1.2.3Préversion face à version normale
1.2.3-alpha.2<1.2.3-alpha.11Identifiant de préversion
1.2.3-9<1.2.3-alphaIdentifiant de préversion
1.2.3-alpha<1.2.3-alpha.0Nombre d’identifiants de préversion
1.2.3-Beta<1.2.3-alphaIdentifiant de préversion
1.2.3+linux.001=1.2.3+windows.002Métadonnées exclues de la priorité
9007199254740992.0.0<9007199254740993.0.0MAJOR
Dix cas de syntaxe stricte
Dix cas de syntaxe stricte
EntréeDiagnostic
1.2.3Valide
0.0.0-0Valide
1.2.3+001Valide
1.2.3-01aValide
1.2.3--Valide
v1.2.3Invalide
1.02.3Invalide
1.2.3-01Invalide
1.2.3-alpha..1Invalide
1.2.3+Invalide

Interprétation et exemples originaux d’après SemVer 2.0.0, initialement rédigé par Tom Preston-Werner ; texte de référence sous CC BY 3.0. SemVer 2.0.0 · CC BY 3.0

Poursuivre le contrôle

À retenir pour le dossier

Le comparateur vérifie la syntaxe et la priorité, pas les notes de publication, le contenu, la sécurité ou la compatibilité réelle. Il ne traite ni contraintes de dépendances, ni plages npm, ni versions Python ou Debian. La limite de 256 caractères est celle du formulaire, pas celle de SemVer.

Deux versions de même priorité doivent-elles être fusionnées dans un inventaire ?

Pas automatiquement. Garder la chaîne complète et la référence de l’artefact : 1.2.3+linux et 1.2.3+windows ont la même priorité, mais les métadonnées peuvent servir à distinguer des constructions. Une empreinte et un contrat de publication restent des contrôles séparés.

Documentation primaire

Documentation consultée le .

APPROFONDISSEMENT / PRATIQUE

Conserver les différences entre deux états d’un jeu

Un fichier public est remplacé au même emplacement. Le versionnement doit permettre de retrouver l’état utilisé dans un calcul et de comprendre les changements ultérieurs.

Mis à jour le .

Vérifications prioritaires

Conserver fichier, date, source, empreinte et schéma. Comparer lignes, colonnes, définitions et valeurs avant d’attribuer les différences à une évolution du phénomène mesuré.

Pièges d’interprétation

Une nouvelle date de téléchargement ne signifie pas nécessairement un nouveau contenu. Une modification de structure peut rendre une comparaison brute difficile à interpréter.

Document de travail à conserver

Le journal de versions associe état, empreinte, changement et effet sur les analyses. Les calculs citent explicitement la version utilisée.