From d46e352809e03a85600c35ba407d8b0ad8b57f36 Mon Sep 17 00:00:00 2001
From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
Date: Tue, 10 Nov 2020 15:51:16 -0500
Subject: [PATCH] Add guidance on when to use and not use nested namespaces
 (#1197)

This topic has come up at least 3 times now. I believe a clarification is
warranted. The clarification is aligned with previous recommendations:
https://github.com/open-telemetry/opentelemetry-specification/pull/789#issuecomment-675506855
https://github.com/open-telemetry/opentelemetry-specification/pull/882#issuecomment-690945900
https://github.com/open-telemetry/opentelemetry-specification/pull/1194#issuecomment-722431982
---
 specification/common/common.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/specification/common/common.md b/specification/common/common.md
index 3a759e09e0..15d25304c4 100644
--- a/specification/common/common.md
+++ b/specification/common/common.md
@@ -63,6 +63,10 @@ Names SHOULD follow these rules:
 - Namespaces can be nested. For example `telemetry.sdk` is a namespace inside
   top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute
   inside `telemetry.sdk` namespace.
+  Note: the fact that an entity is located within another entity is typically
+  not a sufficient reason for forming nested namespaces. The purpose of a
+  namespace is to avoid name clashes, not to indicate entity hierarchies. This
+  purpose should primarily drive the decision about forming nested namespaces.
 
 - For each multi-word dot-delimited component of the attribute name separate the
   words by underscores (i.e. use snake_case). For example `http.status_code`