Skip to main content
The IR JSON format is Panlabel’s canonical intermediate representation. It preserves all dataset information without loss and serves as the bridge between all other formats.

​
Overview

  • Path type: JSON file (.json)
  • Lossiness: Lossless
  • Bbox format: Pixel-space XYXY [xmin, ymin, xmax, ymax]
  • Use case: Canonical storage, lossless conversion chains

​
Key Features

✓ Preserves dataset info and metadata
✓ Preserves licenses
✓ Preserves image metadata and attributes
✓ Preserves annotation confidence scores
✓ Preserves custom attributes on annotations and images
✓ Deterministic output (sorted by IDs)
✓ Supports images without annotations

​
Structure

The IR JSON format mirrors COCO’s structure but uses XYXY bbox coordinates: 
{
  "info": {
    "name": "My Dataset",
    "version": "1.0",
    "description": "Sample dataset",
    "url": "https://example.com",
    "year": 2024,
    "contributor": "Your Name",
    "date_created": "2024-01-15"
  },
  "licenses": [
    {
      "id": 1,
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  ],
  "images": [
    {
      "id": 1,
      "file_name": "image001.jpg",
      "width": 640,
      "height": 480,
      "license_id": 1,
      "date_captured": "2024-01-15T10:30:00Z",
      "attributes": {}
    }
  ],
  "categories": [
    {
      "id": 1,
      "name": "person",
      "supercategory": "human"
    }
  ],
  "annotations": [
    {
      "id": 1,
      "image_id": 1,
      "category_id": 1,
      "bbox": [100.0, 150.0, 300.0, 400.0],
      "confidence": 0.95,
      "attributes": {}
    }
  ]
}

​
Bounding Box Format

Bboxes are stored as pixel-space XYXY: 
"bbox": [xmin, ymin, xmax, ymax]
  • xmin: Left edge in pixels
  • ymin: Top edge in pixels
  • xmax: Right edge in pixels
  • ymax: Bottom edge in pixels

​
Example

"bbox": [10.0, 20.0, 100.0, 80.0]
Represents a box from (10, 20) to (100, 80) in pixel coordinates.

​
Schema Details

​
DatasetInfo

{
  "name": "string (optional)",
  "version": "string (optional)",
  "description": "string (optional)",
  "url": "string (optional)",
  "year": "integer (optional)",
  "contributor": "string (optional)",
  "date_created": "string (optional)"
}

​
License

{
  "id": "integer (required)",
  "name": "string (required)",
  "url": "string (optional)"
}

​
Image

{
  "id": "integer (required)",
  "file_name": "string (required)",
  "width": "integer (required)",
  "height": "integer (required)",
  "license_id": "integer (optional)",
  "date_captured": "string (optional)",
  "attributes": "object (optional, default: {})"
}

​
Category

{
  "id": "integer (required)",
  "name": "string (required)",
  "supercategory": "string (optional)"
}

​
Annotation

{
  "id": "integer (required)",
  "image_id": "integer (required)",
  "category_id": "integer (required)",
  "bbox": "[xmin, ymin, xmax, ymax] (required)",
  "confidence": "float (optional)",
  "attributes": "object (optional, default: {})"
}

​
Attributes

Both Image and Annotation support custom attributes as string key-value pairs: 
{
  "id": 1,
  "image_id": 1,
  "category_id": 1,
  "bbox": [10.0, 20.0, 100.0, 80.0],
  "attributes": {
    "occluded": "1",
    "truncated": "0",
    "custom_field": "custom_value"
  }
}
Format-specific attributes are preserved during conversion (e.g., cvat_image_id, ls_rotation_deg).

​
Deterministic Output

When writing IR JSON, Panlabel produces deterministic output:
  • All lists are sorted by ID
  • Ensures reproducible builds
  • Enables meaningful git diffs

​
Usage

​
Read IR JSON

panlabel convert input.json output-dir/ --input-format ir-json --output-format yolo

​
Write IR JSON

panlabel convert dataset/ output.json --input-format yolo --output-format ir-json

​
When to Use IR JSON

Use IR JSON when:
  • You need lossless conversion between formats
  • You want to preserve all metadata and attributes
  • You’re building conversion pipelines
  • You need deterministic, version-controllable output
Use other formats when:
  • Training models (use YOLO, COCO, etc.)
  • Integrating with specific tools (use their native format)
  • Working with legacy systems (use VOC, TFOD, etc.)

​
See Also

COCO Format

Similar structure but uses XYWH bbox format

Format Overview

Compare all supported formats

Build docs developers (and LLMs) love

Get started for freeTalk to us