Skip to content

Commit

Permalink
docs(validator-error): document ValidatorError with markdown and JSON…
Browse files Browse the repository at this point in the history
… schema (refs #272)
  • Loading branch information
mborne committed Aug 6, 2024
1 parent e066ec6 commit 437ef8e
Show file tree
Hide file tree
Showing 3 changed files with 110 additions and 11 deletions.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 :
Expand Down
55 changes: 46 additions & 9 deletions validator-core/src/main/resources/schema/README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,20 @@
# Modélisation des données
# Modélisation des données et des erreurs

## Description

Cette documentation décrit schématiquement les modèles JSON de validation du validateur `IGNF/validator` pour ses versions `4.0` et supérieures.

## 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

Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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)

62 changes: 62 additions & 0 deletions validator-core/src/main/resources/schema/ValidatorError.json
Original file line number Diff line number Diff line change
@@ -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"
]
}

0 comments on commit 437ef8e

Please sign in to comment.