Cyclonedx Spec Reviewer

CycloneDX specification reviewer

Use this skill when a pull request changes CycloneDX output, schema handling, validators, package-manager integrations, BOM enrichment, or custom properties.

Sources of truth

Review in this order:

1. Local schemas in data/bom-1.5.schema.json, data/bom-1.6.schema.json, data/bom-1.7.schema.json
2. Other local schemas when relevant, especially data/cyclonedx-2.0-bundled.schema.json
3. Official CycloneDX documentation and property-taxonomy guidance

JSON-schema validity is only the starting point. Also review semantic correctness.

AI-BOM focus areas

When a change introduces AI-BOM, model inventory, prompt/config discovery, or agent/MCP inventory, explicitly review the standard AI/ML fields already present in CycloneDX 1.5, 1.6, 1.7, and 2.0.

• formulation
• pedigree
• modelCard
• data components and componentData
• services
• evidence
• externalReferences

Treat AI-BOM as CycloneDX-first modeling, not as permission to shift standard semantics into custom properties.

What to check

1. Prefer standard fields over custom properties

Flag a change when it introduces or preserves a custom property for data that already fits a standard field such as:

• supplier, manufacturer, authors, publisher
• externalReferences
• evidence.identity
• evidence.occurrences
• pedigree
• hashes
• licenses
• scope
• properties registered in public taxonomy when applicable

If a custom property is still necessary, require a clear namespace and a narrow purpose.

2. Reject ambiguous or risky custom properties

Flag custom properties that are:

• unnamespaced
• duplicates of existing CycloneDX fields
• host-specific or non-reproducible
• likely to leak local paths, usernames, secrets, or environment-specific details
• packing structured data into comma-delimited strings when a structured field exists
• likely to confuse downstream consumers about meaning

3. Check semantic field use

Review whether attributes are used for the right purpose:

• manufacturer for the entity that created the component
• supplier for the entity that supplied or distributed it
• authors for people, not organizations
• deprecated author only as a compatibility holdover and preferably not in new output
• publisher only when publication semantics are actually intended
• externalReferences[].type matches the URL purpose
• scope is semantically correct for required, optional, excluded, or runtime-only style data
• bom-ref values are unique and resolvable

4. Check new ecosystem/package-manager integrations

When a PR adds or changes ecosystem support, check whether emitted components and services are missing expected data that cdxgen can usually infer:

• stable bom-ref
• type, name, version
• purl when a native package identity exists
• dependency edges
• hashes when resolved artifacts or lockfile integrity data are available
• licenses when manifest or registry metadata provides them
• externalReferences for distribution or VCS when directly available
• evidence fields when provenance or file-location evidence is collected

Flag missing data as a gap when the source material is already available to the integration.

5. Check AI-BOM and AI/ML modeling

Review whether AI-related output uses the standard CycloneDX AI/ML structures correctly:

• formulation should describe how something was created, trained, assembled, deployed, or otherwise brought into its current form. Do not treat it as a generic dumping ground for unrelated inventory.
• formulation.workflows, tasks, and steps should represent real process information. If the PR only discovered runtime usage or file-level evidence, verify that this is not being overstated as build/training lineage.
• machine-learning-model components should prefer modelCard for task, architecture, datasets, and metrics.
• training or evaluation datasets should prefer modelCard.modelParameters.datasets, ideally via ref to stable type: data components when the BOM already has a stable dataset identity.
• model lineage such as fine-tunes, distillations, adapters, merges, and quantized derivatives should prefer pedigree.ancestors, pedigree.variants, commits, or patches. Notes may supplement this but should not be the only place where lineage is captured when a structured relation is known.
• inference endpoints belong in services, not components.
• prompt files, agent instructions, model config files, and notebooks are usually best represented as file components plus evidence, unless the spec clearly supports a richer standard structure.
• component.data must only be present for type: data components.
• component.modelCard should only be present for type: machine-learning-model.
• service evidence and any 2.0-only structures must be reviewed for spec-version downgrade behavior so that 1.5/1.6/1.7 output does not silently become semantically misleading.

Also review AI-specific custom properties carefully. A namespaced property is still a finding if it duplicates a standard field that now exists in the schema.