Skip to content

Add Entity Type Uniqueness and Attribute Ownership restrictions #4697

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
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add Entity Type Uniqueness and Attribute Ownership restrictions #4697

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
faead7f
Add Entity Type Uniqueness and Attribute Ownership restrictions
dmitryax Oct 20, 2025
7e7864b
Add an implementation note
dmitryax Oct 23, 2025
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
35 changes: 30 additions & 5 deletions specification/entities/data-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ weight: 2
- [Identifying Attributes](#identifying-attributes)
- [Resource and Entities](#resource-and-entities)
* [Attribute Referencing Model](#attribute-referencing-model)
* [Entity Type Uniqueness](#entity-type-uniqueness)
* [Attribute Ownership](#attribute-ownership)
* [Placement of Shared Descriptive Attributes](#placement-of-shared-descriptive-attributes)
- [Examples of Entities](#examples-of-entities)

Expand Down Expand Up @@ -127,17 +129,40 @@ entities. The model provides:
- The ability to avoid data duplication and inconsistencies.
- A more efficient representation for encoding and transmission.

### Entity Type Uniqueness

All entities associated with a resource MUST have unique types. No two entities
within the same resource can share the same entity type.

This ensures unambiguous identification when referencing entities within a
resource. Combined with the convention that identifying attributes use the
entity type as a prefix (e.g., `host.id` for `host` entity, `k8s.node.uid` for
`k8s.node` entity), this guarantees that identifying attributes from different
entities will never share the same keys in the resource attributes map.

### Attribute Ownership

Each resource attribute key MUST be owned by at most one entity within a
resource. When an entity adds an attribute to the shared resource attributes
map, no other entity in that resource can reference or modify that same
attribute key. This prevents data inconsistencies where multiple entities could
otherwise compete for control of the same attribute.

For identifying attributes, ownership is implicitly enforced by the combination
of entity type uniqueness and the prefix naming convention. For descriptive
Copy link
Contributor

@jsuereth jsuereth Oct 22, 2025

Choose a reason for hiding this comment

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

I'm skeptical of relying on naming conventions here. I think we likely need something to describe what to do if folks fail to use our naming conventions going forward (it will happen, so we should make sure we don't get invalid Resources when it does, if we can help it.

In light of how other SDK/model behavior is - we should call out that this would be an error scenario in the model - and we'll be recommending SDKs have some kind of "error log + fallback" behavior.

Copy link
Member Author

@dmitryax dmitryax Oct 23, 2025

Choose a reason for hiding this comment

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

Good point. I've added an Implementation Note to address validation and fallback strategies with given data model restrictions. Since this document isn't intended to provide SDK guidance as far as I understand, I kept it as a note rather than normative requirements.

On the naming convention strictness - the current semantic conventions already follow this pattern (host.id, k8s.node.uid, etc.). I'd prefer keeping the stricter requirement until we encounter concrete cases that break it during semantic convention development.

attributes, ownership is determined by the placement rules described in the
following section.

### Placement of Shared Descriptive Attributes

Attribute flattening allows multiple entities to reference the same attribute key,
but with different values across the entities. In such situations, the following
rule applies:

If multiple entities share the same descriptive attribute key with potentially
conflicting values, the attribute MUST logically belong to **only one** of them.
All others SHOULD NOT reference it. The attribute MUST be referenced by the
**most specific** entity, the one closest in the topology graph to the entity
associated with the telemetry signal.
If multiple entities share the same descriptive attribute key, the attribute
MUST logically belong to **only one** of them. All others SHOULD NOT reference
it. The attribute MUST be referenced by the **most specific** entity, the one
closest in the topology graph to the entity associated with the telemetry signal.

**Example:**

Expand Down
Loading