Proposal: Introduce bundles

docs/proposals/bundles.md

@@ -0,0 +1,125 @@
+# Bundles
+
+This document is a design proposal to add the ability to define bundles of attributes in semconv.
+
+## Use cases
+
+There are a few different use cases which bundles will help us to achieve.
+
+### Defining signals
+
+By introducing bundles we are able to bundle a collection of attributes together into a single reusable item. 
+These items have the primary goal of reducing the need to copy paste definitions while also reducing the maintaince effort.
+
+An example of where this would be useful is if a `server` bundle was defined similiar to below:
+
+```
+bundle:
+  - name: server
+    brief: Defines a server
+    note:
+    attributes:
+      - ref: server.address
+      - ref: server.port
+```
+
+Once it is defined, it can then be used on other signals to extend the definition.
+
+```
+span:
+  - name: messaging.produced
+    brief: Defines a span for sending a message via a message broker such as RabbitMQ
+    note:
+    attributes:
+      - ref: message.system.name
+    bundles:
+      - ref: server
+```
+
+In terms of the resolved schema, these bundles are blended seamlessly in to the definition.
+
+```
+span:
+  - name: messaging.produced
+    brief: Defines a span for sending a message via a message broker such as RabbitMQ
+    note:
+    attributes:
+      - id: message.system.name
+        ....
+      - id: server.address
+        ....
+      - id: server.port
+        ....
+```
+
+By adopting this approach we are improving the mantainability of the definitions,
+by reusing the definition rather than copying and pasting structures.
+
+### Extending signals
+
+This use case is similiar to the previous except it is focussed on offering optional contextual extensions.
+An example of this extension would be CloudEvents which are only applicable if the application is using CloudEvents, 
+hence the usage is contextual based upon CloudEvents being used.
+The concept of CloudEvents is described in [CloudEvents Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md).
+
+To indicate that a bundle is contextual, this can be done by defining this on the bundle, just like below for `cloud_events`:
+
+```
+bundle:
+  - name: cloud_events
+    brief: For more information on the concepts, terminology and background of CloudEvents consult the CloudEvents Primer document.
+    context: Can be used when a cloud event payload is being handled (sent/recieved).
+    note:
+    attributes:
+      - ref: cloudevents.event_id
+      - ref: cloudevents.event_source
+      ......
+```
+Once it is defined, it can then be used on other signals ie the span defined in the previous chapter.
+
+```
+span:
+  - name: messaging.produced
+    brief: Defines a span for sending a message via a message brooker such as rabbitmq
+    note:
+    attributes
+      - ref: message.system.name
+    bundles:
+      - ref: server
+      - ref: cloud_events
+```
+
+In terms of the resolved schema, these bundles are blended seamlessly in to the definition.
+
+```
+span:
+  - name: messaging.produced
+    brief: Defines a span for sending a message via a message brooker such as rabbitmq
+    note:
+    attributes
+      - id: message.system.name
+        ....
+      - id: server.address
+        ....
+      - id: server.port
+        ....
+      - id: cloudevents.event_id
+        bundle: cloud_events
+        context: Can be used when a cloud event 
+        ....
+      - id: cloudevents.event_source
+        bundle: cloud_events
+        context: Can be used when a cloud event 
+        ....
+```
+
+By adopting this approach the definition of CloudEvents can easily be added/extended without needing to touch the usage.
+
+## Comparison to v1 solution
+Attribute bundles are similiar to attribute groups however,
+there are some important differences that needs to be called out:
+
+* **Extends:** Bundles can not extend other bundles which is the case to reduce complexity
+and enable streamlining of the resolving process.
+* **Referencing:** A signal ie span can now reference multiple bundles,
+which removes the need for creating nested bundles.