Refactors role-specific properties into entities

[stevespringett]

Implements and closes #718

[Copilot]

Pull request overview

This pull request introduces a new entity schema to CycloneDX 2.0 that refactors role-specific properties into a unified entity structure. The change implements issue #718 by adding new entity types (entity, entityChoice, and entities) along with a comprehensive role taxonomy to the common schema model.

Changes:

• Adds entity object definition with person/organization roles and priority handling
• Introduces predefined and custom role taxonomies covering 27 predefined roles
• Creates entityChoice and entities collection types for flexible entity referencing

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jkowalleck]

"entity" for id, and "Entity" for title - a much too broad term.
please use a more narrow term.

background: every item of a collection is an entity. every banana is an entity of fruit. ...

[jkowalleck]

"role" for id, and "Role" for title - a much too broad term.
please use a more narrow term.

i mean, if we ever have roles for services or something, you would call them "ServiceRoles", right?
Better not use these broad and general terms for things that are pretty narrow in their scope, this prevents extensions in the future and might lead to confusion.

[stevespringett]

The "priority" label may be confusing. Perhaps "sourcingOrder" or just "order"

[stevespringett]

Add additional roles for logistics. Freight forwarder for example.

[stevespringett]

Confirm with @bhess that the CA is captured in CBOM. May want to add certificateAuthority as a role though.

[Mehrn0ush]

Thank you for putting this together — the unified entity/role model feels like a solid direction for reducing duplicated patterns across the schema over time.

I’m not a formal reviewer here, but I wanted to share a few small, hopefully low-impact suggestions that may improve clarity and long-term maintainability (and please ignore any of these if they were already intentional for CycloneDX 2.0):

Definition naming: I see the point raised about $defs ids like entity and role being quite broad within a “common” schema. If you agree, using slightly narrower identifiers (e.g. party/partyRole or relatedEntity/entityRole) might reduce ambiguity as the spec evolves, while keeping the same conceptual model.

Ordering semantics: priority could be interpreted as “importance” rather than “preference ordering”. Renaming to something like preferenceOrder (lower = preferred) or sourcingOrder may communicate intent more directly without changing semantics.

Minor hardening: it might be worth adding uniqueItems: true to the roles array to avoid duplicate role values and improve cross-tool consistency.

Reference target clarity: since entityChoice allows references via refLinkType, and JSON Schema can be limited in expressing strict “target types”, an explicit note that references are intended to target an entity / organizationalContact / organizationalEntity (and that validators MAY warn otherwise) could help implementers.

Person vs org readability: the oneOf already enforces this nicely; adding a short sentence like “Exactly one of person or organization MUST be present” might help consumers reading the schema/description.

Again, these are just small polish items — the overall structure looks promising, and I appreciate the RFC-style approach here.