Added partitioning extension

See #209.

Defines a partitionKey extension attribute for use with message brokers
that support partitioning.

Signed-off-by: James Roper <james@jazzy.id.au>

documented-extensions.md

@@ -48,5 +48,6 @@ their `Attributes`.
 ## Known Extensions
 
 - [Distributed Tracing](extensions/distributed-tracing.md)
+- [Partitioning](extensions/partitioning.md)
 - [Sampling](extensions/sampled-rate.md)
 - [Sequence](extensions/sequence.md)

extensions/partitioning.md

@@ -0,0 +1,35 @@
+# Partitioning extension
+
+This extension defines attributes for use by message brokers and their
+clients that support partitioning of events, typically for the purpose of
+scaling.
+
+## Attributes
+
+### partitionkey
+
+* Type: `String`
+* Description: A partition key for the event, typically for the purposes of
+  defining a causal relationship/grouping between multiple events. In cases
+  where the CloudEvent is delivered to an event consumer via multiple hops,
+  it is possible that the value of this attribute might change, or even be 
+  removed, due to transport semantics or business processing logic within 
+  each hop.
+* Examples:
+  * The ID of the entity that the event is associated with
+* Constraints:
+  * REQUIRED
+  * MUST be a non-empty string
+
+## Encoding
+
+### In-memory formats
+
+The partitionkey attribute extension uses the key `partitionkey` for
+in-memory formats.
+
+### Transport format
+
+The Partitioning extension does not customize any transport binding's storage for
+extensions.
+