Poste de travail technique pour préparer un catalogue

Comparatif documenté · 3 périmètres

CSV, OpenAPI et JSON-LD : trois descriptions, trois fonctions

Un tableau échange des valeurs, un contrat décrit une interface et un contexte donne du sens à des identifiants. Leur validité technique ne prouve pas l’exactitude des offres.

Contenu éditorial mis à jour le . Chaque référence indique sa propre date de consultation. Les faits sont attribués aux sources ; les scénarios et conseils sont éditoriaux. Le périmètre commercial, les prix et les droits de votre compte restent à confirmer.

Références documentaires et points à vérifier

Les lignes comparent des rôles et des conditions d’accès. Un point non documenté reste une question à poser, sans lui attribuer une note négative. Sur téléphone, chaque périmètre se lit dans une carte.

Références, limites et vérifications par périmètre
Périmètre et rôleDocumentéLimiteÀ demander
CSV et métadonnées CSVW

Décrire et contrôler un jeu tabulaire

Le W3C décrit des métadonnées permettant d’associer aux tables des colonnes, types et contraintes.

W3C : primer CSV on the Web ↗

Consulté le

La structure d’un fichier ne prouve pas la fraîcheur d’un prix ou le droit de publier une photo.Quels types, identifiants et relations sont attendus pour chaque colonne ?
OpenAPI

Décrire le contrat d’une API HTTP

OpenAPI définit une description d’opérations HTTP, de paramètres et de structures de réponses.

OpenAPI Specification 3.2.1 ↗

Consulté le

Le contrat ne garantit ni droits d’accès commerciaux ni équivalence de comportement entre fournisseurs.Quelle version de la description correspond au service testé ?
JSON-LD

Exprimer des données liées en JSON

JSON-LD utilise notamment un contexte et des identifiants pour exprimer des relations et une signification dans des données JSON.

W3C : JSON-LD 1.1 ↗

Consulté le

Un balisage valide ne rend pas une information vraie et ne garantit pas sa visibilité dans un moteur.Les entités et propriétés décrivent-elles le contenu réellement visible et ses sources ?

Choisir la description au bon niveau

Pour un import, définissez les lignes, colonnes et relations attendues. Pour une intégration, examinez les opérations et leurs réponses. Pour une page publiée, vérifiez le sens des entités décrites. Ces besoins peuvent coexister, mais ne sont pas satisfaits par le même document.

Une base de fiches gagne à conserver un modèle interne stable. Les formats d’échange et de publication s’y rattachent par des correspondances explicites, plutôt que par des transformations qui perdent les identités.

Séparer structure et vérité métier

Une date bien formée peut être obsolète ; une devise valide peut ne pas correspondre au tarif ; une URL peut pointer vers un média sans droit de réutilisation. Les validations de forme sont nécessaires mais demandent des contrôles de provenance et de cohérence.

Gardez les valeurs inconnues visibles. Ne remplissez pas un champ pour satisfaire un schéma lorsque la source ne fournit pas l’information. Adaptez le statut ou le périmètre publié.

Versionner et rendre les écarts compréhensibles

Lorsqu’un format change, notez la version et les conséquences sur les imports, pages et intégrations. Un ajout de colonne peut rester compatible ; un changement de sens ou d’identité peut demander une migration.

La preuve utile relie un exemple autorisé, la règle attendue et le résultat. Un rapport qui dit seulement « JSON valide » ne permet pas de savoir si la fiche décrit correctement une offre touristique.

Mettre à jour les sorties sans diverger de la source

Scénario de préparation : une définition de champ change alors que tableaux, API et pages publiques sont maintenus séparément. Identifiez la source de référence et les transformations. Un correctif dans un export peut disparaître lors de la prochaine génération.

Conservez la version du contrat, les consommateurs concernés et un exemple avant/après. La sortie du pilote exige un responsable pour les variantes, les valeurs inconnues et les anciennes relations ; contrôlez les trois usages plutôt que le seul format choisi en premier.

Choisir selon le besoin

Trois situations pour cadrer le bon périmètre

Le choix du format suit celui du destinataire. Une équipe qui rapproche un tableau, une application qui appelle un service et un moteur qui lit une page ont des besoins différents. Aucun de ces formats ne garantit à lui seul exactitude, fraîcheur ou droit d’utilisation.

Les situations ci-dessous sont fictives. Elles servent à comparer un périmètre de travail et les preuves nécessaires ; elles ne décrivent pas les conditions d’une offre fournisseur.

Revue de catalogue

Cas fictif : un partenaire transmet dans un espace interne autorisé un tableau de 40 produits. Cinq cellules de prix sont vides et deux indiquent zéro ; la convention et la devise doivent accompagner ces valeurs.

Avant de retenir ce périmètre : Choisir le tableau et ses métadonnées pour cette revue, en distinguant cinq prix inconnus et deux valeurs nulles. La lecture du fichier ne crée aucune réservation et ne transforme pas un prix vide en gratuité.

Intégration logicielle

Cas fictif : l’équipe doit rechercher une offre puis retrouver la réservation créée. Elle dispose d’une description OpenAPI, mais l’accès à la création n’est pas encore activé sur son compte.

Avant de retenir ce périmètre : Relier opérations, paramètres et réponses à la version du service, puis tester les droits réels. Une description d’interface ne vaut pas activation commerciale ni preuve que le parcours marchand a abouti.

Description d’une page publique

Cas fictif : la page décrit un musée ouvert de 10 h à 18 h selon sa source, mais son balisage JSON-LD conserve une fermeture à 20 h provenant d’une ancienne version.

Avant de retenir ce périmètre : Rapprocher l’entité, les propriétés et le contenu visible, puis corriger la divergence. Un contexte JSON-LD valide ne vérifie pas l’horaire du lieu et ne garantit pas un affichage particulier dans un moteur.

Arbitrer les contraintes et le coût de fonctionnement

Une même donnée peut être exposée dans plusieurs formats si leur génération utilise des définitions cohérentes. Le coût réside aussi dans le maintien de cette cohérence. Gardez une source interne identifiable, puis documentez les transformations ; ne corrigez pas une version publique en laissant les autres décrire un ancien état. Prenez une offre fictive traduite en deux langues. Deux lignes de catalogue peuvent représenter deux versions linguistiques d’un même produit ; elles ne créent pas deux capacités à vendre. Vérifiez identifiant stable, langue et règle de rapprochement dans chaque représentation. Le contrat d’API doit préciser comment envoyer ces informations, tandis que le balisage de la page décrit l’offre effectivement visible. La présence du même nom de champ dans trois formats ne démontre pas une sémantique commune.

Points à clarifier avant la décision

  • Le même champ change de devise, d’unité ou de sens entre représentations sans convention de transformation.
  • Une cellule vide devient zéro ou le balisage public conserve une information différente de celle affichée au visiteur.

Quatre cas pour rendre la comparaison vérifiable

Les nombres et situations ci-dessous sont fictifs, à adapter au périmètre proposé. Utilisez un environnement et des données de test autorisés. Conservez les réponses, les opérations manuelles et les points qui restent inconnus.

Situations, contrôle et preuve attendue
SituationContrôlePreuve utile
Même offre dans trois représentationsCas fictif : offre A12 à 120,50 EUR, publiée en français. Examiner une ligne CSV, le contrat d’API et la page balisée.Encodage, séparateur et décimales relus ; OpenAPI décrit les échanges ; JSON-LD correspond au contenu public visible.
Relation orphelineDétecter une référence vers une entité absente.Identifiants et rapport de rapprochement.
Champ facultatif absentOmettre le prix puis utiliser explicitement zéro dans un second jeu fictif.Absence et gratuité restent distinctes dans la lecture, la validation et l’affichage.
Balisage décaléAligner les données structurées sur le contenu visible.Page, entités et sources correspondantes.

Consulter le registre de comparaison et préparer le contrôle d’accès API.

Questions fréquentes

Faut-il remplacer CSV par JSON-LD ?

Le choix dépend de l’usage. Une description liée ne remplace pas automatiquement un format tabulaire pratique pour un import.

OpenAPI certifie-t-il les droits du compte ?

Non. La description technique doit être rapprochée des accès et conditions applicables.

JSON-LD garantit-il la visibilité LLM ?

Non. Il rend une description structurée possible ; exactitude, sources, accès au contenu et décisions des moteurs restent distincts.

Faut-il proposer les trois formats ?

Retenez chaque représentation pour son destinataire et sa tâche : revue tabulaire interne, contrat d’API ou données liées d’une page. Faites partager identifiants, unités et définitions, puis vérifiez les transformations. Multiplier les formats sans propriétaire de mise à jour peut produire trois versions contradictoires plutôt qu’une information plus utile.

Documentation et application

Les précisions utiles des sources

OpenAPI 3.1.1 : un format déclaré n’est pas toujours une validation

Cette lecture porte sur la version 3.1.1, sans la présenter comme la version la plus récente. Le contrat du fournisseur doit préciser sa propre version et le dialecte pris en charge.

OpenAPI 3.1.1 : un format déclaré n’est pas toujours une validation
Point documentéCe que la source préciseConséquence pour votre contrôle
DialecteLe Schema Object repose sur JSON Schema Draft 2020-12, avec le dialecte OpenAPI.Configurer le validateur pour le dialecte annoncé, plutôt que supposer l’équivalence avec un ancien contrat.
formatLe dialecte par défaut utilise format comme annotation ; sa présence ne suffit pas à imposer une validation du format.Vérifier explicitement la validation des dates, adresses et identifiants sensibles.
readOnly et writeOnlyCes annotations portent sur le sens lecture/écriture des champs.Distinguer les propriétés acceptées dans la requête de celles retournées en réponse.

Un contrat de données ne démontre pas l’activation commerciale d’une opération ni la qualité du service d’assistance.

OpenAPI Specification 3.1.1 — Schema Object · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.

Unicode : même nom visible, suites de caractères différentes

Un accent peut être composé dans un caractère ou ajouté après la lettre. Deux libellés visuellement identiques peuvent donc échouer à une comparaison brute.

Unicode : même nom visible, suites de caractères différentes
Point documentéCe que la source préciseConséquence pour votre contrôle
NFC et NFDNFD décompose les équivalences canoniques ; NFC les décompose puis les recompose lorsque c’est possible.Exemple pédagogique : Café avec U+00E9 et Cafe suivi de U+0301 deviennent identiques en NFC.
NFKC et NFKDCes formes appliquent aussi les équivalences de compatibilité : le chiffre romain Ⅳ devient IV.Une clé de recherche peut perdre une distinction conservée dans le libellé. Choisissez la transformation par usage.
Identité et affichageL’équivalence de texte ne prouve pas que deux lignes décrivent le même établissement.Conservez le texte source et rapprochez identifiant fournisseur, adresse et périmètre avant de fusionner des fiches.

La normalisation ne traduit pas, ne corrige pas un mauvais décodage et ne supprime pas automatiquement les accents. Elle ne remplace pas les règles d’identité du catalogue.

Unicode — UAX 15, formes de normalisation, révision 58 · mise à jour par la source le 12/08/2026 · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.

Comparer deux libellés et voir leurs points de code.

Compléter la décision avec les guides et les catégories

Tous les comparatifs · Méthode et limites des sources

Approfondir la méthode

Modèles et champs associés

Les modèles reprennent les documents cités dans cette méthode et ses guides associés. Consultez les informations à rapprocher et les contrôles proposés.