Recommend JSON object encoding of an attribute for non-OTLP

[pellared]

What

Adds in-development guidance for representing a single OpenTelemetry attribute as a string in non-OTLP or debugging contexts.

The recommended form is a single-entry JSON object, for example:

{"http.request.method":"GET"}

Implementation:

• [DO NOT MERGE] attribute: add String method for KeyValue opentelemetry-go#8205

Why

• Support String() method on attribute.Value and attribute.KeyValue opentelemetry-go#7810

I originally thought about key:value (and even key=value beforehand), but it is ambiguous when : appears in keys or string values and is not a robust debugging representation.

Using a JSON object improves clarity for debugging output by:

• avoiding delimiter ambiguity
• aligning with existing JSON-based guidance for complex AnyValue types
• making the representation easier to read, copy, and process when needed

This also is consistent with how OTel Java, .NET, Python, Go are representing attributes in standard output exporters. Therefore, I think it would be most familiar representation for the users.

Notable conversations:

• Recommend JSON object encoding of an attribute for non-OTLP #5028 (comment)
• Recommend JSON object encoding of an attribute for non-OTLP #5028 (comment)

[jack-berg]

non-OTLP or debugging contexts.

Can you clarify what this applies to? I can think of a couple of potential candidates:

• Zipkin and other non-OTLP exporters which need to encode AnyValue types
• Console exporter which writes to console/stout in an unspecified format
• Generic "toString" representation called when you invoke printf or equivalent

Is this what you had in mind? Any other contexts you know of at the moment?

[pellared]

@jack-berg, mostly

Generic "toString" representation called when you invoke printf or equivalent

I thought that maybe some exporters may need a representation of a single attribute (we already have a defintion how to encode a map of AnyValue which is equivalent to a collection of attributes). This is why I decided to also include "For non-OTLP protocols".

[bogdandrutu]

For "float64/int64" can you link to an RFC that needs to be followed? I know at least 2 ways of doing this, some use string to represent them (as proto) or others number.

[bogdandrutu]

Preventing the argument:

Ship has sailed. This is already stable for non-OTLP represnetation of AnyValue. See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#anyvalue-representation-for-non-otlp-protocols. It does not make sense to do it differently here.

Yes AnyValue was stabilized with that definition (which by the industry standard is less than ideal), but the argument can be made that since this is debugging and it cannot be read anyway by other systems better to do the right thing, and maybe reconsider the AnyValue representation since it is not readable by other systems (hence is a bug).

[pellared]

Thanks, I think the concern is reasonable. There are multiple possible encodings here, and the existing non-OTLP AnyValue representation has tradeoffs, especially around numeric precision and lossless round-tripping.

However, for this PR I think we should keep the single-attribute representation aligned with the existing AnyValue representation. Using a different encoding for an Attribute value than for the same value inside map<string, AnyValue> would be awkward and arguably incompatible within the same domain model.

I updated the wording to avoid re-defining the value encoding rules here and instead refer to the existing “AnyValue representation for non-OTLP protocols” section. dccd5bb

I also created #5053 to refine the existing “AnyValue representation for non-OTLP protocols” section

If we want to address the broader concern, I think that should probably be a separate proposal for a revised/v2 non-OTLP representation. Since this is recommendation-level guidance, that proposal could potentially define two recommended representations and spell out the tradeoffs, for example compact/readable output versus a more explicit representation that preserves type information better. It is also worth noting that currently there is non public issue complaining that the non-OTLP representation is lossy (or at least I failed to find one). Also it looks like it was a conscious decision: #4848.

[bogdandrutu]

However, for this PR I think we should keep the single-attribute representation aligned with the existing AnyValue representation. Using a different encoding for an Attribute value than for the same value inside map<string, AnyValue> would be awkward and arguably incompatible within the same domain model.

I am worried about this, why not consistent with the OTLP Json representation? Same question for the AnyValue?

[bogdandrutu]

@pellared I don't see anywhere in the reference you pointed why did we decide to be inconsistent from OTLP JSON representation.

[pellared]

See #4848 (comment)

[Copilot]

Pull request overview

Adds specification guidance for a consistent, unambiguous string representation of a single OpenTelemetry attribute in non-OTLP/debugging contexts, recommending a single-entry JSON object form.

Changes:

• Add a new “Attribute representation for non-OTLP” section describing a single-entry JSON object encoding aligned with existing AnyValue non-OTLP encoding guidance.
• Add an Unreleased changelog entry documenting the new in-development guidance.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
specification/common/README.md	Introduces the new guidance section and examples for JSON-object attribute encoding in non-OTLP/debugging contexts.
CHANGELOG.md	Adds an Unreleased “Common” entry describing the new guidance.

---

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