Skip to content

Refactors role-specific properties into entities #776

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stevespringett wants to merge 4 commits into
base: 2.0-dev
Choose a base branch
from
Open

Refactors role-specific properties into entities #776

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
affbb5d
Initial commit of entities
stevespringett Jan 15, 2026
8dbb7e4
Clarified titles. Added a few additional roles based on HBOM and CBOM…
stevespringett Feb 10, 2026
2d3d75b
Added uniqueItems and description clarity
stevespringett Feb 10, 2026
5718c07
Corrected description of order. Added minLength constraint to name pr…
stevespringett Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 158 additions & 0 deletions schema/2.0/model/cyclonedx-common-2.0.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -407,6 +407,164 @@
},
"organizationalEntityOrContact": {

},
"entity": {
Copy link
Copy Markdown
Member

@jkowalleck jkowalleck Feb 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

@Mehrn0ush Mehrn0ush Feb 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

@Mehrn0ush Mehrn0ush Feb 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

@stevespringett stevespringett Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

That is precisely what the term "entity" was chosen. We've had a number of discussions in the threat modeling working group about different types of entities in the future.

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

Perhaps change the name from "entity" to "actor"? We have this same concept in the threat model schema I believe, but it really needs to be a common object as its going to be reused everywhere.

"type": "object",
"title": "Entity",
Comment thread
stevespringett marked this conversation as resolved.
Outdated
"description": "Represents a person or organization with one or more roles in relation to the subject. Entities provide a unified mechanism for expressing the various parties involved in the creation, distribution, governance, and lifecycle management of components, services, data, and other objects within the BOM.",
"required": ["roles"],
"additionalProperties": false,
"properties": {
"bom-ref": {
"$ref": "#/$defs/refType"
},
"person": {
"title": "Person",
"description": "An individual acting in the specified role(s). Use this property when the entity is a natural person rather than an organization.",
"$ref": "#/$defs/organizationalContact"
},
"organization": {
"title": "Organization",
"description": "An organizational entity acting in the specified role(s). Use this property when the entity is an organization, company, department, or other collective body.",
"$ref": "#/$defs/organizationalEntity"
},
"roles": {
"type": "array",
"title": "Roles",
"description": "The role(s) that the entity fulfils. At least one role shall be specified. Multiple roles may be assigned to represent the various capacities in which the entity operates.",
"minItems": 1,
"items": {
"$ref": "#/$defs/role"
}
},
"priority": {
Comment thread
stevespringett marked this conversation as resolved.
Outdated
"type": "integer",
"title": "Priority",
"description": "The priority order of this entity relative to other entities with the same role(s). Lower values indicate higher priority. When multiple entities share the same role, priority establishes the preference order. For example, in hardware supply chains, a priority of 1 may indicate the primary supplier, whilst 2 and 3 may indicate first and second alternates respectively. If not specified, no priority order is implied.",
"minimum": 1,
"examples": [1, 2, 3]
}
},
"oneOf": [
{
"required": ["person"]
},
{
"required": ["organization"]
}
]
},
"role": {
Copy link
Copy Markdown
Member

@jkowalleck jkowalleck Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member Author

@stevespringett stevespringett Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Title changed

Copy link
Copy Markdown
Member

@jkowalleck jkowalleck Feb 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

then the name should also change to "organizationOrPersonRole"

"title": "Role",
"description": "A role that an entity fulfils. May be a predefined role from the CycloneDX taxonomy or a custom role definition.",
"oneOf": [
{
"type": "string",
"title": "Predefined Role",
"description": "A predefined role from the CycloneDX role taxonomy.",
"enum": [
"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",
"legalContact"
],
Comment thread
stevespringett marked this conversation as resolved.
"meta:enum": {
"assembler": "The entity that assembles or integrates constituent parts into the subject. Assemblers are common in hardware manufacturing but may also apply to software build and packaging processes.",
"author": "The entity that created the subject. Authors are common in entities created through manual processes.",
"manufacturer": "The entity that manufactured or produced the subject. Manufacturers are common in entities created through automated processes.",
"supplier": "The entity that supplied the subject. The supplier may often be the manufacturer, but may also be a distributor or repackager.",
"distributor": "The entity that distributes the subject to downstream consumers or customers.",
"repackager": "The entity that repackages the subject, potentially combining it with other components or modifying its packaging for redistribution.",
"publisher": "The entity that published the subject, making it available for public or private consumption.",
"maintainer": "The entity responsible for ongoing maintenance, including updates, patches, and security fixes.",
"contributor": "An entity that contributed to the development of the subject without being the primary author.",
"licensor": "The entity that grants a licence for the subject.",
"licensee": "The entity to which a licence for the subject has been granted.",
"purchaser": "The entity that purchased the subject or a licence for its use.",
"owner": "The entity that holds ownership rights over the subject, including responsibility for risk management and access control.",
"custodian": "The entity responsible for the safe custody, transport, and storage of the subject.",
"steward": "The entity responsible for the content, context, and associated business rules of the subject.",
"asserter": "The entity making assertions about the subject, such as patent ownership or compliance claims.",
"reviewer": "The entity that reviewed the subject or its associated evidence.",
"annotator": "The entity, component, or service that created annotations or supplementary information about the subject.",
"signatory": "The entity authorised to sign on behalf of an organization, affirming the validity or accuracy of documentation.",
"committer": "The entity who committed or pushed changes to a version control system.",
"auditor": "The entity that conducted an audit or assessment of the subject.",
"integrator": "The entity that integrates the subject into a larger system or product.",
"operator": "The entity responsible for operating or running the subject in a production environment.",
"qualityControl": "The entity responsible for quality control activities, including inspection, testing, and verification to ensure the subject meets specified requirements and standards. Quality control is common in hardware manufacturing but may also apply to software testing and release processes.",
"securityContact": "The designated entity to contact in the event of a security incident.",
"supportContact": "The designated entity to contact for technical support.",
"legalContact": "The designated entity to contact for legal matters."
}
},
{
"type": "object",
"title": "Custom Role",
"description": "A custom role not covered by the predefined taxonomy. Use this structure to define domain-specific or organization-specific roles.",
"required": ["name"],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"title": "Role Name",
"description": "The name of the custom role. Use a concise, descriptive identifier.",
"examples": ["Chief Executive Officer", "Data Protection Officer", "Release Manager"]
},
"description": {
"type": "string",
"title": "Role Description",
"description": "A description of the custom role, including its responsibilities and scope."
}
}
}
]
},
"entityChoice": {
"title": "Entity Choice",
"description": "An entity represented either as a complete object or as a reference to a previously defined entity or other referenceable object within the BOM.",
"oneOf": [
{
"$ref": "#/$defs/entity",
"title": "Entity"
},
{
"$ref": "#/$defs/refLinkType",
"title": "Reference",
"description": "A reference to a previously defined entity, `organizationalContact`, or `organizationalEntity` object in the BOM. The value shall be a valid `bom-ref` pointing to one of these objects."
}
]
},
"entities": {
"type": "array",
"title": "Entities",
"description": "A collection of persons and organizations with defined roles in relation to the subject. Each item may be a complete entity object or a reference to a previously defined entity or other referenceable object within the BOM.",
"items": {
"$ref": "#/$defs/entityChoice"
}
},
"properties": {
"type": "array",
Expand Down