Component Validation Guide¶

Overview¶

Component validation is offline schema + physics validation of the JSON files in backend/categorized_databases/. There are two validators, both local — no API keys, no internet access:

Validator	Location	What it checks
`validate_components.py`	`backend/validate_components.py`	Pydantic schema, tiered field completeness, category rules, cross-field physics, frequency-band placement
`validate_component_data.py`	`backend/scripts/validate_component_data.py`	Unit errors (MHz stored as GHz, Watts stored as dBm), frequency/power range sanity

Note: An earlier internet-based validation system (DigiKey/Octopart API cross-checking via validate-components.ps1 / validate_all_components.py) was removed. If you find references to it elsewhere, they are stale — the current system is the offline validation described here.

Quick Start¶

Validate the whole database¶

cd backend
python validate_components.py

Writes validation_report.json, regenerates the JSON Schema at categorized_databases/schema/component_schema.json, and prints a summary:

============================================================
  Validation Summary
============================================================
  Total scanned:            ...
  Valid (schema):            ...
  Invalid (schema):          ...
  Tier 1 failures:           ...
  Tier 2 warnings:           ...
  Tier 3 info:               ...
  Tier 4 category warnings:  ...
  Tier 5 physics errors:     ...
  Band mismatches:           ...
  Direction errors:          ...
============================================================

Validate one category (or sub-band)¶

cd backend
python validate_components.py --category pa
python validate_components.py --category pa/sub_1ghz

CI / pre-commit mode¶

cd backend
python validate_components.py --check

--check writes no report files and exits with code 1 if there are any blocking failures (Tier 1 schema failures or ferrite direction errors). Tier 5 physics issues print a warning but do not block.

Options (`validate_components.py`)¶

Flag	Meaning
`--category <name>`	Scan one category or sub-path (e.g. `pa`, `pa/sub_1ghz`)
`--root <dir>`	Database root (default: `backend/categorized_databases`)
`--output <file>`	Report file (default: `validation_report.json`)
`--check`	CI/hook mode: exit 1 on blocking failures, no report files

What `validate_components.py` Checks¶

Tier 1 — Schema (blocking): each JSON file must parse and satisfy the Pydantic RFComponent model (backend/component_schema.py). Invalid JSON or schema violations are failures.
Tier 2 — Core fields (warning): flags missing datasheet, package_type, package_dimensions, thermal_specs.
Tier 3 — Enhanced fields (info): flags missing description, key_features, electrical_specifications.
Tier 4 — Category rules (warning): category-specific recommended fields, from backend/category_validation_rules.py.
Tier 5 — Physics (error, non-blocking): cross-field physics rules plus a check that the file's frequency_range actually overlaps the frequency-band folder it sits in (band mismatch).
Ferrite direction (blocking): for isolator/circulator parts, the direction field must be exactly clockwise or counterclockwise.

Skipped automatically: metadata.json, category_index.json, and anything under schema/ or archive/ directories.

Unit-Error Checker (`validate_component_data.py`)¶

Catches the two classic data-entry corruption patterns:

Frequency: values must be 0–100 GHz; values near 1000/2000/... strongly suggest MHz stored as GHz (divide by 1000).
Power: values must be −50…100 dBm; values near 100/200/... suggest Watts stored as dBm (convert: 10*log10(W) + 30).

cd backend

# Whole database
python scripts/validate_component_data.py

# One category / band / file
python scripts/validate_component_data.py --category pa
python scripts/validate_component_data.py --category pa --band 1_6ghz
python scripts/validate_component_data.py --file categorized_databases/pa/1_6ghz/SST12CP21.json

Flag	Meaning
`--category <name>`	Validate one category
`--band <band>`	Validate one frequency band within the category
`--file <path>`	Validate a single JSON file
`--strict`	Exit non-zero on validation failures

Exit code is non-zero when any file is invalid, so it is CI-friendly.

Output Files¶

validation_report.json (or --output path) — full report from validate_components.py: failures, warnings, info, category warnings, physics errors, band mismatches, direction errors, keyed by relative file path.
categorized_databases/schema/component_schema.json — regenerated JSON Schema derived from the Pydantic RFComponent model (skipped in --check mode).

When to Run Validation¶

After any component edit — see COMPONENT_UPDATE_GUIDE.md for the update workflow.
After bulk imports — run both validators; the unit-error checker exists precisely because bulk imports have shipped MHz-as-GHz and Watts-as-dBm errors.
Before committing database changes — python validate_components.py --check is the blocking gate.