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.
Documents consultés le . Les faits ci-dessous sont attribués à leurs 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.
| Périmètre et rôle | Documenté | 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 ↗ | 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 ↗ | 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 ↗ | 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.
Quatre cas pour rendre la comparaison vérifiable
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.
| Situation | Contrôle | Preuve utile |
|---|---|---|
| Valeur inconnue | Conserver un statut sans inventer de contenu. | Valeur source, règle de traitement et page obtenue. |
| Relation orpheline | Détecter une référence vers une entité absente. | Identifiants et rapport de rapprochement. |
| Changement de contrat | Comparer les structures et les comportements utiles. | Versions, différence et résultat de recette. |
| Balisage décalé | Aligner les données structurées sur le contenu visible. | Page, entités et sources correspondantes. |
Télécharger 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.