Repository navigation
[REFACTOR]: Role-based organizationalEntities (manufacturers, suppliers, etc) into extensible objects #718
Description
A lot of discussion in the HBOM working group about different types of roles an entity may play, and which need to be captured in an HBOM.
Based on these discussions, the idea is to replace the dedicated "manufacturer", "supplier" and similar properties that take on a role, with a generic "entities" property which supports both organizationalEntity and organizationalContact along with a "role" property.
Much like the lifecycles objects, you can use the enums or can define your own.
Activity
stevespringett commentedon Jan 15, 2026
Proposed Change: Unified Entity-Role System
Summary
This proposal introduces a unified
entitiesarray to replace the various scattered role-specific properties throughout the CycloneDX specification (e.g.authors,manufacturer,supplier,custodians,stewards,owners,licensor,licensee,purchaser, etc.).Each entity:
bom-ref) to a previously defined entityPredefined Roles (27)
assembler,author,manufacturer,supplier,distributor,repackager,publisher,maintainer,contributor,licensor,licensee,purchaser,owner,custodian,steward,asserter,reviewer,annotator,signatory,committer,auditor,integrator,operator,qualityControl,securityContact,supportContact,legalContactCustom roles may also be defined using a name and description.
Usage
The
entitiesarray replaces every instance that relies upon role-specific properties today (e.g.authors,manufacturer,supplier,custodians,stewards,owners, etc.) throughout the specification.Benefits
Example
{ "$schema": "https://cyclonedx.org/schema/bom-2.0.schema.json", "specFormat": "CycloneDX", "specVersion": "2.0", "version": 1, "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79", "metadata": { "timestamp": "2025-01-15T10:30:00Z", "entities": [ { "bom-ref": "entity-bom-author", "person": { "bom-ref": "person-alice", "name": "Alice Example", "email": "alice.example@example.com", "phone": "800-555-1212" }, "roles": ["author"] }, { "bom-ref": "entity-bom-manufacturer", "organization": { "bom-ref": "org-acme", "name": "Acme Inc", "url": ["https://www.example.com"] }, "roles": ["manufacturer"] } ] }, "components": [ { "type": "device", "bom-ref": "component-sensor-module", "name": "AcmeSense 3000", "version": "2.1.0", "description": "Multi-spectrum environmental sensor module with integrated signal processing unit.", "entities": [ { "bom-ref": "entity-component-manufacturer", "organization": { "bom-ref": "org-acme-hardware", "name": "Acme Hardware Division", "url": ["https://hardware.example.com"] }, "roles": ["manufacturer", "assembler"] }, { "bom-ref": "entity-component-supplier-primary", "organization": { "bom-ref": "org-widgets-supply", "name": "Widgets Supply Co", "url": ["https://widgets-supply.example.net"], "contact": [ { "name": "Sales Department", "email": "sales@widgets-supply.example.net", "phone": "800-555-2424" } ] }, "roles": ["supplier"], "priority": 1 }, { "bom-ref": "entity-component-supplier-secondary", "organization": { "bom-ref": "org-globalparts", "name": "GlobalParts International", "url": ["https://globalparts.example.org"], "contact": [ { "name": "Customer Service", "email": "orders@globalparts.example.org", "phone": "800-555-3636" } ] }, "roles": ["supplier"], "priority": 2 } ] } ] }Example Walkthrough
Metadata Section
The
metadata.entitiesarray defines two entities associated with the BOM itself:Alice Example (Person)
authorAcme Inc (Organization)
manufacturerComponents Section
The example includes a single hardware component, a sensor module, with its own
entitiesarray defining three parties:Acme Hardware Division (Organization)
manufacturer,assemblerWidgets Supply Co (Organization)
supplier1(primary)GlobalParts International (Organization)
supplier2(secondary)Priority in Practice
The
priorityproperty establishes preference order among entities sharing the same role. In this example:This pattern is common in hardware supply chains where procurement teams maintain approved vendor lists with primary and alternate sources. Lower priority values indicate higher preference.
Draft PR is #776 currently containing only the entities definition in the common schema.
Note: If this proposal is accepted, work on refactoring the schema to implement the unified entity-role system will commence. No further schema changes will be made prior to acceptance.
stevespringett commentedon Feb 5, 2026
cc: @bhess
stevespringett commentedon May 14, 2026
The proposed example outlined in this ticket (#718 (comment)) is obsolete and was rejected by TC54. Please refer to #930 for the new design, which is much more extensible, is unified, and addresses the requirements outlined in this ticket, while also providing an abstract capability useful in threat modeling and use case development. It also addresses the concerns raised by TC54.
jkowalleck commentedon May 15, 2026
RFC notice sent on May 15, 2026
Public RFC period ends June 12, 2026
Initial commit of the party model and test cases. (#930)