openlabel-checker

A validator and quality checker for ASAM OpenLABEL 1.0.0 annotation files.

OpenLABEL is the JSON-based format ASAM standardizes for object, action, event, and context annotations in autonomous-driving and robotics data. ASAM publishes an official Quality Checker framework (MPL-2.0) with checker bundles for OpenDRIVE, OpenSCENARIO XML, OTX, and OpenMATERIAL 3D — but no equivalent exists yet for OpenLABEL. This project fills that gap: it validates a file against the official OpenLABEL JSON Schema and runs a set of structural/semantic checks the schema alone can't express (dangling references, inverted frame intervals, negative bounding box dimensions, and so on).

Install

pip install openlabel-checker

Usage

openlabel-check annotations.json

openlabel-check: annotations.json
  ERROR check_geometry: bbox 'bbox_shape' has negative dimension w=-5.0 [openlabel.objects.1.object_data.bbox[0]]
  WARN  check_frame_intervals: frame_intervals[1] (0-3) overlaps frame_intervals[2] (2-4) [openlabel.objects.1]
summary: 1 error(s), 1 warning(s), 0 info

Exit code is 0 if no error-severity issues were found, 1 otherwise — so it's usable as a CI gate.

Pass --json for a machine-readable report:

openlabel-check annotations.json --json

{
  "file": "annotations.json",
  "checkers": [
    {
      "checker_id": "check_geometry",
      "description": "Checks bbox/rbbox/cuboid values parse and have non-negative dimensions.",
      "status": "completed",
      "issues": [
        {
          "checker_id": "check_geometry",
          "severity": "error",
          "message": "bbox 'bbox_shape' has negative dimension w=-5.0",
          "path": "openlabel.objects.1.object_data.bbox[0]"
        }
      ]
    }
  ],
  "summary": { "error": 1, "warning": 0, "info": 0 }
}

Checkers

Every checker has a stable, check_-prefixed ID and a severity per issue (error / warning / info). check_json_schema validates against the schema; everything else is a structural or semantic check the schema can't express on its own.

Design notes

• The vendored schema is the official file ASAM serves at https://openlabel.asam.net/V1-0-0/schema/openlabel_json_schema.json (see src/openlabel_checker/schema_data/PROVENANCE.md). No local modifications.
• The Issue model (checker_id, severity, message, path) deliberately mirrors the ASAM qc-framework's CheckerBundle → Checker → Issue result model, so this tool's output can be re-serialized into that framework's .xqar result format later without a redesign — the goal is that this project could eventually become the framework's qc-openlabel bundle. That serializer (an --format asam-qc flag) is out of scope for this first version; only the internal model is shaped to make it a straightforward follow-up.

Development

pip install -e ".[dev]"
pytest

Contributing

Issues and PRs welcome. Checkers live one-per-file under src/openlabel_checker/checkers/; each is a plain function from the parsed document to a CheckerOutcome, with fixtures in tests/fixtures/ that trip it. Keep new checkers narrowly scoped and add a fixture alongside them.

License

MPL-2.0. See LICENSE.