opengdpr · bhox · May 17, 2018 · May 18, 2018
diff --git a/OpenGDPR_extensions.md b/OpenGDPR_extensions.md
@@ -1,53 +1,63 @@
 # OpenGDPR Extensions
 
-OpenGDPR requests may contain an `extensions` object, composed of a series of child-objects, keyed by a processor domain. 
+OpenGDPR requests may contain an `extensions` object, composed of a series of child-objects, keyed by a processor domain. Extensions are defined here via markdown and JSON-Schema.
 
 - The domain of each extension **MUST** match the processor's OpenGDPR domain.
-- Extensions **MUST** not be used for or contain authentication information. 
-- Processors **MUST** only implement an extension for items that do not already fit into the generic spec. 
+- Extensions **MUST** not be used for or contain authentication information.
+- Processors **MUST** only implement an extension for items that do not already fit into the generic spec.
+- Extensions are namespaced by the processors OpenGDPR domain and have an explicit name/key.
+- One processor may have many extensions under their namespace.
 
 See section the [OpenGDPR spec](OpenGDPR_specification.md) for more information on the use of extensions.
 
-## Published Extensions
+# Extension Definitions
+Extensions are defined in this document with the following fields:
 
-### mParticle
+- Domain: The OpenGDPR domain/subdomain for the processor publishing and consuming the extension.
+
+- Name: The name of this extension.
+Description: A brief description of this extension.
+
+- Example in a new OpenGDPR Request: Show a snippet of how the extension should be used in an OpenGDPR request.
+
+- JSON-Schema definition: A JSON-Schema snippet that defines the fields and formats expected by this extension.
+
+
+---
+
+
+# Published Extensions
+
+## opengdpr.mparticle.com
+### mpids
 
 Domain: `opengdpr.mparticle.com`
 
-Supported keys:
+Name: 'mpids'
 
-- `mpids`: An array of mParticle IDs. The mParticle ID is a 64-bit signed integer.
+Description:
+  Provides support for passing mParticle's internal id "mpid" in a request.
 
-### Example
+#### Example in a new OpenGDPR Request
 
 ```json
+...
 "extensions": {
     "opengdpr.mparticle.com": {
       "mpids":[120934871234, 1309487143098]
     }
 }
+...
 ```
 
-### Schema
+#### JSON-Schema Definition
 
 ```json
 {
-  "type": "object",
-  "properties": {
-    "opengdpr.mparticle.com": {
-      "type": "object",
-      "properties": {
-        "mpids": {
-          "type": "array",
-          "items": {
-            "examples": [
-              120934871234,
-              1309487143098
-            ]
-          }
-        }
-      }
-    }
+  "type": "array",
+  "items":
+  {
+    "type":"64-bit signed integer",
   }
 }
-```
+```
diff --git a/OpenGDPR_specification.md b/OpenGDPR_specification.md
@@ -62,18 +62,18 @@ Enacting compliance related activities to honor an OpenGDPR request.
 ### 3.1. Roles and Responsibilities
 
 #### Data Subject
- 
+
   A European Union resident whose personal data is being processed.
 
 #### Data Controller
-  
+
   An entity which makes the decision about what personal data  will be processed and the types of processing that will be done with respect to that personal data. The Data Controller receives Data Subject requests from the Data Subjects and validates them. The Data Controller **SHOULD** provide a callback endpoint. The Data Controller **SHOULD** verify response signatures. Referenced as "Controller."
 
 #### Data Processor
 
-  The organization that processes data pursuant to the instructions of the Controller on behalf of the Controller. The Data Processor receives data subject requests via RESTful endpoints and is responsible for fulfilling requests. The Data Processor **MUST** provide a signed response to requests. The Data Processor **MUST** honor callbacks.  Data Processors **MUST** honor callbacks included in requests. 
+  The organization that processes data pursuant to the instructions of the Controller on behalf of the Controller. The Data Processor receives data subject requests via RESTful endpoints and is responsible for fulfilling requests. The Data Processor **MUST** provide a signed response to requests. The Data Processor **MUST** honor callbacks.  Data Processors **MUST** honor callbacks included in requests.
 
-  Processors **MUST** provide the following endpoints: 
+  Processors **MUST** provide the following endpoints:
 
   - `/discovery`
   - `/status`
@@ -193,13 +193,17 @@ erasure
 
   **REQUIRED** version string representing the supported version of the OpenGDPR API.
 
- `supported_identities`
+`supported_identities`
 
   **REQUIRED** array of "identity_type" and "identity_format" pairs.
 
 `supported_subject_request_types`
 
-   **REQUIRED** array of "subject_request_type" strings as defined in 6.2.
+  **REQUIRED** array of "subject_request_type" strings as defined in 6.2.
+
+`supported_extensions`
+
+  **REQUIRED** an object containing the extensions supported as defined in 7.1.2.
 
 `processor_certificate`
 
@@ -222,6 +226,13 @@ Content Type: application/json
          "identity_format":"sha256"
       }
    ],
+   "supported_extensions":
+   {
+    "opengdpr.example-processor.com":
+      [
+        "extension-name"
+      ],
+   },
    "supported_subject_request_types":[
       "erasure"
    ],
@@ -265,11 +276,12 @@ OpenGDPR service implementations **MUST** provide an endpoint that creates OpenG
 
 #### 7.1.2 Extensions
 
-OpenGDPR requests may contain an `extensions` object, composed of a series of child-objects, keyed by a processor domain. 
+OpenGDPR requests may contain an `extensions` object, composed of a series of child-objects, keyed by a processor domain.
 
 - The domain of each extension **MUST** match the processor's OpenGDPR domain, matching the `X-OpenGDPR-Processor-Domain` header in OpenGDPR responses.
-- Extensions **MUST** not be used for or contain authentication information. 
-- Processors **MUST** only implement an extension for items that do not already fit into the generic spec. 
+- Extensions **MUST** not be used for or contain authentication information.
+- Processors **MUST** only implement an extension for items that do not already fit into the generic spec.
+- Extensions are published and defined in this repository in the "OpenGDPR_extensions.md" file.
 
 [Currently known extensions can be found here](OpenGDPR_extensions.md).
 
@@ -297,11 +309,11 @@ Content Type: application/json
   ],
   "extensions": {
     "example-processor.com": {
-      "foo-processor-custom-id":123456,
-      "property_id": "123456",
-    },
-    "example-other-processor.com": {
-      "foo-other-processor-custom-id":654321
+      "example-processor-custom-id":123456,
+      "custom-info": [
+        "12345",
+        "67890"
+      ],
     }
   }
 }
@@ -695,4 +707,4 @@ safeguard each request and it’s encapsulated identities.
 
 ## 12.   References
 
-[The EU General Data Protection Regulation](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN)
+[The EU General Data Protection Regulation](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN)