From a94019c28baf755ac376b4a22f0ce6edc2d9af6a Mon Sep 17 00:00:00 2001
From: Doug Davis <dug@us.ibm.com>
Date: Fri, 23 Mar 2018 19:54:44 -0700
Subject: [PATCH] add json serialization

Signed-off-by: Doug Davis <dug@us.ibm.com>
---
 serialization.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 spec.md          |  5 +++++
 2 files changed, 53 insertions(+)
 create mode 100644 serialization.md

diff --git a/serialization.md b/serialization.md
new file mode 100644
index 000000000..7a80327ae
--- /dev/null
+++ b/serialization.md
@@ -0,0 +1,48 @@
+# CloudEvents Serialization Profile - Version 0.1
+
+This document specifies how a CloudEvent is to be serialized into certain
+encoding formats. Compliant CloudEvents implementations that support these
+formats MUST adhere to these rules for these formats.
+
+## Table of Contents
+- [Notational Conventions](#notational-conventions)
+- [JSON](#json)
+
+## Notational Conventions
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to
+be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
+
+## JSON
+
+When serialized in [JSON](https://tools.ietf.org/html/rfc7159) a CloudEvent
+MUST adhere to the following format:
+
+```
+{
+  "cloud-events-version": "cloud-events-version value",
+  "event-id": "event-id value",
+  "namespace": "namespace value",
+  "source": {
+    "type": "source-id value",
+    "id": "source-id value"
+  },
+  "event-type": "event-type value",
+  "event-type-version": "event-type value",
+  "schema-url": "schema-url value",
+  "extensions": {
+    ... extensions values ...
+  },
+  "data": ... data value ...
+}
+```
+
+Notes:
+- The use of whitespace is not significant.
+- The order of the properties, at any level, is not significant.
+- CloudEvent producers MAY include additional properties in the JSON
+  but receivers MAY choose to ignore them. However, it is RECOMMENDED that
+  they be placed as children of the `extensions` property. Receivers
+  MUST NOT treat unkonwn additional properties as an error and MUST NOT stop
+  processing of the event as a result of their presence.
diff --git a/spec.md b/spec.md
index 6056065fa..6c203ddbc 100644
--- a/spec.md
+++ b/spec.md
@@ -26,6 +26,11 @@ Enter CloudEvents, a specification for describing event data in a common way.
 CloudEvents seeks to ease event declaration and delivery across services,
 platforms and beyond.
 
+The [Serialization Profile](serialization.md) specifies how to
+serialize a CloudEvent into certain encoding formats. Compliant CloudEvents
+implementations that support those formats MUST adhere to the encoding rules
+specified in the profile for those formats.
+
 # Design Goals
 
 CloudEvents are typically used in a distributed system to allow for services to