Validation — concepts and best practices

This page is primarily reference + explanation. Use it to understand what validation checks and when to run it.

Why validation matters

R3XA is defined by a JSON Schema. Validation ensures:

  • Completeness: required fields are present.

  • Consistency: values and types match the schema.

  • Reproducibility: others can reuse your data without guessing missing metadata.

Two levels of validation

1) Full file validation

Use when you have a complete R3XA document:

r3xa.validate()

2) Item (registry) validation

Use for reusable components stored in the registry:

from r3xa_api import validate_item
validate_item(camera_item)

This checks against the specific kind schema (e.g. data_sources/camera) rather than the full R3XA schema.

Best practices

  • Validate early: validate items as soon as you define them (especially registry items).

  • Validate before publish: run full validation before sharing or archiving.

  • Use registry items: avoid duplicating camera, machine, and software descriptions.

  • Keep IDs stable: change id only when the object is actually different.

  • Document units: use unit(...) consistently for anything with scale/units.

Common pitfalls

  • Missing required fields (e.g., image_size for data_sources/camera).

  • Wrong types (strings instead of numeric timestamps).

  • Stale registry items (schema evolves; re‑validate periodically).