From 81b078fc8b4b15a696faf1f5da815e992e6d55d0 Mon Sep 17 00:00:00 2001
From: Ben Francis <ben@tola.me.uk>
Date: Mon, 22 Nov 2021 18:10:38 +0000
Subject: [PATCH] Move informative declarative protocol binding example to an
 appendix

---
 index.html | 677 +++++++++++++++++++++++++++--------------------------
 1 file changed, 343 insertions(+), 334 deletions(-)

diff --git a/index.html b/index.html
index e0fdd13..a923e91 100644
--- a/index.html
+++ b/index.html
@@ -1538,11 +1538,15 @@ <h3>Protocol Binding</h3>
         }
       </pre>
       <p>
-        The informative <a href="#protocol-binding-declarative-illustration">
-        Declarative Protocol Binding Illustration</a> provided below illustrates
-        how a Consumer conforming to the Core Profile would interpret the above
-        Thing Description once all of the defaults and protocol definitions
-        from the Core Profile Protocol Binding have been applied.
+        The informative declarative protocol binding example in
+        <a href="#core-profile-declarative-protocol-binding">Appendix A</a>
+        illustrates how the concrete protocol binding defined in this section
+        would have to be represented in a Thing Description if it did not use 
+        the profiling mechanism. In other words, if all of the defaults and
+        protocol specifics defined in this section were instead provided
+        declaratively using hypermedia
+        <a href="https://www.w3.org/TR/wot-thing-description/#form">
+        <code>Form</code></a>s, with all defaults made explicit.
       </p>
 
       <section id="properties">
@@ -2708,356 +2712,361 @@ <h4>Error Responses</h4>
           </span>
         </p>
       </section>
+    </section>
+  </section>
 
-      <section id="protocol-binding-declarative-illustration">
-        <h4>Declarative Protocol Binding Illustration</h4>
-        <p>
-          The following informative Thing Description serves to illustrate how
-          the example Thing Description in <a href="#example-3">EXAMPLE 3</a> 
-          would look if the full Core Profile Protocol Binding was provided
-          declaratively in the Thing Description, with all defaults made 
-          explicit.
-        </p>  
-        <p>
-          This example is only an illustration of a machine-readable version of 
-          the Core Profile Protocol Binding and a demonstration of how Web 
-          Things conforming to the Core Profile can benefit from more concise
-          Thing Descriptions. A Consumer conforming to the Core Profile would
-          only require the significantly more concise form shown in 
-          <a href="#example-3">EXAMPLE 3</a> in order to derive the same
-          information.
-        </p>
-        <pre class="example">
-          {
-            "@context": "https://www.w3.org/2019/wot/td/v1",
-            "id": "https://mywebthingserver.com/things/lamp",
-            "base": "https://mywebthingserver.com/things/lamp/",
-            "title": "My Lamp",
-            "description": "A web connected lamp",
-            "securityDefinitions": {
-              "oauth2": {
-                "scheme": "oauth2",
-                "flow": "code",
-                "authorization": "https://mywebthingserver.com/oauth/authorize",
-                "token": "https://mywebthingserver.com/oauth/token"
+  <section id="core-profile-json-schema" class="appendix normative">
+    <h1>JSON Schema of the Core Profile</h1>
+    <p>
+      A Thing Description can be syntactically validated with the JSON Schema [[?JSON-SCHEMA]] for compliance with
+      the core profile.
+    </p>
+    <p class="ednote">
+      Todo: Define a JSON-SCHEMA.
+    </p>
+  </section>
+</section>
+
+<section id="core-profile-declarative-protocol-binding" class="informative appendix">
+  <h1>Core Profile Declarative Protocol Binding Example</h4>
+  <p>
+    The following informative Thing Description illustrates how the concrete 
+    <a href=#protocol-binding>protocol binding</a> defined in the Core Profile
+    would have to be represented by the Web Thing described by
+    <a href="#example-3">EXAMPLE 3</a> if it did not use the
+    <a href="#profiling-mechanism">profiling mechanism</a>. In other words, if 
+    all of the defaults and protocol specifics defined in the Core Profile 
+    <a href="#protocol-binding">protocol binding</a> were instead provided
+    declaratively using hypermedia
+    <a href="https://www.w3.org/TR/wot-thing-description/#form">
+    <code>Form</code></a>s, with all defaults made explicit.
+  </p>
+  <p>
+    This example is only intended as an illustration of how Web 
+    Things conforming to the Core Profile can benefit from more concise
+    Thing Descriptions. A Web Thing which does use the profiling mechanism 
+    would only need to use the significantly more concise form shown in 
+    <a href="#example-3">EXAMPLE 3</a> in order to provide the same information.
+  </p>
+  <pre class="example">
+    {
+      "@context": "https://www.w3.org/2019/wot/td/v1",
+      "id": "https://mywebthingserver.com/things/lamp",
+      "base": "https://mywebthingserver.com/things/lamp/",
+      "title": "My Lamp",
+      "description": "A web connected lamp",
+      "securityDefinitions": {
+        "oauth2": {
+          "scheme": "oauth2",
+          "flow": "code",
+          "authorization": "https://mywebthingserver.com/oauth/authorize",
+          "token": "https://mywebthingserver.com/oauth/token"
+        }
+      },
+      "security": "oauth2",
+      "properties": {
+        "on": {
+          "type": "boolean",
+          "title": "On/Off",
+          "description": "Whether the lamp is turned on",
+          "forms": [
+            {
+              "op": "readproperty",
+              "href": "./properties/on",
+              "htv:methodName": "GET",
+              "htv:headers": [{
+                "htv:fieldName": "Accept",
+                "htv:fieldValue": "application/json"
+              }],
+              "response": {
+                "htv:statusCodeNumber": 200,
+                "contentType": "application/json"
+              }
+            },
+            {
+              "op": "writeproperty",
+              "href": "./properties/on",
+              "htv:methodName": "PUT",
+              "contentType": "application/json",
+              "response": {
+                "htv:statusCodeNumber": 204
+              }
+            }
+          ]
+        },
+        "level" : {
+          "type": "integer",
+          "title": "Brightness",
+          "description": "The level of light from 0-100",
+          "unit": "percent",
+          "minimum" : 0,
+          "maximum" : 100,
+          "forms": [
+            {
+              "op": "readproperty",
+              "href": "./properties/level",
+              "htv:methodName": "GET",
+              "htv:headers": [{
+                "htv:fieldName": "Accept",
+                "htv:fieldValue": "application/json"
+              }],
+              "response": {
+                "htv:statusCodeNumber": 200,
+                "contentType": "application/json"
               }
             },
-            "security": "oauth2",
+            {
+              "op": "writeproperty",
+              "href": "./properties/level",
+              "htv:methodName": "PUT",
+              "contentType": "application/json",
+              "response": {
+                "htv:statusCodeNumber": 204
+              }
+            }
+          ]
+        }
+      },
+      "actions": {
+        "fade": {
+          "title": "Fade",
+          "description": "Fade the lamp to a given level",
+          "input": {
+            "type": "object",
             "properties": {
-              "on": {
-                "type": "boolean",
-                "title": "On/Off",
-                "description": "Whether the lamp is turned on",
-                "forms": [
-                  {
-                    "op": "readproperty",
-                    "href": "./properties/on",
-                    "htv:methodName": "GET",
-                    "htv:headers": [{
-                      "htv:fieldName": "Accept",
-                      "htv:fieldValue": "application/json"
-                    }],
-                    "response": {
-                      "htv:statusCodeNumber": 200,
-                      "contentType": "application/json"
-                    }
-                  },
-                  {
-                    "op": "writeproperty",
-                    "href": "./properties/on",
-                    "htv:methodName": "PUT",
-                    "contentType": "application/json",
-                    "response": {
-                      "htv:statusCodeNumber": 204
-                    }
-                  }
-                ]
+              "level": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 100,
+                "unit": "percent"
               },
-              "level" : {
+              "duration": {
                 "type": "integer",
-                "title": "Brightness",
-                "description": "The level of light from 0-100",
-                "unit": "percent",
-                "minimum" : 0,
-                "maximum" : 100,
-                "forms": [
-                  {
-                    "op": "readproperty",
-                    "href": "./properties/level",
-                    "htv:methodName": "GET",
-                    "htv:headers": [{
-                      "htv:fieldName": "Accept",
-                      "htv:fieldValue": "application/json"
-                    }],
-                    "response": {
-                      "htv:statusCodeNumber": 200,
-                      "contentType": "application/json"
-                    }
-                  },
-                  {
-                    "op": "writeproperty",
-                    "href": "./properties/level",
-                    "htv:methodName": "PUT",
-                    "contentType": "application/json",
-                    "response": {
-                      "htv:statusCodeNumber": 204
-                    }
-                  }
-                ]
+                "minimum": 0,
+                "unit": "milliseconds"
               }
-            },
-            "actions": {
-              "fade": {
-                "title": "Fade",
-                "description": "Fade the lamp to a given level",
-                "input": {
-                  "type": "object",
-                  "properties": {
-                    "level": {
-                      "type": "integer",
-                      "minimum": 0,
-                      "maximum": 100,
-                      "unit": "percent"
-                    },
-                    "duration": {
-                      "type": "integer",
-                      "minimum": 0,
-                      "unit": "milliseconds"
-                    }
-                  }
-                },
-                "forms": [
-                  {
-                    "op": "invokeaction",
-                    "href": "./actions/fade",
-                    "htv:methodName": "POST",
-                    "contentType": "application/json",
-                    "htv:headers": [{
-                      "htv:fieldName": "Accept",
-                      "htv:fieldValue": "application/json"
-                    }],
-                    "response": {
-                      "htv:statusCodeNumber": 201,
-                      "htv:headers": [
-                        {
-                          "htv:fieldName": "Location",
-                          "htv:fieldValue": "/fade/{id}"
-                        }
-                      ],
-                      "contentType": "application/json",
-                      "schema": "actionStatus"
-                    },
-                    "additionalResponses": [
-                      {
-                        "htv:statusCodeNumber": 200,
-                        "htv:headers": [
-                          {
-                            "htv:fieldName": "Location",
-                            "htv:fieldValue": "/fade/{id}"
-                          }
-                        ],
-                        "contentType": "application/json",
-                        "schema": "actionStatus"
-                      }
-                    ]
-                  },
-                  {
-                    "op": "queryaction",
-                    "href": "./actions/fade/{id}",
-                    "htv:methodName": "GET",
-                    "htv:headers": [{
-                      "htv:fieldName": "Accept",
-                      "htv:fieldValue": "application/json"
-                    }],
-                    "response": {
-                      "contentType": "application/json",
-                      "schema": "actionStatus"
-                    }
-                  },
+            }
+          },
+          "forms": [
+            {
+              "op": "invokeaction",
+              "href": "./actions/fade",
+              "htv:methodName": "POST",
+              "contentType": "application/json",
+              "htv:headers": [{
+                "htv:fieldName": "Accept",
+                "htv:fieldValue": "application/json"
+              }],
+              "response": {
+                "htv:statusCodeNumber": 201,
+                "htv:headers": [
                   {
-                    "op": "cancelaction",
-                    "href": "./actions/fade/{id}",
-                    "htv:methodName": "DELETE",
-                    "contentType": "application/json"
+                    "htv:fieldName": "Location",
+                    "htv:fieldValue": "/fade/{id}"
                   }
                 ],
-                "uriVariables": {
-                  "id": {
-                    "type": "string",
-                    "description": "identifier of action request"
-                  }
+                "contentType": "application/json",
+                "schema": "actionStatus"
+              },
+              "additionalResponses": [
+                {
+                  "htv:statusCodeNumber": 200,
+                  "htv:headers": [
+                    {
+                      "htv:fieldName": "Location",
+                      "htv:fieldValue": "/fade/{id}"
+                    }
+                  ],
+                  "contentType": "application/json",
+                  "schema": "actionStatus"
                 }
-              }
+              ]
             },
-            "events": {
-              "overheated": {
-                "title": "Overheated",
-                "data": {
-                  "type": "number",
-                  "unit": "degree celsius"
-                },
-                "description": "The lamp has exceeded its safe operating temperature",
-                "forms": [
-                  {
-                    "op": "subscribeevent",
-                    "href": "./events/overheated",
-                    "subprotocol": "sse",
-                    "htv:methodName": "GET",
-                    "htv:headers": [
-                      {
-                        "htv:fieldName": "Accept",
-                        "htv:fieldValue": "text/event-stream"
-                      },
-                      {
-                        "htv:fieldName": "Connection",
-                        "htv:fieldValue": "keep-alive"
-                      }
-                    ],
-                    "response": {
-                      "htv:statusCodeNumber": 200,
-                      "contentType": "text/event-stream"
-                    }
-                  },
-                  {
-                    "op": "unbsubscribeevent",
-                    "href": "./events/overheated",
-                    "subprotocol": "sse"
-                  }
-                ]
+            {
+              "op": "queryaction",
+              "href": "./actions/fade/{id}",
+              "htv:methodName": "GET",
+              "htv:headers": [{
+                "htv:fieldName": "Accept",
+                "htv:fieldValue": "application/json"
+              }],
+              "response": {
+                "contentType": "application/json",
+                "schema": "actionStatus"
               }
             },
-            "forms": [
-              {
-                "op": "readallproperties",
-                "href": "./properties",
-                "htv:methodName": "GET",
-                "htv:headers": [{
-                  "htv:fieldName": "Accept",
-                  "htv:fieldValue": "application/json"
-                }],
-                "response": {
-                  "htv:statusCodeNumber": 200,
-                  "contentType": "application/json"
-                }
-              },
-              {
-                "op": "writemultipleproperties",
-                "href": "./properties",
-                "htv:methodName": "PUT",
-                "contentType": "application/json",
-                "response": {
-                  "htv:statusCodeNumber": 204
-                }
-              },
-              {
-                "op": "queryallactions",
-                "href": "./actions",
-                "htv:methodName": "GET",
-                "htv:headers": [{
+            {
+              "op": "cancelaction",
+              "href": "./actions/fade/{id}",
+              "htv:methodName": "DELETE",
+              "contentType": "application/json"
+            }
+          ],
+          "uriVariables": {
+            "id": {
+              "type": "string",
+              "description": "identifier of action request"
+            }
+          }
+        }
+      },
+      "events": {
+        "overheated": {
+          "title": "Overheated",
+          "data": {
+            "type": "number",
+            "unit": "degree celsius"
+          },
+          "description": "The lamp has exceeded its safe operating temperature",
+          "forms": [
+            {
+              "op": "subscribeevent",
+              "href": "./events/overheated",
+              "subprotocol": "sse",
+              "htv:methodName": "GET",
+              "htv:headers": [
+                {
                   "htv:fieldName": "Accept",
-                  "htv:fieldValue": "application/json"
-                }],
-                "response": {
-                  "contentType": "application/json",
-                  "schema": "actionStatusList"
-                }
-              },
-              {
-                "op": "subscribeallevents",
-                "href": "./events",
-                "subprotocol": "sse",
-                "htv:methodName": "GET",
-                "htv:headers": [
-                  {
-                    "htv:fieldName": "Accept",
-                    "htv:fieldValue": "text/event-stream"
-                  },
-                  {
-                    "htv:fieldName": "Connection",
-                    "htv:fieldValue": "keep-alive"
-                  }
-                ],
-                "response": {
-                  "htv:statusCodeNumber": 200,
-                  "contentType": "text/event-stream"
+                  "htv:fieldValue": "text/event-stream"
+                },
+                {
+                  "htv:fieldName": "Connection",
+                  "htv:fieldValue": "keep-alive"
                 }
-              },
-              {
-                "op": "unsubscribeallevents",
-                "href": "./events",
-                "subprotocol": "sse"
+              ],
+              "response": {
+                "htv:statusCodeNumber": 200,
+                "contentType": "text/event-stream"
               }
-            ],
-            "schemaDefinitions": {
-              "actionStatus": {
-                "type": "object",
-                "properties": {
-                  "status": {
-                    "type": "string",
-                    "enum": [
-                      "pending",
-                      "running",
-                      "completed",
-                      "failed"
-                    ]
-                  },
-                  "error": {
-                    "type": "object"
-                  },
-                  "href": {
-                    "type": "string",
-                    "format": "uri",
-                    "const": "./actions/fade/{id}"
-                  }
-                },
-                "required": [
-                  "status"
+            },
+            {
+              "op": "unbsubscribeevent",
+              "href": "./events/overheated",
+              "subprotocol": "sse"
+            }
+          ]
+        }
+      },
+      "forms": [
+        {
+          "op": "readallproperties",
+          "href": "./properties",
+          "htv:methodName": "GET",
+          "htv:headers": [{
+            "htv:fieldName": "Accept",
+            "htv:fieldValue": "application/json"
+          }],
+          "response": {
+            "htv:statusCodeNumber": 200,
+            "contentType": "application/json"
+          }
+        },
+        {
+          "op": "writemultipleproperties",
+          "href": "./properties",
+          "htv:methodName": "PUT",
+          "contentType": "application/json",
+          "response": {
+            "htv:statusCodeNumber": 204
+          }
+        },
+        {
+          "op": "queryallactions",
+          "href": "./actions",
+          "htv:methodName": "GET",
+          "htv:headers": [{
+            "htv:fieldName": "Accept",
+            "htv:fieldValue": "application/json"
+          }],
+          "response": {
+            "contentType": "application/json",
+            "schema": "actionStatusList"
+          }
+        },
+        {
+          "op": "subscribeallevents",
+          "href": "./events",
+          "subprotocol": "sse",
+          "htv:methodName": "GET",
+          "htv:headers": [
+            {
+              "htv:fieldName": "Accept",
+              "htv:fieldValue": "text/event-stream"
+            },
+            {
+              "htv:fieldName": "Connection",
+              "htv:fieldValue": "keep-alive"
+            }
+          ],
+          "response": {
+            "htv:statusCodeNumber": 200,
+            "contentType": "text/event-stream"
+          }
+        },
+        {
+          "op": "unsubscribeallevents",
+          "href": "./events",
+          "subprotocol": "sse"
+        }
+      ],
+      "schemaDefinitions": {
+        "actionStatus": {
+          "type": "object",
+          "properties": {
+            "status": {
+              "type": "string",
+              "enum": [
+                "pending",
+                "running",
+                "completed",
+                "failed"
+              ]
+            },
+            "error": {
+              "type": "object"
+            },
+            "href": {
+              "type": "string",
+              "format": "uri",
+              "const": "./actions/fade/{id}"
+            }
+          },
+          "required": [
+            "status"
+          ]
+        },
+        "actionStatusList": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": [
+                  "pending",
+                  "running",
+                  "completed",
+                  "failed"
                 ]
               },
-              "actionStatusList": {
-                "type": "array",
-                "items": {
-                  "type": "object",
-                  "properties": {
-                    "status": {
-                      "type": "string",
-                      "enum": [
-                        "pending",
-                        "running",
-                        "completed",
-                        "failed"
-                      ]
-                    },
-                    "error": {
-                      "type": "object"
-                    },
-                    "href": {
-                      "type": "string",
-                      "format": "uri",
-                      "const": "./actions/fade/{id}"
-                    }
-                  },
-                  "required": [
-                    "status"
-                  ]
-                }
+              "error": {
+                "type": "object"
+              },
+              "href": {
+                "type": "string",
+                "format": "uri",
+                "const": "./actions/fade/{id}"
               }
-            }
+            },
+            "required": [
+              "status"
+            ]
           }
-        </pre>
-      </section>
-    </section>
-  </section>
-
-  <section id="core-profile-json-schema" class="appendix normative">
-    <h1>JSON Schema of the Core Profile</h1>
-    <p>
-      A Thing Description can be syntactically validated with the JSON Schema [[?JSON-SCHEMA]] for compliance with
-      the core profile.
-    </p>
-    <p class="ednote">
-      Todo: Define a JSON-SCHEMA.
-    </p>
+        }
+      }
+    }
+  </pre>
+</section>
 
 </body>