CycloneDX / CycloneDX/specification

CycloneDX 2.0 - Modularize the specification into multiple schemas

Open
#636 0 comments 0 reactions 1 assignee Claimed by @stevespringett View on GitHub
breaking-changes proposed core enhancement
Dominant language
XSLT
Stars
547
Forks
93
Avg merge
7h 11m
Merged PRs (30d)
37

Description

## Proposal: Modularization of the CycloneDX JSON Schema

To improve maintainability and promote reuse across the CycloneDX specification, this proposal introduces a modular schema structure. The schema will be decomposed into individual files aligned with top-level BOM fields and high-composability objects.

### Proposed Modules

- `cyclonedx-annotation-2.0.schema.json`
- `cyclonedx-api-2.0.schema.json`
- `cyclonedx-bom-2.0.schema.json`
- `cyclonedx-common-2.0.schema.json`
- `cyclonedx-component-2.0.schema.json`
- `cyclonedx-composition-2.0.schema.json`
- `cyclonedx-declarations-2.0.schema.json`
- `cyclonedx-definitions-2.0.schema.json`
- `cyclonedx-dependency-2.0.schema.json`
- `cyclonedx-formulation-2.0.schema.json`
- `cyclonedx-license-2.0.schema.json`
- `cyclonedx-metadata-2.0.schema.json`
- `cyclonedx-service-2.0.schema.json`
- `cyclonedx-vulnerability-2.0.schema.json`

### Structural Principles

- `bom` and `api` modules define BOM file and API contexts, respectively.
- `common` contains reusable objects like `OrganizationalEntity` and `ExternalReferences`.

A GitHub workflow will be introduced to compile these modular schemas into a single monolithic schema using [AJV](https://ajv.js.org/), enabling `$ref` resolution and schema validation.

---

## Benefits of Individual Schemas

### Selective Adoption

Users can adopt only the schemas they need, e.g., `component`, `license`, or `declarations`, without requiring the entire BOM structure. This supports domain-specific tooling and integration.

### Improved Maintainability

Smaller files mean easier updates, reviews, and debugging. Isolated changes reduce risk and improve version control granularity.

### Enhanced Reusability

Common elements can be reused across schemas and even integrated into external ecosystems.

### Supports APIs and Partial Payloads

APIs can validate and serve partial BOM fragments (e.g., only `metadata` or `vulnerabilities`) without relying on the full schema.

---

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.