IGNF · mborne · Feb 3, 2022 · Jan 14, 2022 · Jan 14, 2022 · Jan 14, 2022
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,8 +8,30 @@ It relies on the following configuration file [eclipse/formatter-config.xml](ecl
 
 To configure eclipse to use this code formatter, see "Preferences window, go to Java -> Code Style -> Formatter -> Import".
 
+## Continuous Integration (CI)
 
+Note that CI is configured throw [GitHub Actions](https://github.com/IGNF/validator/actions/workflows/main.yml).
 
+It relies on [.github/workflows/main.yml](.github/workflows/main.yml) which :
+
+* Install OpenJDK 11 and maven
+* Install ogr2ogr
+* Run tests through [.ci/build-openjdk11.sh](.ci/build-openjdk11.sh)
+
+You may run `bash .ci/build-openjdk11.sh` to ensure that source code is formatted, build code and run tests.
+
+## Create releases
+
+* Ensure that you are on the right branch and that all code is committed and push (`git status`)
+* Run `mvn release:prepare` and follow instructions to automatically create tags and update version in pom.xml files
+* Build JAR and packages for the new tag
+
+```bash
+git checkout v4.2.5
+make package
+```
+
+* Create release from github tag with the following binary files : `validator-cli/target/validator-cli.jar`, `ign-validator_{VERSION}_all.deb` and `ign-validator-{VERSION}-1.noarch.rpm`
 
 
 
diff --git a/README.md b/README.md
@@ -5,8 +5,9 @@
 
 ## Description
 
-> This programs allows to validate datasets (a folder containing shapefiles, PDF, etc.) according to a file mapping and a FeatureCatalog. It outputs a report describing validation errors and normalized data ready for database integration.
-> It has been developed for the [*géoportail de l'urbanisme*](https://www.geoportail-urbanisme.gouv.fr) to validate urbanism data according to [CNIG standards](https://www.geoportail-urbanisme.gouv.fr/standard/) and allow merging in a national database.
+> This program validates a dataset (a folder containing geodata files and other documents) according to a schema describing the folder structure and the feature catalog. It outputs a report containing validation errors and warnings, and normalized data ready for database integration.
+
+> It has been originally developed for the [Géoportail de l'Urbanisme]((https://www.geoportail-urbanisme.gouv.fr)) to check urban planning documents against CNIG standards in order to produce a nationwide database.
 
 Ce programme permet de valider et de normaliser les données présentes dans une arborescence de fichiers. Ces données peuvent être :
 
@@ -24,102 +25,50 @@ Le paramétrage s'effectue à l'aide de [fichiers JSON décrivant des arborescen
 
 ## Principe de fonctionnement
 
-Le schéma suivant illustre le [Principe de fonctionnement du validateur de document](doc/principe.md) :
+Le schéma suivant illustre le [Principe de fonctionnement du validateur](doc/principe.md) :
 
 ![Working principle](doc/img/principe.jpg)
 
 ## Principales fonctionnalités
 
-| Groupe                                | Fonctionnalité                                                                                                                                                                                                                       |
-|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Modèle de données                     | Modélisation d'arborescence de fichiers : Fichiers attendus (optionnel ou oubligatoire) avec mise en correspondance chemin et modèle de table)                                                                                       |
-| Modèle de données                     | Modélisation de la structure d'une table (spatiale ou non) par définit de la liste de la liste des attributs                                                                                                                         |
-| Modèle de données                     | Modélisation d'un attribut de table par définition du type, de valeurs autorisées, d'une expression régulière, etc.)                                                                                                                 |
-| Validation d'un dossier               | Contrôle de la présence de dossier et de fichiers dans une arborescence suivant des expressions régulières                                                                                                                           |
-| Validation d'une table                | Lecture des formats CSV, Shapefile, MapInfo, GML (possibilité d'étendre aux formats supportés par ogr2ogr de GDAL)                                                                                                                   |
-| Validation d'une table                | Validation de l'encodage des chaînes de caractères (problème encodage UTF-8, LATIN1, etc.), détection des caractères non affichable et simplification pour un meilleur support par les différentes charsets et polices de caractères |
-| Validation d'un attribut géométrique  | Validation du type géométrique avec conversion automatique entre géométrie simple et multiple quand la données le permet                                                                                                             |
-| Validation d'une fiche de métadonnées | Validation des fiches de métadonnées suivants les principales contraintes INSPIRE                                                                                                                                                    |
-| Rapport d'erreur                      | Production d'un rapport d'erreur au format JSON avec des erreurs porteuses d'un code d'erreur, d'un message et d'un niveau de gravité (bloquant pour l'intégration des données en base?)                                             |
-| Plugin CNIG                           | Extension permettant de traiter des aspects spécifiques aux standards CNIG PLU, POS, CC, PSMV, SCOT et SUP (consigne de saisie des métadonnées, IDURBA, TYPEREF, etc.)                                                               |
-| Plugin DGPR                           | Extension permettant de traiter des aspects spécifiques à la validation du standard COVADIS "Directive innondation v2.0" (en particulier, la topologie des différentes couches)                                                      |
-| Normalisation des données             | Production de données données conformes au modèle de validation pour intégration en base de données (format CSV)                                                                                                                     |
-| Normalisation des données             | Conversion des fiches de métadonnées XML dans un modèle pivot JSON                                                                                                                                                                   |
-
-## Documentation technique
+* Validation d'une arborescence de fichiers en fonction d'un modèle de document.
+* Validation des tables en fonction d'un modèle de table.
+* Validation des fiches de métadonnées.
+* Production d'un rapport d'erreur au format JSON.
+* Production de données normalisées (pour agrégation et diffusion).
+* Validation métier à l'aide de [plugins](doc/plugins.md) (CNIG pour GpU, DGPR pour TRI,...) pour les contrôles qui sont pas formalisés dans le modèle de validation.
 
-* [Exemples de modèles de document (french)](validator-core/src/test/resources/config-json/README.md)
-* [Modélisation des données (french)](validator-core/src/main/resources/schema/README.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)
-* [Metadata modelization (english)](doc/metadata.md)
-* [Characters validation (english)](doc/characters/index.md)
-* [plugin-cnig - validation des champs IDURBA](doc/plugin-cnig/idurba.md)
-* [plugin-cnig - Validation des mots clés en fonction des CSMD CNIG](doc/plugin-cnig/keywords.md)
+## Utilisation
 
-## Cas d'utilisation
+Le validateur se présente sous la forme d'un exécutable java (`validator-cli.jar`) utilisable en ligne de commande. Il n'offre pas d'interface graphique car il a vocation à être utilisé pour la mise en œuvre de services web tel le [Géoportail de l'Urbanisme](https://www.geoportail-urbanisme.gouv.fr) offrant ces interfaces.
 
-Ce programme a été développé dans le cadre du [géoportail de l'urbanisme](https://www.geoportail-urbanisme.gouv.fr) pour la validation des [standards CNIG](https://www.geoportail-urbanisme.gouv.fr/standard/).
+Les techniciens peuvent se référer à la documentation [utilisation du validateur en ligne de commande](doc/cli.md).
 
 ## Dépendances
 
+Les exécutables systèmes ci-après sont requis pour l'exécution du programme :
+
 * java >= 11
 * [ogr2ogr >= v2.3.0](doc/dependencies/ogr2ogr.md) : Utilisé pour lire et convertir les données en entrée dans un format pivot avant validation (CSV)
-* [geotools](doc/dependencies/geotools.md)
-
-## Compilation
-
-Vous pouvez télécharger `validator-cli.jar` correspondant à la [dernière release](https://github.com/IGNF/validator/releases) où construire ce `.jar` avec la procédure suivante :
-
-```bash
-mvn package
-# Voir validator-cli/target/validator-cli.jar
-```
-
-## Principales commandes
-
-### Affichage de la liste des commandes disponibles
-
-```bash
-java -jar validator-cli/target/validator-cli.jar --help
-```
 
-### document_validator - validation d'un document (dossier)
+Les dépendances java telle [GeoTools](doc/dependencies/geotools.md) sont décrites dans les fichiers [pom.xml](pom.xml) et intégrées dans l'exécutable JAVA.
 
-Exécuter la commande suivante pour récupérer les paramètres disponibles :
-
-```bash
-java -jar validator-cli.jar document_validator --help
-```
-
-Voir [https://github.com/IGNF/validator-example](https://github.com/IGNF/validator-example) pour des exemples d'utilisation.
-
-Remarques :
-
-* Le chemin d'accès à `ogr2ogr` peut être spécifié :
-  * A l'aide d'une propriété : `java -Dogr2ogr_path=/path/to/ogr2ogr -jar validator-cli.jar ...`
-  * A l'aide d'une variable d'environnement : `OGR2OGR_PATH=/path/to/ogr2ogr java -jar validator-cli.jar`
-* `java  -jar validator-cli.jar --plugins=gpu ...` est utilisé dans le cadre du Géoportail de l'Urbanisme
-
-
-### metadata_to_json - conversion de métadonnées XML dans un modèle pivot simplifié JSON
-
-**ATTENTION : Le modèle pivot JSON n'est pas standardisé et est suspectible d'évoluer**
-
-```bash
-java -jar validator-cli/target/validator-cli.jar metadata_to_json \
-    -i validator-core/src/test/resources/metadata/01.xml \
-    -o validator-core/src/test/resources/metadata/01-expected.json
-```
-
-Exemple : [01.xml](validator-core/src/test/resources/metadata/01.xml) -> [01.json](validator-core/src/test/resources/metadata/01-expected.json)
+## Documentation technique
 
+Les principaux documents sont les suivants :
 
-## Extensibilité
+* [Modélisation des données](validator-core/src/main/resources/schema/README.md)
+* [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)
 
-Le validateur permet l'ajout qui plugin qui vont exécuter des tâches à différentes étapes de la validation :
+Les documents ci-après traitent des problématiques particulières :
 
-* Avant la mise en correspondance des fichiers et du modèle (ex : modification d'extension)
-* Avant la validation (ex : détection de l'encodage des fichiers à partir des métadonnées)
-* Après la validation (ex : receuil de métadonnées sur les données validées, contrôles supplémentaires, etc.)
+* [Metadata (english)](doc/metadata.md)
+* [Characters validation (english)](doc/characters.md)
+* [plugin-cnig - validation des champs IDURBA](doc/plugin-cnig/idurba.md)
+* [plugin-cnig - Validation des mots clés en fonction des CSMD CNIG](doc/plugin-cnig/keywords.md)
 
diff --git a/doc/cli.md b/doc/cli.md
@@ -0,0 +1,39 @@
+
+# Utilisation du validateur en ligne de commande
+
+## Pré-requis
+
+* Exécutable java de OpenJDK 11 (`java --version` doit fonctionner et mentionner une version java 11 ou supérieure)
+* Exécutable [ogr2ogr de GDAL](dependencies/ogr2ogr.md) (`ogr2ogr --version` doit fonctionner et mentionner une version supportée)
+
+## Installation du validateur
+
+Pour chaque version, les livrables sont attachés à une [release sur github.com](https://github.com/IGNF/validator/releases).
+
+Vous pouvez télécharger le fichier `validator-cli.jar` pour la dernière release et tester à l'aide de la commande `java validator-cli.jar version` qui affichera la version du validateur.
+
+## Paramétrage
+
+Les paramètres sont gérés sous forme de variables d'environnement :
+
+| Nom            | Description                              | Valeur par défaut |
+| -------------- | ---------------------------------------- | ----------------- |
+| `OGR2OGR_PATH` | Chemin vers l'exécutable ogr2ogr de GDAL | "ogr2ogr"         |
+| `HTTP_PROXY`   | ex : http://proxy:3128                   |                   |
+| `HTTPS_PROXY`  | ex : http://proxy:3128                   |                   |
+| `NO_PROXY`     | localhost,demo.localhost                 |                   |
+
+
+## Principales commandes
+
+| Commande                                        | Description                                                                                     |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `--help`                                        | Affiche la liste des commandes disponibles                                                      |
+| `version`                                       | Affiche la version de l'exécutable validator-cli.jar (ex : `4.2.5`, `4.2.6-SNAPSHOT`,...)       |
+| [document_validator](cli/document_validator.md) | Valide un document en fonction d'un modèle de document                                          |
+| `projection_list`                               | Exporte la liste des projections supportées au format JSON.                                     |
+| `error_config`                                  | Exporte la liste des modèles d'erreur au format JSON.                                           |
+| `read_url`                                      | Lit le contenu d'une URL (pour debug des problèmes de proxy et de certificat)               |
+| [metadata_to_json](cli/metadata_to_json.md)     | Convertit d'un fiche de métadonnées XML (ISO19115) dans un modèle simplifié au format JSON.    |
+| `cnig_extract_idgest`                           | Extrait de la valeur de IDGEST à partir d'un fichier SERVITUDE (moissonnage des SUP sur GpU) |
+
diff --git a/doc/cli/document_validator.md b/doc/cli/document_validator.md
@@ -0,0 +1,46 @@
+
+## document_validator - validation d'un document
+
+## Affichage de l'aide de la commande
+
+Exécuter la commande suivante pour récupérer la liste des paramètres disponibles :
+
+```bash
+java -jar validator-cli.jar document_validator --help
+```
+
+## Exemple d'utilisation avec les données PCRS
+
+Pour valider le fichier "GeoVendee_LeTallud-StGemme.gml" dans le dossier "document-test" en fonction du modèle [CNIG_PCRS_v2.0](https://ignf.github.io/validator/validator-core/src/test/resources/config-json/CNIG_PCRS_v2.0/document.json), on appellera par exemple la commande suivante :
+
+```bash
+java -jar validator-cli.jar document_validator \
+    --report-format jsonl \
+    --model https://ignf.github.io/validator/validator-core/src/test/resources/config-json/CNIG_PCRS_v2.0/document.json \
+    --input document-test \
+    --output validation \
+    --srs EPSG:3947 \
+    --normalize
+```
+
+Les fichiers produits seront les suivants :
+
+| Fichier                                         | Description                                                                             |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `./validation/`                                 | Le répertoire de résultat de la validation                                              |
+| `./validation/validation.jsonl`                 | Le rapport de validation                                                                |
+| `./validation/document-info.json`               | Les informations sur le documents validés (comptages, emprises,...)                     |
+| `./validation/document_database.db`             | La base de données temporaire de validation (pour contrôle d'unicité, de référence,...) |
+| `./validation/document-test/DATA/{NomType}.csv` | Les données normalisées pour une éventuelle livraison à un entrepot de diffusion        |
+| `./validator-debug.log`                         | Les logs du validateur java                                                             |
+
+
+## Remarques
+
+La conversion des fichiers au format CSV est réalisées sous forme de fichier "companions" avec des extensions dédiées (`.vrows` et `.vtabs`) dans le dossier à valider :
+
+* Pour un fichier `./document-test/TRONCON_ROUTE.shp`, on notera la présence d'un fichier CSV `./document-test/TRONCON_ROUTE.vrows` contenant le résultat de la conversion du Shapefile en CSV.
+* Pour un fichier GML `./document-test/GeoVendee_LeTallud-StGemme.gml` contenant plusieurs collections, on notera la présence d'un dossier `./document-test/GeoVendee_LeTallud-StGemme.vtabs` contenant le résultat de la conversion du GML en CSV.
+
+Ces conversions sont réalisées à l'aide de [ogr2ogr de GDAL](../dependencies/ogr2ogr.md). L'utilisation d'extension dédiées facilite principalement une nouvelle exécution du validateur sur un dossier.
+
diff --git a/doc/cli/metadata_to_json.md b/doc/cli/metadata_to_json.md
@@ -0,0 +1,21 @@
+
+# metadata_to_json
+
+## Description
+
+Conversion de métadonnées XML dans un modèle pivot simplifié au format JSON.
+
+## Exemple d'utilisation
+
+Pour convertir [01.xml](../../validator-core/src/test/resources/metadata/01.xml) en [01-expected.json](../../validator-core/src/test/resources/metadata/01-expected.json) :
+
+```bash
+java -jar validator-cli.jar metadata_to_json \
+    -i validator-core/src/test/resources/metadata/01.xml \
+    -o validator-core/src/test/resources/metadata/01-expected.json
+```
+
+## Remarques
+
+* Le modèle pivot est une simplification du modèle ISO 19915 se concentrant sur les éléments utilisés dans les profiles INSPIRE et CNIG.
+* **ATTENTION : Ce modèle pivot JSON n'est pas standardisé et est susceptible d'évoluer**
diff --git a/doc/dependencies/geotools.md b/doc/dependencies/geotools.md
@@ -1,8 +1,8 @@
-# geotools
+# GeoTools
 
-## Relation to java version
+## Description
 
-See [Geotools - Java Install](http://docs.geotools.org/latest/userguide/build/install/jdk.html#) to get information about java version support.
+[GeoTools](https://geotools.org/) is mainly used to manipulate projection.
 
 ## Projection
 
@@ -11,3 +11,13 @@ Coordinate order behavior differs between usage of `gt-epsg-hsql` or `gt-epsg-wk
 There is no way to manage standard lat,lon for EPSG:4326 with `gt-epsg-wkt`.
 
 So, `gt-epsg-hsql` is used as `java -Dorg.geotools.referencing.forceXY=true` may allow non standard lon,lat order.
+
+## Relation to java version
+
+As the validator requires Java 11, GeoTools 21.x and above is supported.
+
+See [Geotools - Java Install](http://docs.geotools.org/latest/userguide/build/install/jdk.html#) for more details.
+
+
+
+