Version Health States

Every ingested version carries a health record: one status per data component, plus an overall verdict. It is what the health banner in the web UI reads, and it is available directly on

GET .../projects/{projectId}/versions/{versionId}/health

This page explains what each state means – in particular the one that is routinely misread: a version whose build shipped no schema-validation report.

Components and states

Four components are reported per version:

  • Needs – the requirement graph itself, from docs/ubtrace/needs.json.

  • Coverage – the traceability coverage computed at ingest.

  • Schema violations – from the optional reports/schema_violations.json.

  • ASPICE readiness – from the project’s ASPICE configuration, when one exists.

Each is in exactly one of four states:

State

Meaning

loaded

The component’s data was ingested and is queryable.

missing

No data for this component. This is not, on its own, a fault – see below.

error

The component’s data could not be read back. This is a fault: it means ubTrace failed to answer the question, not that the answer is “nothing”.

not_applicable

The component does not apply to this project, so its absence is expected and counts as healthy. Currently used for ASPICE readiness in a project with no ASPICE configuration.

“Schema violations: missing” is a supported state

reports/schema_violations.json is optional. Every description of the version layout says so: the tree in Installation marks it # optional, as do the input_build/README.md, DOCKER.md and README-offline.md copies shipped with your deployment. A documentation build that does not run Sphinx-Needs schema validation simply does not produce the file, and uploading such a build is a fully supported setup, not a broken one.

So when the schema-violations component reports missing:

  • it does not mean the ingest failed – the version’s needs, documents and coverage are loaded and queryable exactly as usual;

  • it does not mean the version passed schema validation. Nothing was validated. ubTrace deliberately refuses to render “no report” as a green pass, because this report is read as compliance evidence and absence of evidence is not evidence of absence;

  • it means: this version’s build shipped no schema-validation report.

Read it as unknown, and expect it to stay that way for as long as your build does not emit the report.

Making the report appear

Nothing in ubTrace turns this on – it is produced upstream, by your documentation build:

  1. Configure Sphinx-Needs schema validation in your documentation project, so the build writes schema_violations.json.

  2. Place it at reports/schema_violations.json inside the version bundle (the path in every layout on this site).

  3. Re-upload the version (or re-drop it into input_build/). The report is read on every ingest, so re-uploading an existing bundle is enough.

A report that arrives late is picked up on its own

Copying a version into input_build/ is not an atomic operation: an rsync or a CI copy can be observed by the scanner after needs.json has landed but before reports/ has. Such a version used to ingest without its report and keep reporting missing forever, even though the file was sitting right there on disk.

That no longer happens. The worker reconciles the report against the ingested data on a later scan and re-ingests the version by itself, once, when it finds a report on disk that never made it into the database.

The practical consequence for a reader: a ``missing`` state that persists is a genuine absence. It means the build shipped no report – not that a copy was caught half-finished.

When it is a fault

Two states on this component do warrant attention:

  • error – the data exists but could not be read back. Check the server logs and the version’s last ingestion activity.

  • loaded with counts that do not match your build – re-upload the version so the report is re-read.