From 68e12feec7dec6b3a43b381ceb7958d226c67de0 Mon Sep 17 00:00:00 2001
From: Maxime Dor <max@kamax.io>
Date: Sun, 5 Nov 2017 01:14:44 +0100
Subject: [PATCH] Add explicit examples for JSON encoding

---
 specification/appendices/signing_json.rst | 149 ++++++++++++++++++++++
 1 file changed, 149 insertions(+)

diff --git a/specification/appendices/signing_json.rst b/specification/appendices/signing_json.rst
index 30bf91a0..795d6669 100644
--- a/specification/appendices/signing_json.rst
+++ b/specification/appendices/signing_json.rst
@@ -86,6 +86,155 @@ insignificant whitespace, fractions, exponents and redundant character escapes
            / %x75.30.30.30 (%x30-37 / %x62 / %x65-66) ; u000X
            / %x75.30.30.31 (%x30-39 / %x61-66)        ; u001X
 
+Examples
+++++++++
+
+To assist in the development of compatible implementations, the following test
+values may be useful for verifying the canonical transformation code.
+
+Given the following JSON object:
+
+.. code:: json
+
+    {}
+
+The following canonical JSON should be produced:
+
+.. code:: json
+
+    {}
+
+Given the following JSON object:
+
+.. code:: json
+
+    {
+        "one": 1,
+        "two": "Two"
+    }
+
+The following canonical JSON should be produced:
+
+.. code:: json
+
+    {"one":1,"two":"Two"}
+
+Given the following JSON object:
+
+.. code:: json
+
+    {
+        "b": "2",
+        "a": "1"
+    }
+
+The following canonical JSON should be produced:
+
+.. code:: json
+
+    {"a":"1","b":"2"}
+
+Given the following JSON object:
+
+.. code:: json
+
+    {"b":"2","a":"1"}
+
+The following canonical JSON should be produced:
+
+.. code:: json
+
+    {"a":"1","b":"2"}
+
+Given the following JSON object:
+
+.. code:: json
+
+    {
+        "auth": {
+            "success": true,
+            "mxid": "@john.doe:example.com",
+            "profile": {
+                "display_name": "John Doe",
+                "three_pids": [
+                    {
+                        "medium": "email",
+                        "address": "john.doe@example.org"
+                    },
+                    {
+                        "medium": "msisdn",
+                        "address": "123456789"
+                    }
+                ]
+            }
+        }
+    }
+
+
+The following canonical JSON should be produced:
+
+.. code:: json
+
+    {"auth":{"mxid":"@john.doe:example.com","profile":{"display_name":"John Doe","three_pids":[{"address":"john.doe@example.org","medium":"email"},{"address":"123456789","medium":"msisdn"}]},"success":true}}
+
+
+Given the following JSON object:
+
+.. code:: json
+
+    {
+        "a": "日本語"
+    }
+
+The following canonical JSON should be produced:
+
+.. code:: json
+
+    {"a":"日本語"}
+
+Given the following JSON object:
+
+.. code:: json
+
+    {
+        "本": 2,
+        "日": 1
+    }
+
+The following canonical JSON should be produced:
+
+.. code:: json
+
+    {"日":1,"本":2}
+
+Given the following JSON object:
+
+.. code:: json
+
+    {
+        "a": "\u65E5"
+    }
+
+The following canonical JSON should be produced:
+
+.. code:: json
+
+    {"a":"日"}
+
+Given the following JSON object:
+
+.. code:: json
+
+    {
+        "a": null
+    }
+
+The following canonical JSON should be produced:
+
+.. code:: json
+
+    {"a":null}
+
 Signing Details
 ~~~~~~~~~~~~~~~