Corridor graph contract
The corridor graph defines the decision units and the operational groupings. The schema version is
brushline.corridor.v1. The contract is validated by
brushline.model.corridor.validate_corridor_network().
Objects
Object |
Meaning |
|---|---|
|
A linear asset and the land managed along it. Carries a stable id, an asset type, a total length, and the CRS. |
|
The decision unit. A length of corridor with a stable id, a zero-based position within its span, a length, a line geometry, a service standard, an optional access point, and optional structures. |
|
An ordered, contiguous run of segments between access points. |
|
A set of segments scheduled and contracted together, with a contract year window. |
|
A road, trail, landing, water, or other access point that serves a span or a segment. |
|
A tower, pole, valve, crossing, or other asset structure with a required clearance. |
|
A maximum vegetation height, a minimum clearance, and an access requirement. |
Root fields
Field |
Meaning |
|---|---|
|
|
|
Coordinate reference system for every geometry. |
|
One or more corridors. |
|
One or more decision segments. |
|
One or more ordered spans. |
|
One or more contracted treatment units. |
|
Access points; optional at the root, but a referenced access point must exist. |
|
Structures; optional at the root, but a referenced structure must exist. |
|
One or more service standards. |
Invariants
The validator checks:
every collection id is unique;
every corridor CRS matches the root CRS;
every segment references an existing corridor, span, treatment unit, and service standard;
every segment is listed in its span and in its treatment unit;
a span’s segments have the contiguous sequence
0 .. n-1in the listed order;no span or treatment unit repeats a segment;
a segment belongs to at most one treatment unit;
a treatment unit’s contract window is ordered;
a span’s access points exist and belong to the same corridor;
a structure’s segment and corridor exist and agree;
the sum of a corridor’s segment lengths equals its declared length within the tolerance;
a segment without an access point is a warning, not an error.
Named errors use the prefixes CORRIDOR-ID, CORRIDOR-CRS, CORRIDOR-REF,
CORRIDOR-SPAN, CORRIDOR-SEQUENCE, CORRIDOR-TU, CORRIDOR-ACCESS,
CORRIDOR-STRUCTURE, and CORRIDOR-LENGTH.
Geometry
Segment geometry is LINESTRING or MULTILINESTRING WKT. Access point geometry is POINT WKT.
All geometry is in the root CRS. A reprojection is an explicit, recorded decision, not an implicit
step.
Example
{
"schema_version": "brushline.corridor.v1",
"crs": "EPSG:3005",
"corridors": [
{
"corridor_id": "c1",
"name": "Example transmission corridor",
"asset_type": "transmission",
"length_m": 30.0,
"crs": "EPSG:3005"
}
],
"segments": [
{
"segment_id": "s1",
"corridor_id": "c1",
"span_id": "sp1",
"treatment_unit_id": "tu1",
"sequence": 0,
"length_m": 10.0,
"geometry_wkt": "LINESTRING (0 0, 10 0)",
"service_standard_id": "std1",
"access_point_id": "ap1",
"structure_ids": ["st1"]
},
{
"segment_id": "s2",
"corridor_id": "c1",
"span_id": "sp1",
"treatment_unit_id": "tu1",
"sequence": 1,
"length_m": 20.0,
"geometry_wkt": "LINESTRING (10 0, 30 0)",
"service_standard_id": "std1",
"access_point_id": "ap1"
}
],
"spans": [
{
"span_id": "sp1",
"corridor_id": "c1",
"segment_ids": ["s1", "s2"],
"access_point_ids": ["ap1"]
}
],
"treatment_units": [
{
"treatment_unit_id": "tu1",
"corridor_id": "c1",
"segment_ids": ["s1", "s2"],
"contract_start_year": 2027,
"contract_end_year": 2031
}
],
"access_points": [
{
"access_point_id": "ap1",
"corridor_id": "c1",
"kind": "road",
"location_wkt": "POINT (0 0)"
}
],
"structures": [
{
"structure_id": "st1",
"corridor_id": "c1",
"segment_id": "s1",
"structure_type": "tower",
"clearance_m": 6.0
}
],
"service_standards": [
{
"service_standard_id": "std1",
"max_height_m": 3.0,
"min_clearance_m": 6.0,
"access_required": true
}
]
}
Python use
from pathlib import Path
from brushline.model.corridor import CorridorNetwork, validate_corridor_network
network = CorridorNetwork.model_validate_json(Path("corridor.json").read_text())
report = validate_corridor_network(network)
if not report.is_valid:
raise SystemExit("\n".join(report.errors))