Valider des flux

Ce guide couvre une boucle de validation réaliste : choisir le bon format de sortie, filtrer le bruit, produire un rapport pour une partie prenante, itérer jusqu’à obtenir un flux propre.

1. Choisir un format de sortie

gapline validate produit cinq formats. Adaptez le format au consommateur.

Format	Idéal pour
`text`	Usage interactif. Coloré par défaut ; les couleurs sont désactivées automatiquement en pipe.
`json`	Pipelines CI. Analysable avec `jq`, diffable entre exécutions.
`csv`	Triage en tableur. Une ligne par anomalie.
`xml`	Systèmes legacy qui ingèrent déjà du GTFS validator XML.
`html`	Partager un rapport avec une partie prenante non-tech. Auto-contenu, s’ouvre par double-clic.

gapline validate -f gtfs.zip --format json -o report.json
gapline validate -f gtfs.zip --format html -o report.html
gapline validate -f gtfs.zip --format csv  -o report.csv

Le schéma de chaque format est documenté sur formats de sortie.

2. Filtrer par sévérité

Par défaut, toutes les anomalies sont incluses. Le code de retour est non nul uniquement si une anomalie atteint le niveau ERROR.

Si la sortie brute est trop bruyante, utilisez --min-severity pour masquer tout ce qui est en dessous du niveau choisi. Cela reclassifie aussi — un WARNING avec --min-severity warning devient bloquant.

# Échec uniquement sur les ERROR (comportement par défaut).
gapline validate -f gtfs.zip

# Échec aussi sur les WARNING.
gapline validate -f gtfs.zip --min-severity warning

# Échec sur tout, y compris les suggestions INFO.
gapline validate -f gtfs.zip --min-severity info

Voir concepts / sévérités pour la politique derrière les trois niveaux.

3. Désactiver des règles bruyantes

Parfois une règle est trop stricte pour votre flux. Exemple classique : block_id_trip_overlap se déclenche quand vous chaînez intentionnellement deux trajets via un block_id partagé. Désactivez-la pour cette exécution :

gapline validate -f gtfs.zip --disable-rule block_id_trip_overlap

Plusieurs IDs peuvent suivre un seul --disable-rule :

gapline validate -f gtfs.zip --disable-rule block_id_trip_overlap duplicate_coordinates

Pour trouver l’ID d’une règle à désactiver, passez par gapline rules list et un grep :

gapline rules list | grep -i speed

Pour une désactivation permanente, épinglez la liste dans gapline.toml :

[validation]
disabled_rules = ["block_id_trip_overlap", "duplicate_coordinates"]

--disable-rule en ligne de commande ajoute à la liste de config — il ne la remplace pas. L’autocomplétion shell suggère dynamiquement les IDs enregistrés — activez la complétion si ce n’est pas déjà fait.

4. Produire un rapport

Pour vous-même

gapline validate -f gtfs.zip

Texte coloré. Scannez, corrigez, relancez.

Pour un pipeline CI

gapline validate -f gtfs.zip --format json -o report.json

Analysez le JSON avec jq pour poster un commentaire de PR ou produire un diff par rapport à l’exécution précédente :

jq '.summary' report.json
jq '.errors | group_by(.rule_id) | map({rule: .[0].rule_id, count: length})' report.json

Pour une partie prenante non-tech

gapline validate -f gtfs.zip --format html -o report.html

Le fichier HTML est auto-contenu — CSS et JS sont inlinés. Envoyez-le par mail ou hébergez-le en statique. Aucun serveur requis.

5. Boucler

Le but n’est pas d’exécuter validate une fois ; c’est d’en faire une cadence qui maintient votre flux en bonne santé.

#!/usr/bin/env bash
if git diff --cached --name-only | grep -q '^data/gtfs/'; then
  gapline validate -f ./data/gtfs/ --min-severity error || exit 1
fi

- run: gapline validate -f data/gtfs.zip --format json -o report.json
- uses: actions/upload-artifact@v4
  with: { name: gtfs-report, path: report.json }

curl -L -o feed.zip https://agency.example.com/gtfs.zip
gapline validate -f feed.zip --format json -o "$(date +%F).json"

Voir aussi

gapline validate — toutes les options, tous les codes de retour.
Concepts / Sévérités — quand utiliser --min-severity.
Formats de sortie — schéma JSON, colonnes CSV, racine XML.
Guides / Intégration CI — recettes de pipeline complètes.