OpenLabel Validator

A Python tool to validate OpenLabel JSON files against the official ASAM OpenLabel schema.

Features

• Schema Validation: Validates against the official ASAM OpenLabel V1.0.0 schema
• Batch Processing: Validate multiple files with progress indication
• Directory Scanning: Scan directories for JSON files (with recursive option)
• Caching: Automatic schema caching with configurable expiry
• Error Reporting: Clear validation error messages
• Error Handling: Graceful handling of network and file system issues
• Progress Tracking: Visual progress bars for batch operations

Installation

Method 1: From Source (Recommended)

# Clone the repository
git clone git@github.com:dxc-technology/openlabel-validator.git
cd openlabel-validator

# Install dependencies
pip install -r requirements.txt

Method 2: Install as Package

# Install directly from source
pip install git+ssh://git@github.com/dxc-technology/openlabel-validator.git

# Or install in development mode
git clone git@github.com:dxc-technology/openlabel-validator.git
cd openlabel-validator
pip install -e .

Prerequisites

• Python 3.7 or higher
• pip package manager

Platform-Specific Installation

# Windows
python -m pip install -r requirements.txt

# macOS with Homebrew Python
python3 -m pip install -r requirements.txt

# Linux/Ubuntu
python3 -m pip install -r requirements.txt

Virtual Environment (Recommended)

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Usage

Basic Usage

# Validate a single file
python validate_openlabel.py data.json

# Validate multiple files (with progress bar)
python validate_openlabel.py data1.json data2.json data3.json

# Validate all JSON files in a directory
python validate_openlabel.py --folder /path/to/json/files

# Validate JSON files recursively in subdirectories
python validate_openlabel.py --folder /path/to/json/files --recursive

# Check version
python validate_openlabel.py --version

Advanced Options

# Use custom schema URL
python validate_openlabel.py --schema-url https://custom-schema.com/schema.json data.json

# Specify custom cache directory
python validate_openlabel.py --cache-dir /path/to/cache data.json

# Bypass SSL verification (use with caution)
python validate_openlabel.py --bypass-ssl data.json

# Set cache expiry (in days)
python validate_openlabel.py --cache-expiry-days 30 data.json

# Combine folder scanning with specific files
python validate_openlabel.py --folder /data/jsons file1.json file2.json

# Use folder scanning with other options
python validate_openlabel.py --folder /data --recursive --bypass-ssl

Example OpenLabel JSON Structure

Here's a minimal example of a valid OpenLabel JSON file:

{
  "openlabel": {
    "metadata": {
      "schema_version": "1.0.0"
    },
    "coordinate_systems": {
      "base": {
        "type": "geo",
        "parent": ""
      }
    },
    "streams": {},
    "frames": {},
    "frame_intervals": [],
    "objects": {},
    "relations": {},
    "tags": {},
    "actions": {}
  }
}

Output Examples

Successful Validation

data.json is valid according to the OpenLabel schema

Validation Errors

data.json failed validation:
  • 'openlabel' is a required property
  • Additional property 'invalid_field' is not allowed

Batch Validation

Validating files: 100%|██████████| 3/3 [00:01<00:00, 2.5file/s]

Validation Summary:
Valid files: 2
Invalid files: 1

Invalid files:

data3.json:
  • 'metadata' is a required property at openlabel

Directory Scanning

Found 5 JSON files in /path/to/data
Validating files: 100%|██████████| 5/5 [00:02<00:00, 2.1file/s]

Validation Summary:
Valid files: 4
Invalid files: 1

Troubleshooting

SSL Certificate Issues

If you encounter SSL certificate errors:

# Temporary workaround (use with caution)
python validate_openlabel.py --bypass-ssl data.json

Network Issues

• Check your internet connection
• Verify firewall settings allow HTTPS traffic
• Try using a different schema URL with --schema-url

File Access Issues

• Ensure the JSON file exists and is readable
• Check file permissions
• Verify the file path is correct

Cache Issues

# Clear cache by specifying a new cache directory
python validate_openlabel.py --cache-dir /tmp/new-cache data.json

# Or delete the existing cache directory
rm -rf ~/.cache/openlabel-validator

Development

Running Tests

python -m pytest tests/

Code Quality

# Type checking
mypy validate_openlabel.py

# Linting
flake8 validate_openlabel.py

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

About

Project Origins

OpenLabel Validator was originally developed by LUXOFT, A DXC TECHNOLOGY COMPANY as part of the pre-competitive research initiative “just better DATA – Efficient and High-Precision Data Generation for AI Applications in Autonomous Driving.” It was initiated by the “VDA-Leitinitiative” (VDA lead initiative autonomous and connected driving). The jbDATA project was funded by the Federal Ministry for Economic Affairs and Energy (BMWE). The authors would like to thank the funding body.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Schema Information

This validator uses the official ASAM OpenLabel schema:

• Version: 1.0.0
• URL: https://openlabel.asam.net/V1-0-0/schema/openlabel_json_schema.json
• Specification: ASAM OpenLABEL Standard

For more information about the OpenLabel format, visit the official ASAM documentation.