Vegetation state and treatment contract

The state contract carries the vegetation state, the treatment actions, the treatment transitions, and the observations. The schema version is brushline.state.v1. The contract is validated by brushline.model.state.validate_state_contract().

Objects

Object

Meaning

VegetationState

One functional group’s state on one segment in one year, with height, cover, density, biomass, age, uncertainty, treatment history, and provenance.

Uncertainty

Standard deviations and a confidence value for the state.

TreatmentAction

A planned, applied, or cancelled treatment with a method, season, intensity, efficacy, cost hooks, and status.

TreatmentTransition

The before-and-after state of a treatment, with the method, efficacy, regrowth delay, and source.

Observation

A remote or field observation with a sensor, date, product, coverage, error, model card, and provenance.

Functional groups and classes

Functional groups: unknown, shrub, deciduous_sprout, conifer, grass_herb.

State classes: unknown, partial, grass_herb, shrub, young_tree, mixed, mature_edge.

An unknown state uses the unknown functional group and zero height and cover. A known state must name a functional group. A partial state is allowed and is reported as a warning.

Treatment methods and sensors

Treatment methods: manual, mechanical, chemical, mowing, grazing, prescribed_fire, other.

Seasons: spring, summer, fall, winter, any.

Sensors: lidar, uav_lidar, imagery, field, inspection, other.

Invariants

The models and the validator check:

  • the state key (segment_id, state_year, functional_group) is unique;

  • height and density are non-negative; cover is between 0 and 100;

  • an unknown state is empty and uses the unknown group;

  • a known state names a functional group;

  • years are between 1900 and 2200;

  • a treatment action’s intensity and efficacy are between 0 and 1;

  • a treatment transition does not increase height or cover;

  • an observation’s coverage is between 0 and 100 and its errors are non-negative;

  • every treatment, transition, and observation references a segment with a state;

  • every required segment has at least one state;

  • partial states, low confidence, partial coverage, and long regrowth delays are warnings.

Named errors use the prefixes STATE-ID, STATE-REF, and STATE-MISSING. Named warnings use STATE-PARTIAL, STATE-UNCERTAIN, STATE-COVERAGE, and STATE-DELAY.

Example

{
  "schema_version": "brushline.state.v1",
  "states": [
    {
      "segment_id": "s1",
      "state_year": 2026,
      "functional_group": "shrub",
      "state_class": "shrub",
      "height_m": 2.0,
      "cover_pct": 50.0,
      "density_per_ha": 1200.0,
      "age_years": 3,
      "uncertainty": {"height_m_sd": 0.2, "cover_pct_sd": 5.0, "confidence": 0.9},
      "source": "synthetic",
      "source_version": "1.0"
    }
  ],
  "treatments": [
    {
      "action_id": "a1",
      "segment_id": "s1",
      "year": 2026,
      "season": "summer",
      "method": "mowing",
      "intensity": 0.8,
      "efficacy": 0.7,
      "cost_per_ha": 1200.0,
      "status": "applied"
    }
  ],
  "transitions": [
    {
      "transition_id": "t1",
      "segment_id": "s1",
      "year": 2026,
      "method": "mowing",
      "before_height_m": 2.0,
      "after_height_m": 0.5,
      "before_cover_pct": 50.0,
      "after_cover_pct": 10.0,
      "efficacy": 0.75,
      "regrowth_delay_years": 2,
      "source": "synthetic"
    }
  ],
  "observations": [
    {
      "observation_id": "o1",
      "segment_id": "s1",
      "observed_date": "2026-07-01",
      "sensor": "lidar",
      "product": "CHM",
      "coverage_pct": 100.0,
      "height_m": 2.0,
      "cover_pct": 50.0,
      "height_error_m": 0.2,
      "cover_error_pct": 5.0,
      "source": "synthetic",
      "source_version": "1.0"
    }
  ]
}

Python use

from pathlib import Path
from brushline.model.state import StateContract, validate_state_contract

contract = StateContract.model_validate_json(Path("state.json").read_text())
report = validate_state_contract(contract, required_segment_ids={"s1", "s2"})
if not report.is_valid:
    raise SystemExit("\n".join(report.errors))