CycloneDX 2.0 - Modularize the specification into multiple schemas

[stevespringett]

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, 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.

---