From 437ef8e4f2c7bd722d62203260d6333d336f3042 Mon Sep 17 00:00:00 2001 From: MBorne Date: Tue, 6 Aug 2024 14:36:04 +0200 Subject: [PATCH] docs(validator-error): document ValidatorError with markdown and JSON schema (refs #272) --- README.md | 4 +- .../src/main/resources/schema/README.md | 55 +++++++++++++--- .../main/resources/schema/ValidatorError.json | 62 +++++++++++++++++++ 3 files changed, 110 insertions(+), 11 deletions(-) create mode 100644 validator-core/src/main/resources/schema/ValidatorError.json diff --git a/README.md b/README.md index f3b21f7a..202ce81d 100644 --- a/README.md +++ b/README.md @@ -57,12 +57,12 @@ Les dépendances java telle [GeoTools](doc/dependencies/geotools.md) sont décri Les principaux documents sont les suivants : -* [Modélisation des données](validator-core/src/main/resources/schema/README.md) +* [Modélisation des données et des erreurs](validator-core/src/main/resources/schema/README.md) +* [Liste des codes d'erreurs (JSON)](validator-core/src/main/resources/error-code.json) * [Exemples de modèles de document](validator-core/src/test/resources/config-json/README.md) * [Utilisation du validateur en ligne de commande](doc/cli.md) pour une utilisation directe. * [Principe de fonctionnement du validateur](doc/principe.md) * [Principe de fonctionnement des plugins](doc/plugins.md) -* [Liste des codes d'erreurs (JSON)](validator-core/src/main/resources/error-code.json) * [Projection supportées (JSON)](validator-core/src/main/resources/projection.json) Les documents ci-après traitent des problématiques particulières : diff --git a/validator-core/src/main/resources/schema/README.md b/validator-core/src/main/resources/schema/README.md index f3cb938f..a7a99c8c 100644 --- a/validator-core/src/main/resources/schema/README.md +++ b/validator-core/src/main/resources/schema/README.md @@ -1,4 +1,4 @@ -# Modélisation des données +# Modélisation des données et des erreurs ## Description @@ -6,14 +6,15 @@ Cette documentation décrit schématiquement les modèles JSON de validation du ## Vue d'ensemble des concepts -| Concept | Description | Implémentation | -| --------------------- | ------------------------------------------------------------------------------- | --------------- | -| [Document](#document) | Modélisation du contenu d'un dossier ou d'une archive. | `DocumentModel` | -| [File](#file) | Modélisation d'un fichier du document (chemin, type, présence obligatoire,...). | `FileModel` | -| [Table](#table) | Modélisation d'une table matérialisée dans un fichier. | `FeatureType` | -| [Column](#column) | Modélisation d'une colonne d'une table. | `AttributeType` | +| Concept | Description | Implémentation | +| ---------------------------------- | ------------------------------------------------------------------------------- | ---------------- | +| [Document](#document) | Modélisation du contenu d'un dossier ou d'une archive. | `DocumentModel` | +| [File](#file) | Modélisation d'un fichier du document (chemin, type, présence obligatoire,...). | `FileModel` | +| [Table](#table) | Modélisation d'une table matérialisée dans un fichier. | `FeatureType` | +| [Column](#column) | Modélisation d'une colonne d'une table. | `AttributeType` | +| [ValidatorError](#validationerror) | Modélisation des erreurs (résultat de la validation) | `ValidatorError` | -## Modélisation des concepts +## Modélisation des données ### Document @@ -62,7 +63,7 @@ Les types de fichiers supportés sont les suivants : | `metadata` | Fiche de métadonnées XML au format ISO 19115 (`.xml`) | 4.0 | | `pdf` | Fichier PDF (`.pdf`) | 4.0 | | `table` | Table de données géographique ou non (`.csv`, `.dbf`, `.shp`, `.geojson`, `.gml`) | 4.0 | -| `multi_table` | Un ensemble de tables stockées dans un seul fichier (`.gml`, `.gpkg`) | 4.2 | +| `multi_table` | Un ensemble de tables stockées dans un seul fichier (`.gml`, `.gpkg`) | 4.2 | Remarque : L'ajout du concept `multi_table` est lié à la validation des données [PCRS vecteur](https://github.com/cnigfr/PCRS) où un même fichier GML contient plusieurs collections. Il est étendu au format GeoPackage pour le [Géostandards Risques](https://github.com/cnigfr/Geostandards-Risques). @@ -148,3 +149,39 @@ Remarques : | `maximum` | `any` | Contrainte sur la valeur maximale autorisée (incluse) | +## Modélisation des erreurs + +### ValidatorError + +Le concept de [ValidatorError](ValidatorError.json) est utilisé pour modéliser les erreurs rapportés dans les rapports de validation. Les principales propriétés sont les suivantes : + +| Nom | description | Exemple | +| --------------- | -------------------------------------------------------------------- | ----------------------------------------------- | +| `code` | Code de l'erreur | `ATTRIBUTE_GEOMETRY_INVALID` | +| `level` | Niveau de gravité de l'erreur (DEBUG, INFO, WARNING, ERROR ou FATAL) | `ERROR` | +| `message` | Message d'erreur détaillé | `"La géométrie n'est pas valide"` | +| `documentModel` | Nom du modèle de document | `cnig_PLU_2017` | +| `fileModel` | Nom du modèle de fichier | `ZONE_URBA` | +| `attribute` | Nom de la colonne concernée | `WKT` | +| `file` | Chemin du fichier concerné | `Donnees_geographique/ZONE_URBA.shp` | +| `id` | Numéro de la ligne dans le fichier / la table | `228` | +| `featureBbox` | Boite englobante de l'objet (lonMin,latMin,lonMax,latMax) | `-2.156289,47.3279265,-2.1558376,47.3281971` | +| `errorGeometry` | Localisation de l'erreur géométrique (format WKT, projection CRS:84) | `POINT (-2.1559630631294775 47.32809837488598)` | +| `featureId` | Identifiant de l'objet (si disponible) | `id-6b2bd0b0-c593-4e40-8e2e-2037e35b4685` | + +Les propriétés suivantes sont spécifiques aux erreurs de validation XML sur la base de schémas XSD (`code=XSD_SCHEMA_ERROR`) : + +| Nom | description | Exemple | +| ----------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | +| `xsdErrorCode` | Code de l'erreur | [cvc-datatype-valid.1.2.3](https://knowledge.xmldation.com/fr/support/validator/cvc-datatype-valid-1-2-1/fr) | +| `xsdErrorMessage` | Message d'erreur standard du validateur XSD | `'bad-nature' n'est pas une valeur valide du type d'union 'NatureAffleurantPCRSTypeType'.` | +| `xsdErrorPath` | XPath correspondant à l'erreur de validation XML | `//PlanCorpsRueSimplifie/featureMember/AffleurantPCRS[@id='AffleurantEnveloppePCRS.0']/nature` | + +Les niveaux de gravité des erreurs sont utilisés comme suit : + +* `FATAL` correspond à un échec de la validation (problème technique, plantage du validateur) +* `ERROR` matérialise problème bloquant pour l'intégration des données dans une base de données (ex : problème de type) +* `WARNING` matérialise un problème non bloquant pour l'intégration des données dans une base de données est rencontré +* `INFO` permet d'ajouter au rapport un message d'information visible par les utilisateurs du validateur (ex : projection lue dans une fiche de métadonnées) +* `DEBUG` permet d'ajouter un rapport un message d'information non visible par les utilisateurs (ex : version de GDAL) + diff --git a/validator-core/src/main/resources/schema/ValidatorError.json b/validator-core/src/main/resources/schema/ValidatorError.json new file mode 100644 index 00000000..5a49cf9b --- /dev/null +++ b/validator-core/src/main/resources/schema/ValidatorError.json @@ -0,0 +1,62 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "Code de l'erreur" + }, + "level": { + "type": "string", + "description": "Niveau de gravité de l'erreur" + }, + "message": { + "type": "string", + "description": "Message d'erreur détaillé" + }, + "documentModel": { + "type": "string", + "description": "Nom du modèle de document" + }, + "fileModel": { + "type": "string", + "description": "Nom du modèle de fichier" + }, + "attribute": { + "type": "string", + "description": "Nom de la colonne concernée" + }, + "file": { + "type": "string", + "description": "Chemin du fichier concerné" + }, + "id": { + "type": "string", + "description": "Numéro de la ligne dans le fichier / la table" + }, + "featureBbox": { + "type": "array", + "items": { + "type": "number" + }, + "minItems": 4, + "maxItems": 4, + "description": "Boite englobante de l'objet (lonMin,latMin,lonMax,latMax)" + }, + "errorGeometry": { + "type": "string", + "description": "Localisation de l'erreur géométrique (format WKT, projection CRS:84)" + }, + "featureId": { + "type": "string", + "description": "Identifiant de l'objet (si disponible)" + } + }, + "required": [ + "code", + "level", + "message", + "documentModel" + ] + } + \ No newline at end of file