From 758b2cf57f3e7b8eff6e46fe4b6e34828def085c Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Mon, 27 Apr 2026 09:16:20 +0200 Subject: [PATCH 1/5] Clarify non-OTLP representation guidance nested AnyValue --- CHANGELOG.md | 4 ++++ specification/common/README.md | 35 +++++++++++++++++++++------------- 2 files changed, 26 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 348aa2d6d5b..20b25929d3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,10 @@ release. ### Common +- Clarify non-OTLP representation guidance nested `AnyValue` values in arrays + and maps. + ([#TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/#TODO)) + ### OpenTelemetry Protocol ### Compatibility diff --git a/specification/common/README.md b/specification/common/README.md index 282ec85faf5..22c04772b79 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -154,25 +154,34 @@ They SHOULD NOT be encoded as a JSON string (with explicit surrounding quotes). #### Arrays -Arrays, except for byte arrays, SHOULD be represented as JSON arrays. - -Nested byte arrays SHOULD be represented as -[Base64-encoded](https://datatracker.ietf.org/doc/html/rfc4648#section-4) JSON strings. -Nested empty values SHOULD be represented as JSON null. -The special floating point values NaN and Infinity SHOULD be represented as -JSON strings `"NaN"`, `"Infinity"`, and `"-Infinity"`. +Arrays, except for [byte arrays](#byte-arrays), SHOULD be represented as +[JSON arrays](https://datatracker.ietf.org/doc/html/rfc8259#section-5). + +Array elements SHOULD be represented as JSON values using the following rules: + +- [Strings](#strings) as [JSON strings](https://datatracker.ietf.org/doc/html/rfc8259#section-7), +- [Booleans](#booleans) as [JSON booleans](https://datatracker.ietf.org/doc/html/rfc8259#section-3) (`true` or `false`), +- [Integers](#integers) and [floating point numbers](#floating-point-numbers) + as [JSON numbers](https://datatracker.ietf.org/doc/html/rfc8259#section-6), + except that the special floating point values NaN and Infinity SHOULD be + represented as JSON strings `"NaN"`, `"Infinity"`, and `"-Infinity"`, +- [Byte arrays](#byte-arrays) as + [Base64-encoded](https://datatracker.ietf.org/doc/html/rfc4648#section-4) + JSON strings, +- [Empty values](#empty-values) as [JSON `null`](https://datatracker.ietf.org/doc/html/rfc8259#section-6), +- [Arrays](#arrays) as [JSON arrays](https://datatracker.ietf.org/doc/html/rfc8259#section-5), +- [Maps](#maps) as [JSON objects](https://datatracker.ietf.org/doc/html/rfc8259#section-4). Examples: `[]`, `[1, "-Infinity", "a", true, {"nested": "aGVsbG8gd29ybGQ="}]` #### Maps -Maps SHOULD be represented as JSON objects. +Maps SHOULD be represented as [JSON objects](https://datatracker.ietf.org/doc/html/rfc8259#section-4). -Nested byte arrays SHOULD be represented as -[Base64-encoded](https://datatracker.ietf.org/doc/html/rfc4648#section-4) JSON strings. -Nested empty values SHOULD be represented as JSON null. -The special floating point values NaN and Infinity SHOULD be represented as -JSON strings `"NaN"`, `"Infinity"`, and `"-Infinity"`. +Map keys SHOULD be represented as JSON string member names. + +Map values SHOULD be represented using the same rules as +[array elements](#arrays). Examples: `{}`, `{"a": "-Infinity", "b": 2, "c": [3, null]}` From 171a87a6b2613b15b3c69cf071f583efd8fa6de9 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Mon, 27 Apr 2026 09:19:09 +0200 Subject: [PATCH 2/5] add PR number --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 20b25929d3c..00c1a2642d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,7 +33,7 @@ release. - Clarify non-OTLP representation guidance nested `AnyValue` values in arrays and maps. - ([#TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/#TODO)) + ([#5053](https://github.com/open-telemetry/opentelemetry-specification/pull/#5053)) ### OpenTelemetry Protocol From a159f5ee4062e99dd24237d11cbcd17c99ab0f7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 27 Apr 2026 10:14:02 +0200 Subject: [PATCH 3/5] Update specification/common/README.md --- specification/common/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/README.md b/specification/common/README.md index 22c04772b79..8666547b4a3 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -168,7 +168,7 @@ Array elements SHOULD be represented as JSON values using the following rules: - [Byte arrays](#byte-arrays) as [Base64-encoded](https://datatracker.ietf.org/doc/html/rfc4648#section-4) JSON strings, -- [Empty values](#empty-values) as [JSON `null`](https://datatracker.ietf.org/doc/html/rfc8259#section-6), +- [Empty values](#empty-values) as [JSON `null`](https://datatracker.ietf.org/doc/html/rfc8259#section-3), - [Arrays](#arrays) as [JSON arrays](https://datatracker.ietf.org/doc/html/rfc8259#section-5), - [Maps](#maps) as [JSON objects](https://datatracker.ietf.org/doc/html/rfc8259#section-4). From 26ab42a7018b763ac4893805b6d1860e443eec63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 27 Apr 2026 10:14:54 +0200 Subject: [PATCH 4/5] Apply suggestions from code review --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 00c1a2642d5..7e32552375a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,9 +31,9 @@ release. ### Common -- Clarify non-OTLP representation guidance nested `AnyValue` values in arrays +- Clarify non-OTLP representation guidance for nested `AnyValue` values in arrays and maps. - ([#5053](https://github.com/open-telemetry/opentelemetry-specification/pull/#5053)) + ([#5053](https://github.com/open-telemetry/opentelemetry-specification/pull/5053)) ### OpenTelemetry Protocol From e1092a075ac323a97df26ceb70b5d5ab51abddc3 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Mon, 27 Apr 2026 10:15:39 +0200 Subject: [PATCH 5/5] lint --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e32552375a..82e1c00bb2c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,8 +31,8 @@ release. ### Common -- Clarify non-OTLP representation guidance for nested `AnyValue` values in arrays - and maps. +- Clarify non-OTLP representation guidance for nested `AnyValue` values in + arrays and maps. ([#5053](https://github.com/open-telemetry/opentelemetry-specification/pull/5053)) ### OpenTelemetry Protocol