Mark .instrumentation as experimental

README.md

@@ -94,7 +94,7 @@ Stability guarantees do not apply to [experimental features](#experimental-featu
 
 Sometimes we need to experiment with new types and properties. For example, to evaluate the configuration experience for experimental features in [opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification).
 
-Experimental properties are denoted by a `*/(development|alpha|beta)` suffix (e.g.`foo/development`). The suffix indicates the property value and all types nested within it are exempt from stability guarantees, and are subject to breaking changes in minor versions. Experimental types have a [title](https://json-schema.org/understanding-json-schema/reference/annotations) prefixed with `Experimental*` (e.g. `ExperimentalFoo`).
+Experimental properties are denoted by a `*/(development|alpha|beta)` suffix (e.g.`foo/development`). The suffix indicates the property value and all types nested within it are exempt from stability guarantees, and are subject to breaking changes in minor versions. Experimental type key values in `$defs` should be prefixed with `Experimental*` (e.g. `ExperimentalFoo`). Note that because we [omit the title annotation](./CONTRIBUTING.md#annotations---title-and-description), the `$defs` key value effectively acts as the type title for code generation tools. 
 
 Maintainers are not obligated to implement support for experimental properties and types. When they do, they are no obligated to maintain any stability guarantees. 
 

examples/kitchen-sink.yaml

@@ -700,7 +700,8 @@ resource:
   # If omitted or null, no schema URL is used.
   schema_url: https://opentelemetry.io/schemas/1.16.0
 # Configure instrumentation.
-instrumentation:
+# This type is in development and subject to breaking changes in minor versions.
+instrumentation/development:
   # Configure general SemConv options that may apply to multiple languages and instrumentations.
   # Instrumenation may merge general config options with the language specific configuration at .instrumentation.<language>.
   general:

schema/instrumentation.json

@@ -5,61 +5,61 @@
     "additionalProperties": false,
     "properties": {
         "general": {
-            "$ref": "#/$defs/GeneralInstrumentation"
+            "$ref": "#/$defs/ExperimentalGeneralInstrumentation"
         },
         "cpp": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "dotnet": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "erlang": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "go": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "java": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "js": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "php": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "python": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "ruby": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "rust": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         },
         "swift": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         }
     },
     "patternProperties": {
         ".*": {
-            "$ref": "#/$defs/LanguageSpecificInstrumentation"
+            "$ref": "#/$defs/ExperimentalLanguageSpecificInstrumentation"
         }
     },
     "$defs": {
-        "GeneralInstrumentation": {
+        "ExperimentalGeneralInstrumentation": {
             "type": "object",
             "additionalProperties": false,
             "properties": {
                 "peer": {
-                    "$ref": "#/$defs/PeerInstrumentation"
+                    "$ref": "#/$defs/ExperimentalPeerInstrumentation"
                 },
                 "http": {
-                    "$ref": "#/$defs/HttpInstrumentation"
+                    "$ref": "#/$defs/ExperimentalHttpInstrumentation"
                 }
             }
         },
-        "PeerInstrumentation": {
+        "ExperimentalPeerInstrumentation": {
             "type": "object",
             "additionalProperties": false,
             "properties": {
@@ -84,7 +84,7 @@
                 }
             }
         },
-        "HttpInstrumentation": {
+        "ExperimentalHttpInstrumentation": {
             "type": "object",
             "additionalProperties": false,
             "properties": {
@@ -126,7 +126,7 @@
                 }
             }
         },
-        "LanguageSpecificInstrumentation": {
+        "ExperimentalLanguageSpecificInstrumentation": {
             "type": "object",
             "additionalProperties": true,
             "patternProperties": {

schema/opentelemetry_configuration.json

@@ -32,8 +32,8 @@
         "resource": {
             "$ref": "#/$defs/Resource"
         },
-        "instrumentation": {
-            "$ref": "#/$defs/Instrumentation"
+        "instrumentation/development": {
+            "$ref": "#/$defs/ExperimentalInstrumentation"
         }
     },
     "required": [
@@ -67,7 +67,7 @@
         "Resource": {
             "$ref": "resource.json"
         },
-        "Instrumentation": {
+        "ExperimentalInstrumentation": {
             "$ref": "instrumentation.json"
         }
     }

schema/type_descriptions.yaml

@@ -48,7 +48,10 @@
       Configure meter provider.
 
       If omitted, a noop meter provider is used.
-    instrumentation: Configure instrumentation.
+    instrumentation/development: >
+      Configure instrumentation.
+
+      This type is in development and subject to breaking changes in minor versions.
   path_patterns:
     - .
 
@@ -704,7 +707,7 @@
     rust: Configure Rust language-specific instrumentation libraries.
     swift: Configure Swift language-specific instrumentation libraries.
   path_patterns:
-    - .instrumentation
+    - .instrumentation/development
 
 - type: GeneralInstrumentation
   property_descriptions:
@@ -717,7 +720,7 @@
 
       See http semantic conventions: https://opentelemetry.io/docs/specs/semconv/http/
   path_patterns:
-    - .instrumentation.general
+    - .instrumentation/development.general
 
 - type: GeneralInstrumentationPeer
   property_descriptions:
@@ -728,33 +731,33 @@
 
       See peer.service semantic conventions: https://opentelemetry.io/docs/specs/semconv/general/attributes/#general-remote-service-attributes
   path_patterns:
-    - .instrumentation.general.peer
+    - .instrumentation/development.general.peer
 
 - type: GeneralInstrumentationHttp
   property_descriptions:
     client: Configure instrumentations following the http client semantic conventions.
     server: Configure instrumentations following the http server semantic conventions.
   path_patterns:
-    - .instrumentation.general.http
+    - .instrumentation/development.general.http
 
 - type: GeneralInstrumentationHttpClient
   property_descriptions:
     request_captured_headers: Configure headers to capture for outbound http requests.
     response_captured_headers: Configure headers to capture for outbound http responses.
   path_patterns:
-    - .instrumentation.general.http.client
+    - .instrumentation/development.general.http.client
 
 - type: GeneralInstrumentationHttpServer
   property_descriptions:
     request_captured_headers: Configure headers to capture for inbound http requests.
     response_captured_headers: Configure headers to capture for outbound http responses.
   path_patterns:
-    - .instrumentation.general.http.server
+    - .instrumentation/development.general.http.server
 
 - type: LanguageSpecificInstrumentation
   property_descriptions:
     example: Configure the instrumentation corresponding to key "example".
   path_patterns:
-    - .instrumentation.*
+    - .instrumentation/development.*
 # END Instrumentation