[entities] Attribute field names inconsistency

[dmitryax]

What are you trying to achieve?

Establish consistent naming for entity attribute fields. This issue originates from this discussion.

What did you expect to see?

Consistent terminology across the proto definitions, semantic conventions, and documentation.

Additional context

There is an inconsistency in how entity attribute key fields are named:

Description vs Descriptive

• The proto definition uses description_keys.
• The semantic conventions refer to them as Descriptive Attributes.

ID vs Identity vs Identifying

• Identity has not been used so far.
• The proto defines the field as id_keys, while the documentation refers to them as Identifying.
• Using both ID and Identifying might be acceptable, but this naming is not consistent with how we handle the Description terminology since Description is a noun, the equivalent pattern would suggest using Identity (also a noun), rather than Identifying (an adjective/participle).

The Collector Go API currently aligns with the proto naming but could still be changed since it’s not yet in use.

---

Proposed options for consistency

1. Use “Descriptive” and “Identifying/ID” everywhere
   → Rename the proto field from description_keys to descriptive_keys and update related docs.

2. Use “Description” and “Identity/ID” everywhere
   → Keep the current proto naming but update all documentation accordingly.

---

_{Tip: React with 👍 to help prioritize this issue. Please use comments to add useful context (avoid +1 or me too) to help with triage. Learn more here.}

[danielgblanco]

@open-telemetry/entities-maintainers I've moved this into your project for Phase 1. Please adjust if that's not the intention.

[dmitryax]

This was discussed during the Entities SIG call. The decision was that we should use the terms Entity Identity (or ID) and Entity Description.

When referring to Entity attributes or keys, the following forms are preferred:

• Attributes of Entity Identity
• Attributes of Entity Description
• Keys of Entity Identity
• Keys of Entity Description
• Entity Identity Attributes (or Identity Attributes)
• Entity Identity Keys (or Identity Keys)
• Entity Description Attributes (or Description Attributes)
• Entity Description Keys (or Description Keys)

Identifying Attributes and Descriptive Attributes are allowed but discouraged.

@jsuereth please correct me if needed