Skip to main content
The validate command checks annotation datasets for errors, warnings, and potential issues without performing a conversion.

​
Usage

panlabel validate <INPUT> [OPTIONS]

​
Parameters

​
input
path
required
Path to the dataset to validate. Can be a file or directory depending on the format.
​
--format
string
default:"ir-json"
Input format to validate against.Supported values: ir-json, coco, cvat, label-studio, tfod, yolo, vocAliases: coco-json, cvat-xml, label-studio-json, ls, tfod-csv, ultralytics, yolov8, yolov5, pascal-voc, voc-xml
​
--strict
flag
default:"false"
Treat warnings as errors. When enabled, the command exits with a non-zero status if any warnings are found.Useful for CI/CD pipelines where you want to enforce strict dataset quality.
​
--output
string
default:"text"
Output format for the validation report.Options:
  • text - Human-readable report with colors and formatting
  • json - Machine-readable JSON for programmatic use

​
Validation Checks

Panlabel performs comprehensive validation including:

​
Error-Level Issues

  • Missing required fields (image dimensions, file names, category IDs)
  • Invalid bounding box coordinates (negative values, width/height)
  • Referenced categories that don’t exist in the category list
  • Duplicate image IDs or annotation IDs
  • Malformed data structures

​
Warning-Level Issues

  • Bounding boxes partially or fully outside image bounds
  • Images with no annotations
  • Unusual aspect ratios or dimensions
  • Missing optional metadata
  • Suspicious coordinate values

​
Examples

​
Basic Validation

panlabel validate annotations.json --format coco
Validates a COCO dataset and prints a human-readable report.

​
Validate YOLO Dataset

panlabel validate /data/my_yolo --format yolo
Validates a YOLO directory structure.

​
Strict Mode for CI/CD

panlabel validate dataset.json --format ir-json --strict
Fails (exits with code 1) if there are any warnings, making it suitable for continuous integration checks.

​
JSON Output for Automation

panlabel validate input.json --format coco --output json > validation.json
Outputs a structured JSON report for parsing by other tools.

​
Validate VOC Dataset

panlabel validate /data/VOC2012 --format voc
Validates a Pascal VOC directory with Annotations/ and JPEGImages/ subdirectories.

​
Output Format

​
Text Report Example

Validation Report for dataset.json

Summary:
  ✓ Dataset is valid
  Images: 150
  Annotations: 1,234
  Categories: 8
  
Warnings (3):
  ⚠ image_001.jpg: Bounding box extends 2.5px beyond image boundary
  ⚠ image_042.jpg: Image has no annotations
  ⚠ image_089.jpg: Unusual aspect ratio (0.1)

All checks passed with warnings.

​
JSON Report Example

{
  "valid": true,
  "error_count": 0,
  "warning_count": 3,
  "images": 150,
  "annotations": 1234,
  "categories": 8,
  "errors": [],
  "warnings": [
    {
      "type": "bbox_out_of_bounds",
      "image": "image_001.jpg",
      "message": "Bounding box extends 2.5px beyond image boundary"
    },
    {
      "type": "no_annotations",
      "image": "image_042.jpg",
      "message": "Image has no annotations"
    },
    {
      "type": "unusual_aspect_ratio",
      "image": "image_089.jpg",
      "message": "Unusual aspect ratio (0.1)"
    }
  ]
}

​
Strict Mode Behavior

When --strict is enabled:
  1. All warnings are promoted to errors
  2. The command exits with code 1 if any warnings exist
  3. The report clearly indicates strict mode was active
  4. Useful for enforcing dataset quality in automated workflows

​
Example with Strict Mode

$ panlabel validate dataset.json --format coco --strict
Validation Report for dataset.json

Errors (3 - promoted from warnings in strict mode):
  ✗ image_001.jpg: Bounding box extends 2.5px beyond image boundary
  ✗ image_042.jpg: Image has no annotations
  ✗ image_089.jpg: Unusual aspect ratio (0.1)

Validation failed in strict mode.
$ echo $?
1

​
Exit Codes

  • 0 - Validation successful (no errors, or warnings only in non-strict mode)
  • 1 - Validation failed (errors found, or warnings found in strict mode)

​
Integration Examples

​
Pre-Conversion Validation

# Validate before converting
if panlabel validate input.json --format coco --strict; then
  panlabel convert -f coco -t yolo -i input.json -o ./yolo_output/
else
  echo "Validation failed, fix errors before converting"
  exit 1
fi

​
CI/CD Pipeline

# GitHub Actions example
- name: Validate annotations
  run: |
    panlabel validate annotations.json --format coco --strict --output json > validation.json
    
- name: Upload validation report
  uses: actions/upload-artifact@v3
  with:
    name: validation-report
    path: validation.json

​
Batch Validation

#!/bin/bash
# Validate multiple datasets
for dataset in data/*.json; do
  echo "Validating $dataset..."
  panlabel validate "$dataset" --format coco --output json > "${dataset}.validation.json"
done

​
See Also

Convert Command

Convert datasets (includes validation)

Stats Command

Analyze dataset statistics

Build docs developers (and LLMs) love

Get started for freeTalk to us