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

Corridor

A linear asset and the land managed along it. Carries a stable id, an asset type, a total length, and the CRS.

Segment

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.

Span

An ordered, contiguous run of segments between access points.

TreatmentUnit

A set of segments scheduled and contracted together, with a contract year window.

AccessPoint

A road, trail, landing, water, or other access point that serves a span or a segment.

Structure

A tower, pole, valve, crossing, or other asset structure with a required clearance.

ServiceStandard

A maximum vegetation height, a minimum clearance, and an access requirement.

Root fields

Field

Meaning

schema_version

brushline.corridor.v1.

crs

Coordinate reference system for every geometry.

corridors

One or more corridors.

segments

One or more decision segments.

spans

One or more ordered spans.

treatment_units

One or more contracted treatment units.

access_points

Access points; optional at the root, but a referenced access point must exist.

structures

Structures; optional at the root, but a referenced structure must exist.

service_standards

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-1 in 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))