The problem: The validator reports an error you did not expect, or a warning you do not understand, and changing the file blindly risks hiding the real problem.
Schema errors
| What you see | Likely cause | Fix |
|---|---|---|
| Required field missing | The generator omitted a mandatory field, often a version or a bom-ref. | Add the field at the reported path; do not delete the parent object. |
| Wrong type | A number was emitted as a string, or an object where an array is required. | Fix the generator; hand-editing the JSON hides the same bug in the next build. |
| Value not in enum | A scope, hash algorithm or component type uses a value from another spec version. | Use a value from the schema for the declared version. |
| Additional property not allowed | A field from a newer spec version is present under an older declaration. | Either declare the matching version or remove the field. |
| Pattern or format mismatch | A purl, timestamp or serial number does not match the required pattern. | Validate the value against the specification before regenerating. |
Identity and readiness findings
- Missing package identity: no purl and no CPE. Add a real identifier if one exists; otherwise declare the component as a vendor component and record the limit.
- Invalid package identity: the identifier is present but cannot be parsed. Fix the purl type, namespace or version encoding.
- Unsupported ecosystem: the package type has no mapping in the advisory source used for matching. This is common for firmware-specific components and does not mean the component is safe.
- Missing exact version: ranges, hashes, dates and placeholders cannot be matched. Use the exact upstream release the code came from, even if the vendor applied patches.
- Ambiguous identity: two declarations claim the same identity, so matching is discarded. Merge the declarations or make the identities distinct.
Do not invent an identifier to clear the warning
A fabricated purl makes the readiness number look better and the result less true. A limitation that is declared is more useful than a clean report built on invented data.
Dependency and relationship errors
- Broken reference: a dependsOn target or SPDX relationship points at an identifier the document never declares. Add the missing component or correct the reference.
- Self reference: a component depends on itself. Usually a generator bug; remove it unless the specification explicitly allows it.
- Duplicate edge: the same dependency is declared twice. Remove the duplicate; it inflates counts without adding meaning.
- Cycle: components form a dependency loop. Cycles can be legitimate in some graphs; review whether yours is intended rather than deleting it reflexively.
- SPDX documentDescribes points at an unknown SPDXID. Check the package or file identifier, not the document namespace.
Repair in this order
- Fix the generator so the defect does not return on the next build.
- Fix schema errors before quality findings.
- Fix missing or invalid identities before dependency warnings.
- Re-run and compare the counts, not just the pass/fail line.
- If a finding is a real limitation, record it rather than suppressing it.
Scope and limits
- The exact rule names and messages depend on the validator version; this guide groups the defects, not every individual message.
- This is not a substitute for fixing the generator: hand-edited files regress on the next build.