Commit bc44ea36 authored by Christophe Benz's avatar Christophe Benz

Update doc template

parent 0dbbdcec
Pipeline #703 passed with stages
in 1 minute and 31 seconds
# Validata-Badge
## Configuration
La configuration du badge Validata est contenue dans le fichier badge_conf.toml. Ex:
```toml
[body]
# Seuil d'acceptabilité (entre 0 et 1.0)
acceptability-threshold = 0.3
# Poids associé à chaque type d'erreur (entre 0 et 1.0)
# Par défaut, le poids associé est 1.0 (100%).
# Un type d'erreur peut être ignoré en positionnant le poids à 0 (non recommandé)
[body.errors-weight]
# Erreur: la valeur ne respecte pas l'expression régulière donnée
pattern-constraint = 0.5
# Erreur: la taille de la valeur dépasse la limite autorisée
maximum-length-constraint: 0.2
```
La configuration du badge Validata est contenue dans le fichier [badge_conf.toml](badge_conf.toml).
Elle indique le seuil (`acceptability-threshold`) au delà duquel le ratio
d'erreur de contenu passe de l'orange (acceptable ?) au rouge.
d'erreur de contenu passe de l'orange (acceptable ?) au rouge.
Chaque type d'erreur intervenant dans le calcul du taux d'erreur peut être
pondéré individuellement (`errors-weight`).
......@@ -33,6 +15,7 @@ La construction d'un badge nécessite de croiser les résultats de validation
d'une ressource et les informations de configuration du badge.
Un badge est constitué des informations suivantes :
- structure : les valeurs possibles sont `OK`, `WARN` et `KO`
- `OK`: pas d'erreur de structure
- `WARN`: erreur(s) de structure récupérable(s)
......@@ -44,27 +27,7 @@ Un badge est constitué des informations suivantes :
- ratio (`R`) : pourcentage d'erreur (valeurs comprises entre 0 et 1)
Notes :
- Si la propriété `structure` vaut `KO`, les informations de `body` et `ratio`
ne sont pas données.
- `R` = taux d'erreur (Error Ratio) calculé comme le nombre de cellules en erreur sur le nombre de cellules total (valeur comprise entre 0 et 1)
pondéré par le poids sur le type d'erreur. Le poids associé à chaque type d'erreur est spécifié dans la configuration
- `Th` = seuil d'acceptabilité (Acceptability Threshold) à partir duquel le témoin passe de l'orange au rouge (valeur comprise entre 0 et 1).
La valeur du seuil est spécifié dans la configuration.
## Représentation graphique du badge
Le badge est en 2 parties :
- partie gauche : bloc gris foncé avec le libellé "Validata"
- partie droite : bloc vert, orange ou rouge contenant du texte (cf. tableau ci-dessous)
| Structure | Contenu | Texte à afficher | Couleur |
|-----------|----------|---------------------------|---------|
| KO | * | "structure invalide" | rouge |
| WARN | KO | "cellules valides : `P`%" | rouge |
| WARN | WARN | "cellules valides : `P`%" | orange |
| WARN | OK | "structure invalide" | orange |
| OK | KO | "cellules valides : `P`%" | rouge |
| OK | WARN | "cellules valides : `P`%" | orange |
| OK | OK | "valide" | vert |
`P` = pourcentage de qualité calculé comme : `(1 - R) * 100`
\ No newline at end of file
- Si la propriété `structure` vaut `KO`, les informations de `body` et `ratio` ne sont pas données.
- `R` = taux d'erreur (Error Ratio) calculé comme le nombre de cellules en erreur sur le nombre de cellules total (valeur comprise entre 0 et 1) pondéré par le poids sur le type d'erreur. Le poids associé à chaque type d'erreur est spécifié dans la configuration
- `Th` = seuil d'acceptabilité (Acceptability Threshold) à partir duquel le témoin passe de l'orange au rouge (valeur comprise entre 0 et 1). La valeur du seuil est spécifié dans la configuration.
......@@ -2,39 +2,43 @@
## Principe
Le badge Validata est une représentation graphique destinée
à illustrer l'état de validité
d'une ressource tabulaire selon les critères de Validata.
Le badge Validata est une représentation graphique destinée à illustrer l'état de validité d'une ressource tabulaire selon les critères de [Validata](https://go.validata.fr).
Sa représentation s'appuie sur le descriptif des erreurs relevées par l'outil de
[validation Validata](https://go.validata.fr) pour une ressource données.
Exemple: ![](https://img.shields.io/static/v1.svg?label=Validata&message=cellules+valides+%3A+96.1%25&color=orange)
Les erreurs sont de deux types :
- structure : (nombre, ordre et libellés des colonnes)
- contenu : valeur absente, incorrecte, trop courte ou trop longue...
Les erreurs peuvent porter sur :
Les erreurs de structure sont vérifiées tout d'abord. Si la structure est incorrecte,
la validation s'arrête là. Sinon, un taux d'erreur de contenu est calculé sur la base de
```nombre de cellules en erreur / nombre de cellules total```.
Au-delà d'un certain *seuil acceptable*, la ressource n'est plus utilisable.
- la structure : nombre, ordre et libellés des colonnes
- le contenu : valeur absente, incorrecte, trop courte ou trop longue...
## Configuration
Les erreurs de structure sont vérifiées en premier. Si la structure est incorrecte, la validation s'arrête là. Sinon, un taux d'erreur de contenu est calculé (voir ci-dessous).
Il est possible de jouer sur :
- le seuil d'acceptabilité (`acceptability-threshold`)
- le poids accordé à chaque type d'erreur (`errors-weight`)
## Règles de calcul du badge
en modifiant le fichier [badge_conf.toml](https://git.opendatafrance.net/validata/validata-badge/blob/master/badge_conf.toml).
En fonction de la présence ou non d'erreurs de structure et/ou de contenu, le badge adopte une présentation différente. Voici les règles appliquées par l'outil Validata:
### Configuration actuelle
| Structure | Contenu | Texte affiché | Couleur |
|-----------|---------|-------------------------|---------|
| KO | * | "structure invalide" | rouge |
| WARN | KO (erreurs >= {{ threshold * 100 }}%) | "cellules valides : N%" | rouge |
| WARN | WARN (erreurs < {{ threshold * 100 }}%) | "cellules valides : N%" | orange |
| WARN | OK (0% d'erreurs) | "structure invalide" | orange |
| OK | KO (erreurs >= {{ threshold * 100 }}%) | "cellules valides : N%" | rouge |
| OK | WARN (erreurs < {{ threshold * 100 }}%) | "cellules valides : N%" | orange |
| OK | OK (0% d'erreurs) | "valide" | vert |
Le seuil d'acceptabilité est fixé à **{{ threshold * 100 }}%**
Notes :
- "Structure = WARN" signifie que les erreurs de structure ont pu être réparées automatiquement, permettant la validation du contenu du fichier. Ceci s'applique notamment aux erreurs d'encodage ou de délimiteur de colonnes.
- "Contenu = *" signifie que dans la mesure où la structure du fichier est invalide, le contenu n'est pas validé.
- La valeur "N%" présente dans la colonne "Texte affiché" vaut `100 - "taux d'erreur"`.
{% if weight_dict %}
Type(s) d'erreurs avec ayant un poids personnalisé :
{% for err, w in weight_dict|dictsort %}
- {{ err }} : **{{ w * 100}}%**
Le taux d'erreur est le rapport entre le nombre de cellules en erreur et le nombre de cellules total, en tenant compte de la pondération spécifique des types erreurs suivants :
{% for err, w in weight_dict|dictsort -%}
- {{ err }} : {{ w * 100 }}%
{% endfor %}
{% else %}
Aucun poids défini. Tous les types d'erreur se valent.
Le taux d'erreur est le rapport entre le nombre de cellules en erreur et le nombre de cellules total.
{% endif %}
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment