Two version identifiers
Every API response includes two version fields in the system_info block:
"system_info": {
"api_version": "v1",
"model_version": "adult_ridge_v4.0",
"computation_time_ms": 14
}
| Field | What it identifies | When it changes |
|---|---|---|
api_version | The request/response schema contract | Breaking schema changes only |
model_version | The trained model and calibration parameters | Model retraining, recalibration |
api_version and model_version are versioned independently. A model update (improved calibration, recalibration on new data) does not change api_version. A schema change (new field, renamed parameter) increments api_version.
Semantic versioning policy
The API follows Semantic Versioning: MAJOR.MINOR.PATCH.
| Increment | Trigger | Example |
|---|---|---|
| MAJOR | Breaking schema change — removed or renamed field, changed enum values | v1 → v2 |
| MINOR | New capability, new field, new parameter — backwards compatible | 1.3.0 → 1.4.0 |
| PATCH | Bug fix, calibration correction, safety fix — no schema change | 1.3.1 → 1.3.2 |
Breaking changes are announced in advance. A deprecated field or parameter will be documented in the response meta_warnings for at least one minor version before removal.
What model updates mean in practice
A model version change (e.g., adult_ridge_v3.0 → adult_ridge_v4.0) means the trained coefficients, calibration parameters, or the dimension catalog changed. Concretely:
- Predicted values may shift slightly for the same input — this is a calibration improvement, not a regression.
- Confidence scores may change — recalibration means scores better reflect empirical coverage.
- Dimension catalog changes are noted explicitly in the changelog — a dimension added or removed is always a documented event, not a silent change.
- The request/response schema is unchanged — your integration code continues to work without modification.
If your application stores predictions, a model version change is a signal to consider re-running queries that are sensitive to small value shifts.
Current versions
| Version | Released | Notes |
|---|---|---|
API v1 | 2025 | Current schema version — no breaking changes planned |
Model adult_ridge_v4.0 | 2026-04-12 | Current production model. Dimension catalog locked at 130. |
Model pediatric_lms_v1 | 2025 | Unchanged since initial release. |
Version history summary
v1.4.0 — Dimension catalog finalized at 130. 15 dimensions removed (duplicates, unmeasurable aliases, below accuracy threshold). PRIMARY_RICH confidence tier finalized at 84/87/80 based on Track 6+7 validation. Anchor bounds validation added for 14 measurements.
v1.3.2 — Hip circumference fallback corrected to ANSUR II empirical coefficients (residual bias < ±2 mm). Head circumference bias correction updated. Imputation confidence propagation fixed.
v1.3.1 — AUTO engine routing added. input_origin_region / target_region two-field contract finalized; deprecated region parameter removed.
v1.3.0 — Request schema restructured into input_data / output_settings hierarchy. system_info block added to every response. include_range_95 and include_iso_codes flags added.
v1.2.0 — Civilian waist accuracy improved (staged NHANES BMI dampening). interpupillary_distance models retrained (post-correction MAE: 2.94 mm). Confidence Score recalibrated (Precision Validation v2.0: 23,856 calls, average MAE 14.1 mm).
v1.1.0 — Confidence Score v3 recalibration. Score bracket 80–89 now dominant at 62.6% of predictions.
v1.0.0 — Initial release. Dual-core prediction engine (Adult Ridge + Pediatric LMS). 277 imputation models per gender. 7-region calibration. NASA-STD-3001 biological limits gate.
Full changelog
The complete changelog with all fixes, architecture decisions, and validation results is published at github.com/D-P0t/dimensionspot-api.