Formats de sortie

--format est accepté par validate, read et rules list. Cinq formats sont supportés. Choisissez selon le consommateur de la sortie.

Comparaison rapide

Format	Défaut ?	Couleurs TTY-aware	Schéma stable	Idéal pour
text	✅	✅		Usage interactif.
json			✅	Pipelines CI, diff.
csv			✅	Triage en tableur.
xml			✅	Intégrations legacy.
html				Partage avec partie prenante.

text

Lisible par un humain, coloré quand stdout est un TTY. Les couleurs ANSI sont désactivées automatiquement hors TTY ; forcez ou supprimez avec --force-color / --no-color.

Validate

Les anomalies streament inline (une par ligne), suivies d’un bloc de résumé. Chaque ligne :

[<severity>] <rule_id> — <message>[ — <file>:<line>][ — <field> = <value>]

Les segments optionnels sont omis quand la règle ne pointe pas un endroit précis.

[ERROR]    fk_violation — stop_id "BAD_STOP" not found in stops.txt — stop_times.txt:14203 — stop_id = BAD_STOP
[WARNING]  duplicate_route_short_name — two routes share short_name "747" — routes.txt:58 — route_short_name = 747
[INFO]     missing_shape — trip has no shape_id — trips.txt:1029

Le bloc de résumé clôt la sortie :

===================================
Summary
===================================
45 Errors — 94912 Warnings — 177074 Infos
Status: FAIL

Avec -o, les anomalies vont dans le fichier et la console n’affiche que les barres de progression et le résumé.

Read / Rules

Tabulaire. Les colonnes suivent l’ordre canonique de la spec GTFS (pour read) ou rule_id | severity | stage (pour rules list).

json

Stable, machine-readable. À utiliser en CI.

Validate

{
  "errors": [
    {
      "rule_id": "fk_violation",
      "section": "foreign_key",
      "severity": "Error",
      "message": "stop_id \"BAD_STOP\" not found in stops.txt",
      "file_name": "stop_times.txt",
      "line_number": 14203,
      "field_name": "stop_id",
      "value": "BAD_STOP"
    }
  ],
  "summary": {
    "error_count": 45,
    "warning_count": 94912,
    "info_count": 177074,
    "passed": false
  }
}

Schéma d’une anomalie (champs dans errors) :

Champ	Type	Notes
rule_id	string	Identifiant de règle enregistré. Voir règles de validation.
section	string	Section de spec à laquelle la règle appartient (ex. foreign_key).
severity	"Error" | "Warning" | "Info"	Capitalisé.
message	string	Description humaine.
file_name	string | null	Fichier GTFS pointé. null pour les anomalies au niveau flux.
line_number	integer | null	1-based, en-tête inclus.
field_name	string | null	Colonne mise en cause.
value	string | null	Valeur réelle ayant déclenché la règle.

Schéma summary :

Champ	Type
error_count	integer
warning_count	integer
info_count	integer
passed	boolean

passed est true ssi error_count == 0 après filtrage --min-severity. Le code de retour suit la même règle.

Read / Rules

read produit un tableau d’objets lignes avec clés = noms de colonnes. rules list produit un tableau d’objets {rule_id, severity, stage} encapsulé dans {count, rules}.

csv

Table plate, une ligne par anomalie (pour validate) ou par enregistrement (pour read). Inclut toujours la ligne d’en-tête.

Colonnes Validate

rule_id,section,severity,message,file_name,line_number,field_name,value
fk_violation,foreign_key,Error,"stop_id ""BAD_STOP"" not found in stops.txt",stop_times.txt,14203,stop_id,BAD_STOP

Les cellules vides (pas null — chaîne vide) sont utilisées quand un champ n’est pas renseigné.

Colonnes Read / Rules

read reprend l’ordre canonique des colonnes de la cible. rules list produit rule_id,severity,stage.

xml

XML standard avec racine <validation_report>. La structure reflète le schéma JSON — mêmes noms de champs, rendus en éléments plutôt qu’en clés.

<?xml version="1.0" encoding="UTF-8"?>
<validation_report>
  <summary>
    <error_count>45</error_count>
    <warning_count>94912</warning_count>
    <info_count>177074</info_count>
    <passed>false</passed>
  </summary>
  <error>
    <rule_id>fk_violation</rule_id>
    <section>foreign_key</section>
    <severity>Error</severity>
    <message>stop_id "BAD_STOP" not found in stops.txt</message>
    <file_name>stop_times.txt</file_name>
    <line_number>14203</line_number>
    <field_name>stop_id</field_name>
    <value>BAD_STOP</value>
  </error>
</validation_report>

rules list produit <rules> en racine avec un <rule> par entrée.

html

Rapport auto-contenu. CSS et JavaScript sont inlinés ; le fichier s’ouvre par double-clic dans n’importe quel navigateur — pas de serveur requis. À utiliser pour partager un rapport avec quelqu’un qui ne vit pas dans un terminal.

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

Le HTML inclut les compteurs, un toggle de regroupement par fichier et par règle, et des badges colorés par sévérité. Les gros rapports restent navigables — la table est virtualisée côté client.

Choisir le bon format

Pipeline CI

gapline validate -f gtfs.zip --format json -o report.json
jq '.summary.error_count' report.json

Revue tableur

gapline validate -f gtfs.zip --format csv -o report.csv
open report.csv

Intégration legacy

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

Partage partie prenante

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

Envoyez report.html par mail. Fonctionne hors-ligne, aucun outil requis côté destinataire.

Contrôle des couleurs

text est le seul format avec couleurs. Contrôlez la sortie couleur avec :

• --no-color — toujours désactivé, même en TTY.
• --force-color — toujours activé, même en pipe.
• Section [output] de gapline.toml — no_color, force_color (les flags ci-dessus gagnent).

Voir flags globaux.

Voir aussi

• gapline validate — référence --format sur la commande principale.
• Concepts / Sévérités — comment les anomalies sont classifiées.
• Guides / Intégration CI — parser du JSON en pipeline.