Skip to content

Commit 8545878

Browse files
committed
add reverse domain name recommendation for private / experimental namespaces
1 parent 5b8c98f commit 8545878

File tree

1 file changed

+19
-4
lines changed

1 file changed

+19
-4
lines changed

docs/reference/code/namespaces.md

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,14 @@ use only.
115115

116116
The SSVC project does not manage namespaces with the `x_` prefix, so
117117
collisions may occur across organizations who develop their own private SSVC
118-
namespaces.
118+
namespaces.
119+
120+
!!! warning "Reverse domain name notation recommended"
121+
122+
We strongly recommend using reverse domain name notation for private namespaces to
123+
avoid conflicts with other users' private namespaces. This helps to ensure
124+
that your private namespaces are unique and easily identifiable.
125+
E.g., `x_org.cert-experimental` for an experimental namespace within the CERT organization.
119126

120127
!!! example "OT Monitoring Service (OTMS) Private Namespace"
121128

@@ -137,9 +144,15 @@ namespaces.
137144

138145
!!! tip "Private vs Extension Namespaces"
139146

140-
Private namespaces are intended for internal use only and are not registered
141-
with the SSVC project. They are not intended to be shared or used outside of
142-
the organization that created them. In contrast, extension namespaces are
147+
Private namespaces are intended for use within a closed scope
148+
and are not registered with the SSVC project.
149+
In other words, they are not intended to be used outside of a
150+
specific constuency.
151+
For example, an organization might create a private namespace for
152+
decision points that are specific to their internal processes or policies.
153+
Or an information sharing and analysis organization (ISAO) might create a
154+
private namespace for decision points that are specific to their sector.
155+
In contrast, extension namespaces are
143156
intended to extend the existing SSVC namespaces and may be shared with other
144157
users of the SSVC framework.
145158

@@ -233,6 +246,8 @@ segment of the extension.
233246
To avoid conflicts with other users' extensions, we recommend using reverse
234247
domain name notation for your extensions. This helps to ensure that your
235248
extensions are unique and easily identifiable.
249+
For example, if your organization is `example.com`, you might use an extension
250+
like `ssvc//com.example/extension`.
236251

237252
!!! example "Reverse Domain Name Notation"
238253

0 commit comments

Comments
 (0)