Configuration file

gapline reads its configuration from TOML files. Unknown keys are rejected: a typo in a section or field produces a parse error with the path to the offending file. See getting started / configuration for how the lookup chain works.

This page documents every accepted key. Some are forward-compatible stubs — they deserialize cleanly but are not yet read by any runtime code. They are documented for completeness and will become live as the features land.

Top-level sections

[default]
[validation]
[validation.thresholds.speed_limits]
[validation.thresholds.distances]
[validation.thresholds.time]
[validation.thresholds.coordinates]
[validation.thresholds.calendar]
[validation.thresholds.naming]
[performance]
[output]
[batch]
[experimental]

Any section can be omitted — every key has a default.

`[default]`

Defaults for CLI arguments that can be omitted from the command line.

Key	Type	Default	Description
`feed`	path	—	Feed path used when `--feed` is omitted. Accepts a ZIP archive or directory.
`format`	string	—	Output format: `text`, `json`, `csv`, `xml`, `html`. Overridden by `--format`.
`output`	path	—	Output destination when `--output` is omitted. Per-command.

`[validation]`

Rule selection and high-level behaviour.

Key	Type	Default	Description
`min_severity`	`error\|warning\|info`	—	Filter out findings below this level. Overridden by `--min-severity`.
`disabled_rules`	array of string	`[]`	Rule IDs to skip. CLI `--disable-rule` appends to this list.
`max_rows`	integer	—	Maximum data rows per file (consumed by `TooManyRowsRule`). Omit to disable the check.
`fail_fast`	boolean	`false`	Forward-compat. Not yet wired.
`max_errors_per_rule`	integer	—	Forward-compat. Not yet wired.
`enabled_rules`	array of string	`[]`	Forward-compat. Not yet wired. When non-empty, will pin the rule set.

`[validation.thresholds.speed_limits]`

Per-route-type maximum speeds in km/h. Consumed by speed_validation.

Key	Type	Default	Applies to `route_type`
`tram_kmh`	number	`150.0`	0
`subway_kmh`	number	`150.0`	1
`rail_kmh`	number	`500.0`	2
`bus_kmh`	number	`150.0`	3
`ferry_kmh`	number	`150.0`	4
`cable_tram_kmh`	number	`30.0`	5
`aerial_lift_kmh`	number	`50.0`	6
`funicular_kmh`	number	`50.0`	7
`trolleybus_kmh`	number	`150.0`	11
`monorail_kmh`	number	`150.0`	12
`default_kmh`	number	`150.0`	Extended/unknown route types

Every value must be a finite number strictly greater than zero.

`[validation.thresholds.distances]`

Distance thresholds in metres.

Key	Type	Default	Description
`max_stop_to_shape_distance_m`	number	`100.0`	Max allowed distance from a stop to its nearest shape point.
`min_shape_point_distance_m`	number	`1.11`	Minimum spacing between consecutive shape points.
`shape_dist_incoherence_ratio`	number	`0.5`	Tolerance for `shape_dist_traveled` mismatch. Must be in `[0, 1]`.
`max_transfer_distance_m`	number	`10000.0`	Upper bound on `transfers.min_transfer_time`-derived distance.
`transfer_distance_warning_m`	number	`2000.0`	Warning threshold. Must be ≤ `max_transfer_distance_m`.

All values must be finite and non-negative.

`[validation.thresholds.time]`

Key	Type	Default	Description
`max_trip_duration_hours`	integer	`24`	Maximum allowed trip duration. Omit to disable the check. Must be `> 0` when set.

`[validation.thresholds.coordinates]`

Key	Type	Default	Description
`min_distance_from_origin_m`	number	`1000.0`	Reject coordinates closer than this to 0/0.
`min_distance_from_poles_m`	number	`1000.0`	Reject coordinates closer than this to either pole.

`[validation.thresholds.calendar]`

Key	Type	Default	Description
`min_feed_coverage_days`	integer	`30`	Minimum calendar coverage. Must be `> 0`.
`feed_expiration_warning_days`	integer	`7`	Warn when the feed expires in fewer days than this.
`min_trip_activity_days`	integer	`7`	Flag trips active on fewer days than this.

`[validation.thresholds.naming]`

Key	Type	Default	Description
`max_route_short_name_length`	integer	`12`	Warn when `route_short_name` exceeds this many characters. Must be `> 0`.

`[performance]`

Key	Type	Default	Description
`num_threads`	integer	—	Worker pool size. Auto-detected when omitted. Overridden by `--threads`.
`csv_buffer_size`	integer	`8192`	CSV reader buffer size in bytes.
`parallel_parsing`	boolean	`true`	Forward-compat. Not yet wired.
`parallel_validation`	boolean	`true`	Forward-compat. Not yet wired.

`[output]`

Key	Type	Default	Description
`force_color`	boolean	`false`	Force ANSI colors. Overridden by `--force-color`.
`no_color`	boolean	`false`	Suppress ANSI colors. Overridden by `--no-color`.
`show_progress`	boolean	`true`	Whether to render per-group progress bars during validation.
`verbosity`	`quiet \| normal \| verbose`	`normal`	Log verbosity.
`timestamp_format`	`none \| iso8601 \| unix \| relative`	`none`	Timestamp style in report headers.
`group_by_file`	boolean	`true`	Group findings by `file_name` in the text report.
`group_by_rule`	boolean	`false`	Group findings by `rule_id` in the text report.

`[batch]`

Key	Type	Default	Description
`continue_on_error`	boolean	`false`	Planned: keep running after a failed directive in `.gl` scripts.
`echo_commands`	boolean	`true`	Planned: print each directive to stderr before execution.

`[experimental]`

Key	Type	Default	Description
`enabled`	boolean	`false`	Master switch.
`validate_flex`	boolean	`false`	Planned GTFS-Flex validation.
`validate_fares_v2`	boolean	`false`	Planned GTFS Fares v2 validation.
`validate_geojson`	boolean	`false`	Planned GeoJSON shape validation.

Complete example

[default]
feed   = "./data/gtfs.zip"
format = "json"
output = "./reports/latest.json"

[validation]
disabled_rules = ["block_id_trip_overlap"]
min_severity   = "warning"
max_rows       = 5_000_000

[validation.thresholds.speed_limits]
rail_kmh = 320
bus_kmh  = 120

[validation.thresholds.distances]
max_transfer_distance_m     = 5000
transfer_distance_warning_m = 1500

[validation.thresholds.calendar]
min_feed_coverage_days       = 60
feed_expiration_warning_days = 14

[performance]
num_threads     = 4
csv_buffer_size = 32_768

[output]
show_progress    = true
group_by_rule    = true
verbosity        = "normal"
timestamp_format = "iso8601"

Error behaviour

A missing config file (any of the three lookup layers) is silently skipped.
A file that exists but cannot be read (permission denied, I/O error) aborts with exit code 3.
A file that parses to invalid TOML, or contains an unknown key, aborts with exit code 2 and a message that includes the path and the offending token.
A semantically invalid value (negative speed, zero calendar coverage, incoherent thresholds) aborts with exit code 2 and a message that cites the specific field.

See concepts / exit codes.

Configuration file

Top-level sections

[default]

[validation]

[validation.thresholds.speed_limits]

[validation.thresholds.distances]

[validation.thresholds.time]

[validation.thresholds.coordinates]

[validation.thresholds.calendar]

[validation.thresholds.naming]

[performance]

[output]

[batch]

[experimental]