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]

"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]

Title changed

[jkowalleck]

then the name should also change to "organizationOrPersonRole"

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

[stevespringett]

cc: @bhess

[Mehrn0ush]

Hi @stevespringett — quick follow-ups (low-impact), in case you think they’re worth folding in:

1. Prevent enum/meta drift
   Now that the role taxonomy is growing, it might be worth adding a lightweight consistency check (either a CI step or a small script that CI can call) to ensure role.enum and meta:enum stay in sync—i.e., every enum value has a corresponding meta:enum description, and there are no extra meta:enum keys not present in enum. This helps prevent accidental omissions and keeps schema-driven docs/tooling consistent as the list evolves.

2. Minor hardening for custom roles
   Consider adding minLength: 1 for custom role.name (and optionally a short note discouraging whitespace-only values). In practice, empty/blank role names can slip through generators and produce confusing downstream diffs; a minimal constraint improves data quality and cross-tool consistency without changing the model.

3. Naming/wording consistency for order
   Tiny consistency nit (similar to the recent title/description polish in this PR): the property is now order, but the title/wording still uses “Priority” in a few places. Since schema-driven UI/docs often surface title as the field label, this mixed terminology can confuse implementers (and may leak into spec-text wording later). If the intent is preference ordering, aligning the title/description terminology with order (or “preference order”) would make the semantics and migration clearer.

[stevespringett]

@Mehrn0ush

Prevent enum/meta drift

Good point. We've created our own linter for CycloneDX 2.0, which I believe handles this case. We still need to hook it up into a build process, but the framework should be there.
https://github.com/CycloneDX/specification/blob/2.0-dev/tools/src/main/js/linter/checks/enum-value-formatting.check.js

Minor hardening for custom roles

I don't think we have a linter check for this today and I know we've had an issue or two where this has come up, allowing someone to simply use "" and it satisfies the required check, which defeats the purpose. The specific occurrence of this has now been corrected.

Naming/wording consistency for order

Thanks for catching this. This has been corrected.

[jkowalleck]

i still dont like the wording "entity".
an entity of what? better name: "organizationOrPerson"

[Mehrn0ush]

The term entity is used here as a domain-level abstraction representing an identifiable actor within CycloneDX.

Although the current oneOf constrains implementations to organization/person, this reflects the present schema scope rather than the conceptual boundary of the model.

Encoding concrete types directly into the primitive name (e.g. organizationOrPerson) tightly couples the abstraction to today’s variants and reduces extensibility for future actor classes (such as services, signing authorities, or automated agents).

Keeping entity generic aligns with standard domain modeling practice: define a stable abstract actor, then specialize via schema composition. This avoids introducing parallel actor constructs as the specification evolves.

[Mehrn0ush]

role models the contextual function an entity assumes (e.g. supplier, manufacturer, operator), not an intrinsic attribute of organization/person.

The structural relationship is:

entity → roles[]

This follows established actor/role modeling patterns (RBAC / domain-driven design), where actors remain generic and roles express situational responsibility.

Renaming to organizationOrPersonRole couples role semantics to specific actor variants and limits reuse if additional entity types are introduced later.

Keeping role generic preserves a clean separation between actor identity and functional responsibility, and prevents fragmentation of role taxonomies across future entity categories.

[jkowalleck]

then the name should also change to "organizationOrPersonRole"