tag-review.html

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Web of Things (WoT) Thing Description</title>
    <script src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>
    <script class='remove'>
          var respecConfig = {
              specStatus:     "ED"
            , processVersion: 2017
            , shortName:      "wot-thing-description"
            , copyrightStart: 2017
            , noLegacyStyle:  true
            , inlineCSS:      true
            , noIDLIn:        true
            , format:         "markdown"
            , wg:             "Web of Things Working Group"
            , wgURI:          "https://www.w3.org/WoT/WG/"
            , wgPublicList:   "public-wot-wg"
            , edDraftURI:     "https://w3c.github.io/wot-thing-description/"
            , githubAPI:      "https://api.github.com/repos/w3c/wot-thing-description"
            , issueBase:      "https://www.github.com/w3c/wot-thing-description/issues"
            , editors: [
                {
                  name:       "Sebastian Kaebisch"
                , w3cid:      "43064"
                , company:    "Siemens AG"
                , companyURL: "https://www.siemens.com/"
                }
              , {
                  name:       "Takuki Kamiya"
                , w3cid:      "29376"
                , company:    "Fujitsu Laboratories of America, Inc."
                , companyURL: "https://www.fujitsu.com/"
                }
                , {
                  name:       "Michael McCool"
                , w3cid:      ""
                , company:    "Intel"
                , companyURL: "	www.intel.com/"
                }
                , {
                  name:       "Victor Charpenay"
                , w3cid:      ""
                , company:    "Siemens AG"
                , companyURL: "https://www.siemens.com/"
                }
              ]
            , localBiblio: {
                "JSON-SCHEMA-VALIDATION": {
                  title:    "JSON Schema Validation: A Vocabulary for Structural Validation of JSON"
                , href:     "https://tools.ietf.org/html/draft-handrews-json-schema-validation-00"
                , authors: [
                    "Austin Wright"
                  , "Henry Andrews"
                  , "Geraint Luff"
                  ]
                , status:   "Internet-Draft"
                , publisher:  "IETF"
                }
              , "JSON-SCHEMA-CORE": {
                  title:    "JSON Schema: A Media Type for Describing JSON Documents"
                , href:     "https://tools.ietf.org/html/draft-handrews-json-schema-00"
                , authors:  [
                    "Austin Wright"
                  , "Henry Andrews"
                  ]
                , status:    "Internet-Draft"
                , publisher: "IETF"
                }
              , "OPENAPI": {
                  title:    "OpenAPI Specification: Version 3.0.1"
                , href:     "https://swagger.io/specification/"
                , authors:  [
		    "Darrel Miller"
                  , "Jason Harmon"
                  , "Jeremy Whitlock"
                  , "Kris Hahn"
                  , "Marsh Gardiner"
                  , "Mike Ralphson"
                  , "Rob Dolin"
                  , "Ron Ratovsky"
                  , "Tony Tam"
                  ]
                , publisher: "OpenAPI Initiative, Linux Foundation"
                , date: "7 December 2017"
                }
              , "SemVer": {
                  title:    "Semantic Versioning 2.0.0"
                , href:     "https://semver.org/"
                , authors:  ["Tom Preston-Werner"]
                , date: "26 December 2017"
                }
              , "WOT-ARCHITECTURE" : {
                  title: "Web of Things Architecture"
                , href: "https://w3c.github.io/wot-architecture/"
                , authors:  [
                    "Kazuo Kajimoto"
                  , "Matthias Kovatsch"
                  , "Uday Davuluru"
                  ]
                , publisher: "W3C"
                , date: "20 August 2017"
                }
              , "WOT-SECURITY-CONSIDERATIONS" : {
                title: "Web of Things Security and Privacy Considerations"
                , href: "https://w3c.github.io/wot-security/"
                , authors:  [
                  , "Michael McCool"
                  , "Elena Reshetova"
                  ]
                , publisher: "W3C"
                , date: "28 August 2017"
                }
              , "WOT-SECURITY-BEST-PRACTICES" : {
                title: "Web of Things Security and Privacy Best Practices (WIP)"
                , href: "https://github.com/w3c/wot-security/blob/master/wot-security-best-practices.md"
                , authors:  [
                  , "Michael McCool"
                  , "Elena Reshetova"
                  ]
                , publisher: "W3C"
                , date: "WIP"
                }
	      , "WOT-PROTOCOL-BINDING" : {
                  title: "Web of Things Protocol Binding Templates"
                , href: "https://w3c.github.io/wot-binding-templates/"
                , authors:  [
                    "Michael Koster"
                  ]
                , publisher: "W3C"
                , date: "12 January 2018"
                }
	      , "MQTT" : {
                  title: "MQTT Version 5.0"
                , href: "http://docs.oasis-open.org/mqtt/mqtt/v5.0/cos01/mqtt-v5.0-cos01.html"
                , authors:  [
                    "Andrew Banks",
                    "Ed Briggs",
                    "Ken Borgendale",
                    "Rahul Gupta"
                  ]
                , publisher: "OASIS"
                , date: "31 October 2018"
                , status: "Candidate OASIS Standard 01"
                }
              }
            , otherLinks: [
                {
                  key: "Contributors"
                , data: [
                    {
                      value: "In the GitHub repository"
                    , href: "https://github.com/w3c/wot-thing-description/graphs/contributors"
                    }
                  ]
                }
              , {
                  key: "Repository",
                  data: [
                    {
                      value: "We are on GitHub"
                    , href: "https://github.com/w3c/wot-thing-description/"
                    }
                  , {
                      value: "File a bug"
                    , href: "https://github.com/w3c/wot-thing-description/issues"
                    }
                  ]
                }
              ]
            };
    </script>
<style>
.example {
		border-color: #EA1252;
		background: #FEF11E;
		counter-increment: example;
		overflow: auto;
		clear: both;
	}
</style>

<!-- BEGIN EXTRA TABS -->
<script>
  // Add example button selection logic
  document.addEventListener("DOMContentLoaded", () => {
    for (const button of document.querySelectorAll(".ds-selector-tabs .selectors button")) {
      button.onclick = () => {
        const ex = button.closest(".ds-selector-tabs");
        ex.querySelector("button.selected").classList.remove("selected");
        ex.querySelector(".selected").classList.remove("selected");
        button.classList.add('selected');
        ex.querySelector("." + button.dataset.selects).classList.add("selected");
      }
    }
  })
</script>
<style>
  /* example tab selection */
  .ds-selector-tabs {
    padding-bottom: 2em;
  }
  .ds-selector-tabs .selectors {
    padding: 0;
    border-bottom: 1px solid #ccc;
    height: 28px;
  }
  .ds-selector-tabs .selectors button {
    display: inline-block;
    min-width: 54px;
    text-align: center;
    font-size: 11px;
    font-weight: bold;
    height: 27px;
    padding: 0 8px;
    line-height: 27px;
    transition: all,0.218s;
    border-top-right-radius: 2px;
    border-top-left-radius: 2px;
    color: #666;
    border: 1px solid transparent;
  }
  .ds-selector-tabs .selectors button:first-child {
    margin-left: 2px;
  }
  .ds-selector-tabs .selectors button.selected {
    color: #202020 !important;
    border: 1px solid #ccc;
    border-bottom: 1px solid #fff !important;
  }
  .ds-selector-tabs .selectors button:hover {
    background-color: transparent;
    color: #202020;
    cursor: pointer;
  }
  .ds-selector-tabs pre, .ds-selector-tabs table {
    display: none;
  }
  .ds-selector-tabs pre.selected, .ds-selector-tabs table.selected {
    display: block;
  }
  a.playground {
    display: inline-block;
    width: 150px;
    border: 1px solid transparent;
    border-top-right-radius: 2px;
    border-top-left-radius: 2px;
    background-color: rgb(192, 192, 192);
    text-decoration: none;
    font-size: 13px;
    margin-bottom: 10px;
  }
  a[href].playground {
    padding: 4px 0 3px 8px;
    border-bottom: none;
    text-decoration: none;
    color: #666;
  }
</style>
<!-- END EXTRA TABS -->
<!-- ASSERTION HIGHLIGHTING -->
<style>
.rfc2119-assertion {
  background-color: rgb(230,230,230)
}
#td-context-ns-dataschema-dereferenceable-url {
  background-color: yellow;
}
#td-context-ns-dataschema-mandatory {
  background-color: yellow;
}
#td-context-ns-dataschema-map-of-namespaces {
  background-color: yellow;
}
#td-context-ns-dataschema-optional {
  background-color: yellow;
}
#td-context-ns-dataschema-prefix {
  background-color: yellow;
}
#td-context-ns-multilanguage-content-negotiation {
  background-color: yellow;
}
#td-context-ns-securityscheme-dereferenceable-url {
  background-color: yellow;
}
#td-context-ns-securityscheme-mandatory {
  background-color: yellow;
}
#td-context-ns-securityscheme-map-of-namespaces {
  background-color: yellow;
}
#td-context-ns-securityscheme-optional {
  background-color: yellow;
}
#rdf-transformation {
  background-color: yellow;
}
#td-action-names {
  background-color: yellow;
}
#td-action-names_descriptions {
  background-color: yellow;
}
#td-action-names_titles {
  background-color: yellow;
}
#td-arrays {
  background-color: yellow;
}
#td-arrays_scopes {
  background-color: yellow;
}
#td-context-ns-thing {
  background-color: yellow;
}
#td-context-ns-dataschema {
  background-color: yellow;
}
#td-context-ns-dataschema-prefix {
  background-color: yellow;
}
#td-context-ns-securityscheme {
  background-color: yellow;
}
#td-context-ns-securityscheme-prefix {
  background-color: yellow;
}
#td-context-ns-thing-dereferenceable-url {
  background-color: yellow;
}
#td-context-ns-thing-mandatory {
  background-color: yellow;
}
#td-context-ns-thing-map-of-namespaces {
  background-color: yellow;
}
#td-context-ns-thing-optional {
  background-color: yellow;
}
#td-context-ns-thing-prefix {
  background-color: yellow;
}
#td-data-schema-objects {
  background-color: yellow;
}
#td-data-schema-objects_items {
  background-color: yellow;
}
#td-data-schema-objects_properties {
  background-color: yellow;
}
#td-default-alg {
  background-color: yellow;
}
#td-default-context-of-thing {
  background-color: yellow;
}
#td-default-context-of-dataschema {
  background-color: yellow;
}
#td-default-context-of-securityscheme {
  background-color: yellow;
}
#td-default-flow {
  background-color: yellow;
}
#td-default-op-actions {
  background-color: yellow;
}
#td-default-op-events {
  background-color: yellow;
}
#td-default-op-properties {
  background-color: yellow;
}
#td-default-qop {
  background-color: yellow;
}
#td-event-names {
  background-color: yellow;
}
#td-event-names_descriptions {
  background-color: yellow;
}
#td-event-names_titles {
  background-color: yellow;
}
#td-event-names_uriVariables {
  background-color: yellow;
}
#td-op-for-property-readonly {
  background-color: yellow;
}
#td-op-for-property-writeonly {
  background-color: yellow;
}
#td-property-names {
  background-color: yellow;
}
#td-property-names_const {
  background-color: yellow;
}
#td-property-names_scopes {
  background-color: yellow;
}
#td-property-names_security {
  background-color: yellow;
}
#td-property-names_uriVariables {
  background-color: yellow;
}
#td-security-schemes {
  background-color: yellow;
}
#td-serializiation-default-values {
  background-color: yellow;
}
#td-vocab-alg--PoPSecurityScheme {
  background-color: yellow;
}
#td-vocab-anchor--Link {
  background-color: yellow;
}
#td-vocab-at-context--DataSchema {
  background-color: yellow;
}
#td-vocab-at-context--SecurityScheme {
  background-color: yellow;
}
#td-vocab-at-type--SecurityScheme {
  background-color: yellow;
}
#td-vocab-authorization--OAuth2SecurityScheme {
  background-color: yellow;
}
#td-vocab-authorization--PoPSecurityScheme {
  background-color: yellow;
}
#td-vocab-description {
  background-color: yellow;
}
#td-vocab-description--SecurityScheme {
  background-color: yellow;
}
#td-vocab-descriptions--SecurityScheme {
  background-color: yellow;
}
#td-vocab-flow--OAuth2SecurityScheme {
  background-color: yellow;
}
#td-vocab-format--DataSchema {
  background-color: yellow;
}
#td-vocab-format--PoPSecurityScheme {
  background-color: yellow;
}
#td-vocab-identity--CertSecurityScheme {
  background-color: yellow;
}
#td-vocab-identity--PSKSecurityScheme {
  background-color: yellow;
}
#td-vocab-identity--PublicSecurityScheme {
  background-color: yellow;
}
#td-vocab-in--APIKeySecurityScheme {
  background-color: yellow;
}
#td-vocab-in--BearerSecurityScheme {
  background-color: yellow;
}
#td-vocab-in--DigestSecurityScheme {
  background-color: yellow;
}
#td-vocab-in--PoPSecurityScheme {
  background-color: yellow;
}
#td-vocab-name--APIKeySecurityScheme {
  background-color: yellow;
}
#td-vocab-name--CertSecurityScheme {
  background-color: yellow;
}
#td-vocab-name--PSKSecurityScheme {
  background-color: yellow;
}
#td-vocab-name--BasicSecurityScheme {
  background-color: yellow;
}
#td-vocab-name--BearerSecurityScheme {
  background-color: yellow;
}
#td-vocab-name--DigestSecurityScheme {
  background-color: yellow;
}
#td-vocab-name--PoPSecurityScheme {
  background-color: yellow;
}
#td-vocab-names--Thing {
  background-color: yellow;
}
#td-vocab-op--Form {
  background-color: yellow;
}
#td-vocab-proxy--SecurityScheme {
  background-color: yellow;
}
#td-vocab-qop--DigestSecurityScheme {
  background-color: yellow;
}
#td-vocab-refresh--OAuth2SecurityScheme {
  background-color: yellow;
}
#td-vocab-scopes--Form {
  background-color: yellow;
}
#td-vocab-scopes--OAuth2SecurityScheme {
  background-color: yellow;
}
#td-vocab-scheme--SecurityScheme {
  background-color: yellow;
}
#td-vocab-scheme--SecurityScheme_apikey {
  background-color: yellow;
}
#td-vocab-scheme--SecurityScheme_cert {
  background-color: yellow;
}
#td-vocab-scheme--SecurityScheme_oauth2 {
  background-color: yellow;
}
#td-vocab-scheme--SecurityScheme_pop {
  background-color: yellow;
}
#td-vocab-scheme--SecurityScheme_psk {
  background-color: yellow;
}
#td-vocab-scheme--SecurityScheme_public {
  background-color: yellow;
}
#td-vocab-type--DataSchema {
  background-color: yellow;
}
#td-vocab-token--OAuth2SecurityScheme {
  background-color: yellow;
}
#td-vocabulary-default-values {
  background-color: yellow;
}

.at-risk {
  background-color: yellow;
}

</style>
<!-- END ASSERTION HIGHLIGHTING -->

</head>
<body>

  
  <section id="abstract">
  <p>
  This document describes a formal model and a common representation 
  for a Web of Things (WoT) Thing Description. 
  A Thing Description describes the metadata and interfaces of Things, 
  where a Thing is an abstraction of a physical or virtual entity that 
  provides interactions to and participates in the Web of Things. 
  Thing Descriptions provide a set of interactions based on a small vocabulary 
  that makes it possible both to integrate diverse devices and 
  to allow diverse applications to interoperate. 
  Thing Descriptions, by default, are encoded in a JSON format that also allows
  JSON-LD processing. The latter provides a powerful foundation to represent
  knowledge about Things in a machine-understandable way.
  A Thing Description instance can be hosted by the Thing itself or hosted 
  externally when a Thing has resource restrictions (e.g., limited memory space) 
  or when a Web of Things-compatible legacy device is retrofitted 
  with a Thing Description.
  </p>
  </section>

  <section id="sotd">
  <p>
  Implementers need to be aware that this specification is considered unstable. 
  Vendors interested in implementing this specification before it eventually 
  reaches the Candidate Recommendation phase should subscribe to the 
  <a href="https://github.com/w3c/wot-thing-description">repository</a>
  and take part in the discussions.
  </p>
<!--
  <p>This document is governed by the <a id=
  "w3c_process_revision" href=
  "https://www.w3.org/2019/Process-20190301/">1 March 2019
  <abbr title="World Wide Web Consortium">W3C</abbr> Process
  Document</a>.</p>
-->
  <p>
  <span class="at-risk">Text and table entries highlighted with a yellow background
  indicates a feature associated with an at-risk assertion for which
  insufficient implementation experience exists.</span>
  When an entire section is at-risk the words
  "<span class="at-risk">This section is at risk.</span>"
  will be placed at the start of the section and highlighted with a yellow background.</span>
  </p>
   
  </section>

  <section id="introduction" class="informative">
  <h1>Introduction</h1>
  <p>
  The Thing Description (TD) model is a central building block in the W3C Web of
  Things (WoT) and can be considered as the entry point of a Thing
  (much like the <i>index.html</i> of a Web site). A TD instance has four main
  components: textual metadata about the Thing itself, a collection of affordances
  to interact with the Thing on the basis of WoT's high-level interaction paradigm
  (involving the classes <code>Property</code>, <code>Action</code>, and <code>Event</code>), 
  schemas for the information exchanged with the Thing for machine-understandability, 
  and, finally, Web links to express any formal or informal relation to other Things. 
  </p>
  <p>
  <code>Property</code> affordances can be used for sensing and controlling parameters,
  such as getting the current value or setting an operation state.
  <code>Action</code> affordances model invocation of physical (and hence time-consuming) processes,
  but can also be used to abstract RPC-like calls of existing platforms. 
  <code>Event</code> affordances are used for the push model of communication where notifications,
  discrete events, or streams of values are sent asynchronously to the receiver.
  In general, the TD provides metadata for different communication bindings 
  identified by URI schemes [[iana-uri-schemes]] (e.g., <code>http</code>, <code>coap</code>, etc.),
  content types based on media types (e.g., "application/json", "application/xml", "application/cbor",
  "application/exi" etc.) [[iana-media-types]], and security mechanisms (for authentication,
  authorization, confidentiality, etc.).
  Serialization of TD instances is based on JSON [[rfc8259]], where JSON keys refers to terms of
  the TD core vocabulary, as defined in this specification document. In addition the JSON serialization of TDs 
  follows the syntax of JSON-LD 1.1 [[json-ld11]] to enable context extension and RDF processing.
  </p>
  <p>
  Example 1 shows a TD instance with its different equivalent representation options (<i>Simple</i>, <i>Full (JSON-LD 1.1)</i>, <i>RDF</i>) and
  illustrates the TD model's <code>Property</code>, <code>Action</code>,
  and <code>Event</code> classes by describing a lamp Thing with the name <i>MyLampThing</i>. 
  </p>
<aside class="example ds-selector-tabs changed" id="simple-thing-description-sample" title="Thing Description Sample">
    <div class="selectors">
      <button class="selected" data-selects="ex-original">Simple</button>
      <button data-selects="ex-full">Full (JSON-LD 1.1)</button>
      <button data-selects="ex-rdf">RDF</button>
    </div>
    <pre class="ex-original selected">{
    "id": "urn:dev:wot:com:example:servient:lamp",
    "name": "MyLampThing",
    "securityDefinitions": {
        "basic_sc": {"scheme": "basic", "in":"header"}
    },
    "security": ["basic_sc"],
    "properties": {
        "status" : {
            "type": "string",
            "forms": [{"href": "https://mylamp.example.com/status"}]
        }
    },
    "actions": {
        "toggle" : {
            "forms": [{"href": "https://mylamp.example.com/toggle"}]
        }
    },
    "events":{
        "overheating":{
            "data": {"type": "string"},
            "forms": [{
                "href": "https://mylamp.example.com/oh",
                "subprotocol": "longpoll"
            }]
        }
    }
}</pre>
    <pre class="ex-full">{
    "@context": "http://www.w3.org/ns/td",
    "id": "urn:dev:wot:com:example:servient:lamp",
    "name": "MyLampThing",
    "securityDefinitions": {
        "basic_sc": {"scheme": "basic", "in":"header"}
    },
    "security": ["basic_sc"],
    "properties": {
        "status" : {
            "type": "string",
            "forms": [{
				"href": "https://mylamp.example.com/status",
                "contentType": "application/json",
                "op": ["readproperty", "writeproperty"]
			}]
        }
    },
    "actions": {
        "toggle" : {
            "idempotent" : false,
            "safe" : false,
            "forms": [{
				"href": "https://mylamp.example.com/toggle",
				"contentType": "application/json",
                "op": "invokeaction"
			}]
        }
    },
    "events":{
        "overheating":{
            "data": {"type": "string"},
            "forms": [{
                "href": "https://mylamp.example.com/oh",
				"contentType": "application/json",
                "subprotocol": "longpoll",
                "op": "subscribeevent"
            }]
        }
    }
}</pre>
<pre class="ex-rdf">&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#actions&gt; _:b0 .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#events&gt; _:b2 .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#name&gt; &quot;MyLampThing&quot; .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#properties&gt; _:b5 .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#securityDefinitions&gt; _:b7 .
_:b0 &lt;http://www.w3.org/ns/td#forms&gt; _:b1 .
_:b0 &lt;http://www.w3.org/ns/td#idempotent&gt; &quot;false&quot;^^&lt;http://www.w3.org/2001/XMLSchema#boolean&gt; .
_:b0 &lt;http://www.w3.org/ns/td#safe&gt; &quot;false&quot;^^&lt;http://www.w3.org/2001/XMLSchema#boolean&gt; .
_:b1 &lt;http://www.w3.org/ns/td#contentType&gt; &quot;application/json&quot; .
_:b4 &lt;http://www.w3.org/ns/td#op&gt; &quot;invokeaction&quot; .
_:b1 &lt;http://www.w3.org/ns/td#href&gt; &quot;https://mylamp.example.com/toggle&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b2 &lt;http://www.w3.org/ns/td#data&gt; _:b3 .
_:b2 &lt;http://www.w3.org/ns/td#forms&gt; _:b4 .
_:b3 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#StringSchema&gt; .
_:b4 &lt;http://www.w3.org/ns/td#contentType&gt; &quot;application/json&quot; .
_:b4 &lt;http://www.w3.org/ns/td#op&gt; &quot;subscribeevent&quot; .
_:b4 &lt;http://www.w3.org/ns/td#href&gt; &quot;https://mylamp.example.com/oh&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b4 &lt;http://www.w3.org/ns/td#subprotocol&gt; &quot;longpoll&quot; .
_:b5 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#StringSchema&gt; .
_:b5 &lt;http://www.w3.org/ns/td#forms&gt; _:b6 .
_:b6 &lt;http://www.w3.org/ns/td#contentType&gt; &quot;application/json&quot; .
_:b4 &lt;http://www.w3.org/ns/td#op&gt; &quot;readproperty&quot; .
_:b4 &lt;http://www.w3.org/ns/td#op&gt; &quot;writeproperty&quot; .
_:b6 &lt;http://www.w3.org/ns/td#href&gt; &quot;https://mylamp.example.com/status&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
</pre>
</aside>


  <p>
  Based on the content that can be seen in the <i>Simple</i> tab, 
  we know there exists one <code>Property</code> <a>interaction resource</a> 
  with the name <i>status</i>. 
  In addition, 
  information is provided to indicate that this Property is accessible via 
  (the secure form of) the HTTP protocol with a GET method 
  at the URI <code>https://mylamp.example.com/status</code> 
  (announced within the <code>forms</code> structure by the 
  <code>href</code> name), and will return a string-based status value.
  The use of the GET method is not stated explicitly, 
  but is one of the default assumptions defined by this document and explained in [[wot-protocol-binding]].
  </p>
  <p>
  In a similar manner, an <code>Action</code> is specified to toggle the
  switch status using the POST method applied to the 
  <code>https://mylamp.example.com/toggle</code> resource,
  where POST is again a default assumption for invoking Actions.
  </p>
  <p>
  The <code>Event</code> pattern enables a mechanism for asynchronous messages
  to be sent by a Thing.
  Here, a subscription to be notified upon a possible overheating event 
  of the lamp can be obtained by using the HTTP with its long polling
  sub-protocol at <code>https://mylamp.example.com/oh</code>.
  </p>
 
  <p>
  This example also specifies the <code>basic</code> security scheme, 
  requiring a username and password for access.
  Note that a security scheme is first given a name in a 
  <code>securityDefinition</code> and then activated by specifying
  that name in a <code>security</code> section.
  In combination with the use of the HTTP protocol this example
  demonstrates the use of HTTP Basic Authentication.
  Specification of at least one security scheme at the top level is mandatory,
  and gives the default access requirements for every resource.
  However, security schemes can also be specified per-form,
  with configurations given at the form level overriding configurations given at the Thing level,
  allowing for the specification of fine-grained access control.
  It is also possible to use a special <code>nosec</code> security scheme to
  indicate that no access control mechanisms are used.
  Additional examples will be provided later.
  </p>
 
  <p>
    The TD in the <i>Simple</i> tab reflects some additional defined default assumptions 
    that are not explicitly described. 
    For example, the content type of the 
    exchange format of the interactions is assumed to be JSON 
    (=<code>contentType</code>). 
    Specifically, the TD specification defines vocabulary terms 
    (e.g., <code>contentType</code>, <code>op</code>, <code>@contex</code>) that have default values. 
    If one or more of these vocabulary terms are not explicitly used in a Thing Description 
    instance we will call it <i>Simple</i> and a Thing Description processor (e.g. based on a raw JSON parser) follows default 
    assumptions for interpretation as defined in this specification. 
    The <i>Full (JSON-LD 1.1)</i> tab shows the identical information of the 
    simple form of the Thing Description instance, but includes these mentioned implicit vocabulary terms with its default values.
    A TD instance that contains all corresponding mandatory vocabulary terms, we will call this representation as <i>Full</i> 
    and can be passed, e.g, directly to a JSON-LD 1.1 processor for semantic interpretation. The <i>RDF</i> tab just shows 
    the RDF triples from the JSON-LD 1.1 representation (as defined in [[json-ld11]]).   
</p>

  <p>
        The Thing Description offers the possibility to add contextual definitions
        in some namespace. This mechanism can be used to integrate additional semantics
        to the content of the Thing Description instance, provided that formal knowledge,
        e.g. logic rules for a specific domain of application, can be found under the
        given namespace. Contextual information can also help specify some configurations and 
        behavior of the underlying communication protocols declared in the <code>forms</code> field.
        Example 2 extends the TD sample from Example 1 by introducing a <code>@context</code>
        key to declare the prefix <code>htv</code> as referring to the HTTP vocabulary namespace.
        This namespace is used here to specify explicitly the HTTP methods for the property and
        action within the <code>forms</code>. The declaration mechanism inside some
        <code>@context</code> is specified by JSON-LD. A TD instance complies to version 1.1 of
        this specification [[json-ld11]]. The TD instance can be also processed as an RDF
        document (details are given in <a href="#note-jsonld11-processing"></a>).
  </p>

 <aside class="example ds-selector-tabs changed" id="thing-description-full-serialization" title="Thing Description with context extension">
        <div class="selectors">
                <button class="selected" data-selects="ex-original">Simple</button>
                <button data-selects="ex-full">Full (JSON-LD 1.1)</button>
                <button data-selects="ex-rdf">RDF</button>
              </div>
              <pre class="ex-original selected">
    {
        "@context": [
            "http://www.w3.org/ns/td",
            {"htv": "http://www.w3.org/2011/http#"}
        ],
        "id": "urn:dev:wot:com:example:servient:lamp",
        "name": "MyLampThing",
        "securityDefinitions": {"basic_sc": {
            "scheme": "basic",
            "in": "header"
        }},
        "security": ["basic_sc"],
        "properties": {
            "status": {
                "type": "string",
                "forms": [{
                    "href": "https://mylamp.example.com/status",
                    "htv:methodName": "GET"
                }]
            }
        },
        "actions": {
            "toggle": {
                "forms": [{
                    "href": "https://mylamp.example.com/toggle",
                    "http:methodName": "POST"
                }]
            }
        },
        "events": {
            "overheating": {
                "data": {"type": "string"},
                "forms": [{
                    "href": "https://mylamp.example.com/oh",
                    "subprotocol": "longpoll"
                }]
            }
        }
    }</pre>
              <pre class="ex-full">
    {
        "@context": [
            "http://www.w3.org/ns/td",
            {"htv": "http://www.w3.org/2011/http#"}
        ],
        "id": "urn:dev:wot:com:example:servient:lamp",
        "name": "MyLampThing",
        "securityDefinitions": {"basic_sc": {
            "scheme": "basic",
            "in": "header"
        }},
        "security": ["basic_sc"],
        "properties": {
            "status": {
                "type": "string",
                "forms": [{
                    "href": "https://mylamp.example.com/status",
                    "htv:methodName": "GET",
                    "contentType": "application/json",
                    "op": ["readproperty", "writeproperty"]
                }]
            }
        },
        "actions": {
            "toggle": {
                "idempotent": false,
                "safe": false,
                "forms": [{
                    "href": "https://mylamp.example.com/toggle",
                    "htv:methodName": "POST",
                    "contentType": "application/json",
                    "op": "invokeaction"
                }]
            }
        },
        "events": {
            "overheating": {
                "data": {"type": "string"},
                "forms": [{
                    "href": "https://mylamp.example.com/oh",
                    "subprotocol": "longpoll",
                    "contentType": "application/json",
                    "op": "subscribeevent"
                }]
            }
        }
    }</pre>
    <pre class="ex-rdf">&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#actions&gt; _:b0 .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#events&gt; _:b2 .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#name&gt; &quot;MyLampThing&quot; .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#properties&gt; _:b5 .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;http://www.w3.org/ns/td#securityDefinitions&gt; _:b7 .
_:b0 &lt;http://www.w3.org/ns/td#forms&gt; _:b1 .
_:b0 &lt;http://www.w3.org/ns/td#idempotent&gt; &quot;false&quot;^^&lt;http://www.w3.org/2001/XMLSchema#boolean&gt; .
_:b0 &lt;http://www.w3.org/ns/td#safe&gt; &quot;false&quot;^^&lt;http://www.w3.org/2001/XMLSchema#boolean&gt; .
_:b1 &lt;http://www.w3.org/2011/http#methodName&gt; &quot;POST&quot; .
_:b1 &lt;http://www.w3.org/ns/td#contentType&gt; &quot;application/json&quot; .
_:b1 &lt;http://www.w3.org/ns/td#op&gt; &quot;invokeaction&quot; .
_:b1 &lt;http://www.w3.org/ns/td#href&gt; &quot;https://mylamp.example.com/toggle&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b2 &lt;http://www.w3.org/ns/td#data&gt; _:b3 .
_:b2 &lt;http://www.w3.org/ns/td#forms&gt; _:b4 .
_:b3 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#StringSchema&gt; .
_:b4 &lt;http://www.w3.org/ns/td#contentType&gt; &quot;application/json&quot; .
_:b1 &lt;http://www.w3.org/ns/td#op&gt; &quot;subscribeevent&quot; .
_:b4 &lt;http://www.w3.org/ns/td#href&gt; &quot;https://mylamp.example.com/oh&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b4 &lt;http://www.w3.org/ns/td#subprotocol&gt; &quot;longpoll&quot; .
_:b5 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#StringSchema&gt; .
_:b5 &lt;http://www.w3.org/ns/td#forms&gt; _:b6 .
_:b6 &lt;http://www.w3.org/2011/http#methodName&gt; &quot;GET&quot; .
_:b6 &lt;http://www.w3.org/ns/td#contentType&gt; &quot;application/json&quot; .
_:b1 &lt;http://www.w3.org/ns/td#op&gt; &quot;readproperty&quot; .
_:b1 &lt;http://www.w3.org/ns/td#op&gt; &quot;writeproperty&quot; .
_:b6 &lt;http://www.w3.org/ns/td#href&gt; &quot;https://mylamp.example.com/status&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .  
    </pre>
          </aside>

  </section>

  <section id="terminology"> 
  <h2>Terminology</h2>
  <p>Generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: 
  <dfn data-lt="Things">Thing</dfn>, 
  <dfn data-lt="Thing Descriptions">Thing Description</dfn> 
    (in short <dfn>TD</dfn>), 
  <dfn>Web of Things</dfn> (in short <b><i>WoT</i></b>),  
  <dfn>WoT Interface</dfn> etc.
  </p>
  </section>

  <section>
  <h1>Namespaces</h1>
  <p>
  The namespace for the W3C Thing Description vocabulary as defined in 
  this document is <a href="http://www.w3.org/ns/td">http://www.w3.org/ns/td</a>. 
  </p> 
  <p>
  Using content negotiation,  this namespace serves either the TD ontology file (Turtle) or the TD context file (JSON-LD).
  </p>
  

  </section>

  <section>
  <h1>Conformance</h1>
  <p>
  As well as all sections marked as non-normative, 
  all authoring guidelines, diagrams, examples, and notes in this specification 
  are non-normative. 
  Everything else in this specification is normative.
  </p>
  <p>
  The key words 
  <em title="MUST" class="rfc2119">MUST</em>, 
  <em title="MUST NOT" class="rfc2119">MUST NOT</em>, 
  <em title="REQUIRED" class="rfc2119">REQUIRED</em>, 
  <em title="SHOULD" class="rfc2119">SHOULD</em>, 
  <em title="SHOULD NOT" class="rfc2119">SHOULD NOT</em>, 
  <em title="RECOMMENDED" class="rfc2119">RECOMMENDED</em>, 
  <em title="MAY" class="rfc2119">MAY</em>,
  and <em title="OPTIONAL" class="rfc2119">OPTIONAL</em> 
  in this specification are to be interpreted as described in [[!RFC2119]].
  </p>
  <p>
  A Thing Description instance complies with this specification if it follows 
  the normative statements in Section 
  <a href="#sec-vocabulary-definition"></a>
  and Section 
  <a href="#sec-td-serialization"></a> 
  regarding Thing Description serialization.
  </p>
  <p>
  A JSON Schema [[?JSON-SCHEMA-VALIDATION]] is provided in Annex 
  <a href="#json-schema-4-validation"></a> 
  to validate Thing Description instances based on JSON serialization.
  </p>

  <p class="ednote">
  In the future some information about RDF validation will be provided.   
  </p>

  </section>


  <section id="sec-vocabulary-definition">
    <h1>Information Model</h1>
    <!-- h1>Vocabulary</h1 -->
    <p>This section introduces the <dfn>Thing Description information model</dfn>. 
      The Thing Description Information model serves as the conceptual basis 
      for the serialization and processing of Thing Description described 
      in later sections in this document.<p>

      <section>
      <h2>Overview</h2>
    
      <p>
      The W3C Thing Description provides a set of vocabulary for describing 
      physical and virtual Things. In general, the Thing Description vocabulary set is grouped in three modules: 
        <ul>
            <li>the core Thing Description vocabulary reflecting WoT's paradigm of 
                    <code>Properties</code>, <code>Actions</code>, and <code>Events</code> affordances (also see [[!WOT-ARCHITECTURE]])</li>
            <li> the data schema vocabulary reflecting a subset of the terms defined in 
                    JSON Schema [[?JSON-SCHEMA-VALIDATION]],</li>
            <li>      and the security vocabulary used to define security mechanism 
                    configuration requirements. </li>                    
        </ul>

      </p>


      <p>
      An overview of this vocabulary with its class context and class relation 
      is given by the following three figures. 
      <dfn>Vocabulary term</dfn>s identify members within the TD information model.
      Both the terms shown on the left side of "<code> : </code>" (i.e. colon) in the boxes 
      representing classes and the terms labelling the arrows constitute 
      the vocabulary terms of Thing Description information model.
      Please note that the figures reflect the vocabulary terms and structure 
      as they would be used in a Thing Description 
      instance (see Section <a href="#sec-td-serialization"></a>).
       
      </p>
      <!--<p><a href="http://visualdataweb.de/webvowl/#iri=https://rawgit.com/w3c/wot-thing-description/TD-JSON-LD-1.1/ontology/td.ttl">Click here for the visualization</a></p>-->
     

      <p class="ednote">
            The following diagrams are automatically generated from the ontology files. The layout will be improved in one of the next TD updates.
             </p>


    <figure id="td-core-model">
      <img src="visualization/td.svg" alt="TD core model figure"/>
      <figcaption>TD core model (<a href="visualization/td.svg">Click SVG file</a>)</figcaption>
    </figure>
    
    <figure id="td-data-schema-model">
      <img src="visualization/json-schema.svg" alt="TD data schema model figure"/>
      <figcaption>JSON schema model (<a href="visualization/json-schema.svg">Click SVG file</a>)</figcaption>
    </figure>
    
    <figure id="td-security-model">
      <img src="visualization/wot-security.svg" alt="TD security model figure"/>
      <figcaption>WoT security model (<a href="visualization/wot-security.svg">Click SVG file</a>)</figcaption>
    </figure>
    
    <figure id="web-linking-model">
      <img src="visualization/web-linking.svg" alt="Web linking model figure"/>
      <figcaption>Web linking model (<a href="visualization/web-linking.svg">Click SVG file</a>)</figcaption>
    </figure>
    
    
      <p>A detailed description of the vocabulary of the TD core model, 
        TD data schema model and TD security model is given in the following 
        sub-sections.</p>

      <p>
            <span class="rfc2119-assertion" id="td-vocabulary">
                    All vocabulary restrictions noted in tables in Section <a href="#sec-core-vocabulary-definition"></a>, <a href="#sec-data-schema-vocabulary-definition"></a>, and <a href="#sec-security-vocabulary-definition"></a> MUST be followed, 
                    including mandatory items. 
                    </span>
      </p>

      <p>
        The <a href="#sec-td-serialization"></a> section explains how to serialize these vocabulary terms to a Thing Description instance using a 
        JSON-based representation. It also defines default values for some mandatory vocabulary and explains the options how they can be serialized.
      </p>
      

      <section id="sec-default-values">
        <h3>Default Values for Vocabulary Terms</h3>
        <p>
        <span class="rfc2119-assertion" id="td-vocabulary-default-values">
        When values are not present for certain mandatory <a>vocabulary term</a>s in an instance of <a>Thing Description information model</a>, default values MUST be assumed as shown in the following table.
        </span>
        </p>
        <table class="def">
            <thead>
                <tr>
                    <th><a>Vocabulary term</a></th>
                    <th>Default value</th>
                    <th>Context</th>
                </tr>
            </thead>
            <tbody>
                <tr class="rfc2119-default-assertion" id="td-default-context-of-thing">
                    <td>
                        <code>@context</code>
                    </td>
                    <td>"http://www.w3.org/ns/td"</td>
                    <td><code>Thing</code></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-contentType">
                    <td>
                        <code>contentType</code>
                    </td>
                    <td>application/json</td>
                    <td></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-safe">
                    <td>
                        <code>safe</code>
                    </td>
                    <td>false</td>
                    <td></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-idempotent">
                    <td>
                        <code>idempotent</code>
                    </td>
                    <td>false</td>
                    <td></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-op-properties">
                    <td>
                        <code>op</code>
                    </td>
                    <td>Array of strings with values <code>readproperty</code> followed by 
                        <code>writeproperty</code></td>
                    <td><code>PropertyAffordance</code></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-op-actions">
                    <td>
                        <code>op</code>
                    </td>
                    <td><code>invokeaction</code></td>
                    <td><code>ActionAffordance</code></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-op-events">
                    <td>
                        <code>op</code>
                    </td>
                    <td><code>subscribeevent</code></td>
                    <td><code>EventAffordance</code></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-in-1">
                    <td>
                        <code>in</code>
                    </td>
                    <td><code>header</code></td>
                    <td><code>BasicSecurityScheme</code></br>
                        <code>DigestSecurityScheme</code></br>
                        <code>BearerSecurityScheme</code></br>
                        <code>PoPSecurityScheme</code></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-in-2">
                    <td>
                        <code>in</code>
                    </td>
                    <td><code>query</code></td>
                    <td><code>APIKeySecurityScheme</code></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-qop">
                    <td>
                        <code>qop</code>
                    </td>
                    <td><code>auth</code></td>
                    <td><code>DigestSecurityScheme</code></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-alg">
                    <td>
                        <code>alg</code>
                    </td>
                    <td><code>ES256</code></td>
                    <td><code>BearerSecurityScheme</code></br>
                        <code>PoPSecurityScheme</code></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-format">
                    <td>
                        <code>format</code>
                    </td>
                    <td><code>jwt</code></td>
                    <td><code>BearerSecurityScheme</code></br>
                        <code>PoPSecurityScheme</code></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-flow">
                    <td>
                        <code>flow</code>
                    </td>
                    <td></code>implicit</code></td>
                    <td><code>OAuth2SecurityScheme</code></td>
                </tr>
            </tbody>
        </table>
      </section>

      </section>
    
      <section id="sec-core-vocabulary-definition">
      <h2>Core Vocabulary Definition</h2>
      <p>In the following tables, 
      a type given as "map of X" should be interpreted as defining
      an unordered collection of name-value pairs associating unique names
      with values of type X.
      Likewise a type given as "array of X" should be interpreted as defining an ordered
      collection of instances of type X. 
      </p>

      <p class="ednote" title="Security Definitions Mandatory">
      Note that for now <code>securityDefinitions</code> are mandatory at the top level of a <code>Thing</code>
      since there needs to be
      at least one definition available for use in the top-level mandatory <code>security</code>
      block.  However, a future extension may allow in-place anonymous definitions
      within <code>security</code> blocks in which case this requirement may be relaxed.
      </p>

        <section><h3><code>Thing</code></h3><p>Describes a physical and/or virtual Thing (may represent one or more physical and/or virtual Things) in the Web of Things context.</p><p>When a concrete Thing is defined in a Thing Description, it is called a <dfn>thing resource</dfn>.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-at-context--Thing"><td><code>@context</code></td><td>Known from JSON-LD [[!json-ld]], <code>@context</code> is used to define short-hand names called terms that are used throughout a TD document.</td><td>yes</td><td>string or array</td></tr><tr class="rfc2119-table-assertion" id="td-vocab-at-type--Thing"><td><code>@type</code></td><td>Known from JSON-LD [[!json-ld]], <code>@type</code> is used to state that a thing resource is an instance of a class.<br/><br/> Each string in the value array represents a class.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr><tr class="rfc2119-table-assertion" id="td-vocab-id--Thing"><td><code>id</code></td><td>unique identifier of the Thing (URI, e.g. custom URN).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr><tr class="rfc2119-table-assertion" id="td-vocab-name--Thing"><td><code>name</code></td><td>Name of the Thing.</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-description--Thing"><td><code>description</code></td><td>Provides additional (human-readable) information based on a default language.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-descriptions--Thing"><td><code>descriptions</code></td><td>Can be used to support (human-readable) information in different languages.</td><td>no</td><td><a href="#multilanguage"><code>MultiLanguage</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-version--Thing"><td><code>version</code></td><td>Provides version information.</td><td>no</td><td><a href="#versioninfo"><code>VersionInfo</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-created--Thing"><td><code>created</code></td><td>Provides information when the TD instance was created.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-lastModified--Thing"><td><code>lastModified</code></td><td>Provides information when the TD instance was last modified.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-support--Thing"><td><code>support</code></td><td>Provides information about the TD maintainer (e.g., author, link or telephone number to get support, etc).</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-base--Thing"><td><code>base</code></td><td>Define the base URI that is used for all relative URI references throughout a TD document. In TD instances, all relative URIs are resolved relative to the base URI using the algorithm defined in [[!RFC3986]].<br/><br/><code>base</code> does not affect the URIs used in <code>@context</code> and the IRIs [[?RFC3987]] used within Linked Data [[?LINKED-DATA]] graphs that are relevant when semantic processing is applied to TD instances.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-properties--Thing"><td><code>properties</code></td><td>All Property-based interaction affordance of the Thing.</td><td>no</td><td>map of <a href="#propertyaffordance"><code>PropertyAffordance</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-actions--Thing"><td><code>actions</code></td><td>All Action-based interaction affordance of the Thing.</td><td>no</td><td>map of <a href="#actionaffordance"><code>ActionAffordance</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-events--Thing"><td><code>events</code></td><td>All Event-based interaction affordance of the Thing.</td><td>no</td><td>map of <a href="#eventaffordance"><code>EventAffordance</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-links--Thing"><td><code>links</code></td><td>Provides Web links to arbitrary resources that relate to the specified Thing Description.</td><td>no</td><td>array of <a href="#link"><code>Link</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-forms--Thing"><td><code>forms</code></td><td>Indicates one or more endpoints at which operation(s) on this resource are accessible. In this version of TD, all operations that can be described at the Thing level are concerning how to interact with the Thing's <a href="#property">Property</a> <a>interaction resources</a> collectively at once.</td><td>no</td><td>array of <a href="#form"><code>Form</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-security--Thing"><td><code>security</code></td><td>Set of security definition names, chosen from those defined in securityDefinitions.  These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level.</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-securityDefinitions--Thing"><td><code>securityDefinitions</code></td><td>Set of named security configurations (definitions only).  Not actually applied unless names are used in a security section.</td><td>yes</td><td><a href="#securityscheme"><code>SecurityScheme</code></a></td></tr></tbody></table>
<p>
     <span class="rfc2119-assertion" id="td-context-ns-thing-mandatory">The mandatory
     context definition of the string <code>"http://www.w3.org/ns/td"</code> MUST be 
     the first item in the <code>@context</code> array.</span>
     <span class="rfc2119-assertion" id="td-context-ns-thing-optional">The mandatory
     context definition MAY be followed by one or more context definitions as strings or 
     objects.</span>
</p>
<p>
     <span class="rfc2119-assertion" id="td-context-ns-thing-dereferenceable-url">
     As suggested in JSON-LD [[!json-ld]] specification, if a context definition is 
     a string, it SHOULD be a dereferenceable URL.
     </span>
     <span class="rfc2119-assertion" id="td-context-ns-thing-map-of-namespaces">
     Likewise, if a context definition is an object, it SHOULD be a map of namespaces, 
     in which keys are namespace prefixes. 
     </span>
     <span class="rfc2119-assertion" id="td-context-ns-thing-prefix">Each optional
     namespace specified in the <code>@context</code> array of a Thing MUST be bound 
     to an unique prefix.</span>
</p>
<p id="meta-interactions-of-thing">Similar to <a href="#propertyaffordance" class="sec-ref">PropertyAffordance</a>, 
    <a href="#actionaffordance" class="sec-ref">ActionAffordance</a> and 
    <a href="#eventaffordance" class="sec-ref">EventAffordance</a> classes, all of which are 
    subclasses of <a href="#interactionaffordance" class="sec-ref">
    InteractionAffordance</a>, the definition of Thing class also contains 
    the <code>forms</code> term. 
    <span class="rfc2119-assertion" id="td-op-for-thing">
    When a <code>forms</code> term member is present in a Thing instance, 
    the value(s) in the <code>op</code> term member of the <code>forms</code> MUST be one or more of 
    <code>readallproperties</code>, <code>writeallproperties</code>, 
    <code>readmultipleproperties</code> or <code>writemultipleproperties</code>.
    </span>
    (See <a href="#td-forms-readall-example"> an example</a> for an usage of <code>form</code> in a <a>thing resource</a>.)
</p>
<p>
    For <code>readallproperties</code> operation's output, 
    <code>readmultipleproperties</code> operation's output,
    <code>writeallproperties</code> operation's input and <code>writemultipleproperties</code>
    operation's input, payloads are assigned an object type schema with its 
    properties equal to the Thing's property resources.
    For <code>readmultipleproperties</code> operation's input, payloads are
    assigned a string array type schema with its items each equal to one of the names of
    The Thing's property resources.
</p>
</section>
<section><h3><code>InteractionAffordance</code></h3><p>Three interaction affordance are defined as subclasses: Property-, Action- and Event-based affordances (also see [[!WOT-ARCHITECTURE]]). Interactions between Things can be as simple as one Thing accessing another Thing's data to get or (in the case the data is also writable) change the representation of data such as metadata, status or mode. A Thing may also be interested in getting asynchronously notified of future changes in another Thing, or may want to initiate a process served in another Thing that may take some time to complete and monitor the progress. Interactions between Things may involve exchanges of data between them. This data can be either given as input by the client Thing, returned as output by the server Thing or both.</p><p>When a concrete Property-, Action- or Event-based affordance is defined in a Thing Description, it is called an <dfn>interaction resource</dfn>.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-at-type--InteractionAffordance"><td><code>@type</code></td><td>Known from JSON-LD [[!json-ld]], <code>@type</code> is used to state that an <a>interaction resource</a> is an instance of a class.<br/><br/> Each string in the value array represents a class.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr><tr class="rfc2119-table-assertion" id="td-vocab-title--InteractionAffordance"><td><code>title</code></td><td>Provides a human-readable title (e.g., display a text for UI representation) of the interaction pattern based on a default language.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-titles--InteractionAffordance"><td><code>titles</code></td><td>Provides multi-language human-readable titles (e.g., display a text for UI representation in different languages) of the interaction pattern.</td><td>no</td><td><a href="#multilanguage"><code>MultiLanguage</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-description--InteractionAffordance"><td><code>description</code></td><td>Provides additional (human-readable) information based on a default language.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-descriptions--InteractionAffordance"><td><code>descriptions</code></td><td>Can be used to support (human-readable) information in different languages.</td><td>no</td><td><a href="#multilanguage"><code>MultiLanguage</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-forms--InteractionAffordance"><td><code>forms</code></td><td>Indicates one or more endpoints at which operation(s) on this resource are accessible.</td><td>yes</td><td>array of <a href="#form"><code>Form</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-uriVariables--InteractionAffordance"><td><code>uriVariables</code></td><td>Define URI template variables as collection based on DataSchema declarations.</td><td>no</td><td>map of <a href="#dataschema"><code>DataSchema</code></a></td></tr></tbody></table><p>The class <code>InteractionAffordance</code> has the following subclasses:</p><ul><li><a href="#actionaffordance"><code>ActionAffordance</code></a></li>
<li><a href="#eventaffordance"><code>EventAffordance</code></a></li>
<li><a href="#propertyaffordance"><code>PropertyAffordance</code></a></li></ul>
<p>
    <span class="rfc2119-assertion" id="td-unique-identifiers">
        Each instance of a <code>Property</code>, <code>Action</code>,
        and <code>Event</code> class MUST have an identifier that is
        unique within the context of a Thing Description document.
    </span>

</p>

<section><h4><code>PropertyAffordance</code></h4><p>Properties expose internal state of a Thing that can be directly retrieved (get) and optionally modified (set). In addition, Things can also choose to make Properties observable by pushing the new state (not an event) after a change; this must follow eventual consistency.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-observable--PropertyAffordance"><td><code>observable</code></td><td>A hint that indicates whether a remote client can subscribe to ("observe") the Property, to receive change notifications or periodic updates (true/false).</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#boolean"><code>boolean</code></a></td></tr></tbody></table>
<p>Property class is a subclass of the class <a href="#interactionaffordance" 
    class="sec-ref">InteractionAffordance</a>. 
    <span class="rfc2119-assertion" id="td-op-for-property">
    When a <code>forms</code> term member is present in a Property instance, 
    the value(s) in the <code>op</code> term member of the <code>forms</code> MUST be one or more of 
    <code>readproperty</code>, <code>writeproperty</code>, <code>observeproperty</code> or <code>unobserveproperty</code>.
    </span>
</p>
<p class="note">
    Property instances are also instances of the class
    <a href="#dataschema" class="sec-ref">DataSchema</a>. Therefore,
    it can contain the <code>type</code>, <code>unit</code>,
    <code>readOnly</code> and <code>writeOnly</code> members, among
    others.
</p>
<p>
    <span class="rfc2119-assertion" id="td-op-for-property-readonly">
    When the value of <code>readOnly</code> member is true in an instance of PropertyAffordance, 
    the value(s) in the <code>op</code> term member of the <code>forms</code> 
    MUST NOT contain <code>writeproperty</code>.
    </span>
    Similarly, 
    <span class="rfc2119-assertion" id="td-op-for-property-writeonly">
    when the value of <code>writeOnly</code> member is true in an instance of PropertyAffordance, 
    the value(s) in the <code>op</code> term member of the <code>forms</code> 
    MUST NOT contain <code>readproperty</code>.
    </span>
</p>
</section>
<section><h4><code>ActionAffordance</code></h4><p>Actions offer functions of the Thing. These functions may manipulate the internal state of a Thing in a way that is not possible through setting Properties. Examples are changing internal state that is not exposed as a Property, changing multiple Properties, changing Properties over time or with a process that should not be disclosed. Actions may also be pure functions, that is, they may not use any internal state at all, and may simply process input data and return a result that directly depends only on the input given.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-input--ActionAffordance"><td><code>input</code></td><td>Used to define the input data schema of the action.</td><td>no</td><td><a href="#dataschema"><code>DataSchema</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-output--ActionAffordance"><td><code>output</code></td><td>Used to define the output data schema of the action.</td><td>no</td><td><a href="#dataschema"><code>DataSchema</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-safe--ActionAffordance"><td><code>safe</code></td><td>Signals if the action is safe (=true) or not. Used to signal if there is no internal state (cf. resource state) is changed when invoking an Action. In that case responses can be cached as example.</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#boolean"><code>boolean</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-idempotent--ActionAffordance"><td><code>idempotent</code></td><td>Indicates whether the action is idempotent (=true) or not. Informs whether the action can be called repeatedly with the same result, if present, based on the same input.</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#boolean"><code>boolean</code></a></td></tr></tbody></table>
<p>Action class is a subclass of the class <a href="#interactionaffordance" 
    class="sec-ref">InteractionAffordance</a>.
    <span class="rfc2119-assertion" id="td-op-for-action">
    When a <code>forms</code> term member is present in an Action instance, 
    the value in the <code>op</code> term member of the <code>forms</code> MUST be 
    <code>invokeaction</code>.
    </span>
</p>
</section>
<section><h4><code>EventAffordance</code></h4><p>The Event Interaction Pattern describes event sources that asynchronously push messages. Here not state, but state transitions (events) are communicated (e.g., "clicked"). Events may be triggered by internal state changes that are not exposed as Properties. Events usually follow strong consistency, where messages need to be queued to ensure eventual delivery of all events that have occurred.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-subscription--EventAffordance"><td><code>subscription</code></td><td>Defines data that needs to be passed upon subscription, e.g., filters or message format for setting up Webhooks.</td><td>no</td><td><a href="#dataschema"><code>DataSchema</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-data--EventAffordance"><td><code>data</code></td><td>Defines the data schema of the Event instance messages pushed by the Thing.</td><td>no</td><td><a href="#dataschema"><code>DataSchema</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-cancellation--EventAffordance"><td><code>cancellation</code></td><td>Defines any data that needs to be passed to cancel a subscription, e.g., a specific message to remove a Webhook.</td><td>no</td><td><a href="#dataschema"><code>DataSchema</code></a></td></tr></tbody></table>
<p>Event class is a subclass of the class <a href="#interactionaffordance" 
    class="sec-ref">InteractionAffordance</a>.
    <span class="rfc2119-assertion" id="td-op-for-event">
    When a <code>forms</code> term member is present in an Event instance, 
    the value(s) in the <code>op</code> term member of the <code>forms</code> MUST be either or both of 
    <code>subscribeevent</code> or/and <code>unsubscribeevent</code>.
    </span>
</p>
</section></section>
<section><h3><code>Form</code></h3><p>Communication metadata indicating where a service can be accessed by a client application. An interaction might have more than one form.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-href--Form"><td><code>href</code></td><td>URI of the endpoint where an interaction pattern is provided.</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-contentType--Form"><td><code>contentType</code></td><td>Assign a content type based on a media type [[!IANA-MEDIA-TYPES]] (e.g., 'application/json) and (optional) parameters (e.g., 'charset=utf-8').</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-response--Form"><td><code>response</code></td><td>This optional term can be used if, e.g., the output communication metadata differ from input metdata (e.g., output contentType differ from the
     input contentType). The response name contains metadata that is only valid for the reponse messages.</td><td>no</td><td><a href="#expectedresponse"><code>ExpectedResponse</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-op--Form"><td><code>op</code></td><td>Indicates the semantic intention of performing the operation(s) described by the form.

For example, the Property interaction allows get and set operations.  
The protocol binding may contain a form for the get operation and a different form for the set operation.  
The op attribute indicates which form is for which and allows the client to select the correct form for the operation required.

op can be assigned one or more interaction verb(s) each representing a semantic intention of an operation.</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (one of <code>readproperty</code>, <code>writeproperty</code>, <code>observeproperty</code>, <code>unobserveproperty</code>, <code>invokeaction</code>, <code>subscribeevent</code>, <code>unsubscribeevent</code>, <code>readallproperties</code>, <code>writeallproperties</code>, <code>readmultipleproperties</code>, or <code>writemultipleproperties</code>)</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-subprotocol--Form"><td><code>subprotocol</code></td><td>Indicates the exact mechanism by which an interaction will be accomplished for a given protocol when there are multiple options.
     
For example, for HTTP and Events, it indicates which of several available mechanisms should be used for asynchronous notifications such as long polling, websub (also see https://www.w3.org/TR/websub/), or server sent events (also see https://www.w3.org/TR/eventsource/). Please note that there is no restriction on the sub-protocol selection and other mechanisms can also be announced by this subprotocol term.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (e.g. <code>longpoll</code>, <code>websub</code>, or <code>sse</code>)</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-security--Form"><td><code>security</code></td><td>Set of security definition names, chosen from those defined in securityDefinitions.  These must all be satisfied for access to resources at or below the current level, if not overridden at a lower level.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-scopes--Form"><td><code>scopes</code></td><td>Set of authorization scope identifiers, provided as an array.  These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>VersionInfo</code></h3><p>Carries version information about the TD instance. If required, additional version information such as firmware and hardware version (term definitions outside of the TD namespace) can be extended here.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-instance--VersionInfo"><td><code>instance</code></td><td>Provides a version identicator of this TD instance.</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>ExpectedResponse</code></h3><p>Communication metadata for response messages (e.g., contentType of the response).</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-contentType--ExpectedResponse"><td><code>contentType</code></td><td>Assign a content type based on a media type [[!IANA-MEDIA-TYPES]] (e.g., 'application/json) and (optional) parameters (e.g., 'charset=utf-8').</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>MultiLanguage</code></h3><p>Container to provide human-readable text in different languages using language tags described in [[!BCP47]]. Each used language tags code MUST be decleared as vocabulary term member of this container (e.g., en, de, ja, zh-Hans, zh-Hant). See <a href="#titles-descriptions-serialization-json"></a> for example usages of this container in a Thing Description instance.</p>
<p>
<span class="rfc2119-assertion" id="td-context-ns-multilanguage-content-negotiation">
Note that in protocols such as HTTP that have an ability to negotiate content based on languages, 
those terms (e.g. <code>description</code> and <code>title</code>) intended for carrying texts in a default language SHOULD be used instead of <code>MultiLanguage</code> container
when the texts are served as a result such negotiation.
</span>
</p>
</section>

      </section>
    
      <section id="sec-data-schema-vocabulary-definition">
      <h2>Data Schema Vocabulary Definition</h2>
      <p>
        The data schema definition reflecting a very common subset of the terms defined in JSON Schema [[?JSON-SCHEMA-VALIDATION]]. It is noted
        that data schema definitions within Thing Description instances are not limited to this defined subset and MAY use additional terms you 
        find in JSON Schema. It that case it is recommended to use context association for that additional terms as described in 
        <a href="#content-extension-section"></a>, otherwise these terms are semantically ignored (also see <a href="#note-jsonld11-processing"></a>).
      </p>

        <section><h3><code>DataSchema</code></h3><p>A JSON specification.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-at-type--DataSchema"><td><code>@type</code></td><td>Known from JSON-LD [[!json-ld]], <code>@type</code> is used to state that values described by the DataSchema are instances of a class. <br/><br/> Each string in the value array represents a class.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr><tr class="rfc2119-table-assertion" id="td-vocab-title--DataSchema"><td><code>title</code></td><td>Provides a human-readable title (e.g., display a text for UI representation) of the interaction pattern based on a default language.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-titles--DataSchema"><td><code>titles</code></td><td>Provides multi-language human-readable titles (e.g., display a text for UI representation in different languages) of the interaction pattern.</td><td>no</td><td><a href="#multilanguage"><code>MultiLanguage</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-description--DataSchema"><td><code>description</code></td><td>Provides additional (human-readable) information based on a default language.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-descriptions--DataSchema"><td><code>descriptions</code></td><td>Can be used to support (human-readable) information in different languages.</td><td>no</td><td><a href="#multilanguage"><code>MultiLanguage</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-type--DataSchema"><td><code>type</code></td><td>Assignment of JSON-based data types compatible with JSON Schema (one of boolean, integer, number, string, object, array, or null).</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (one of <code>object</code>, <code>array</code>, <code>string</code>, <code>number</code>, <code>integer</code>, <code>boolean</code>, or <code>null</code>)</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-const--DataSchema"><td><code>const</code></td><td>Provides a constant value.</td><td>no</td><td>any type</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-unit--DataSchema"><td><code>unit</code></td><td>Provides unit information that is used, e.g., in international science, engineering, and business.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-oneOf--DataSchema"><td><code>oneOf</code></td><td>Used to ensure that the data is valid against one of the specified schemas in the array.</td><td>no</td><td>array of <a href="#dataschema"><code>DataSchema</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-enum--DataSchema"><td><code>enum</code></td><td>Restricted set of values provided as an array.</td><td>no</td><td>array of any type</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-readOnly--DataSchema"><td><code>readOnly</code></td><td>Boolean value that is a hint to indicate whether a property interaction / value is read only (=true) or not (=false).</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#boolean"><code>boolean</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-writeOnly--DataSchema"><td><code>writeOnly</code></td><td>Boolean value that is a hint to indicate whether a property interaction / value is write only (=true) or not (=false).</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#boolean"><code>boolean</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-format--DataSchema"><td><code>format</code></td><td>Defines format pattern validation on certain kinds of string values. It is open to use pattern values that may originate from JSON schema presets (e.g., date/time, email, URL) or other (custom-based) definitions.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table><p>The class <code>DataSchema</code> has the following subclasses:</p><ul><li><a href="#integerschema"><code>IntegerSchema</code></a></li>
<li><a href="#arrayschema"><code>ArraySchema</code></a></li>
<li><a href="#booleanschema"><code>BooleanSchema</code></a></li>
<li><a href="#nullschema"><code>NullSchema</code></a></li>
<li><a href="#objectschema"><code>ObjectSchema</code></a></li>
<li><a href="#numberschema"><code>NumberSchema</code></a></li>
<li><a href="#stringschema"><code>StringSchema</code></a></li></ul>
<p>
     <span class="rfc2119-assertion" id="td-context-ns-dataschema-mandatory">The mandatory
     context definition of the string <code>"http://www.w3.org/ns/json-schema"</code> MUST be 
     the first item in the <code>@context</code> array.</span>
     <span class="rfc2119-assertion" id="td-context-ns-dataschema-optional">The mandatory
     context definition MAY be followed by one or more context definitions as strings or 
     objects.</span>
</p>
<p>
     <span class="rfc2119-assertion" id="td-context-ns-dataschema-dereferenceable-url">
     As suggested in JSON-LD [[!json-ld]] specification, if a context definition is 
     a string, it SHOULD be a dereferenceable URL.
     </span>
     <span class="rfc2119-assertion" id="td-context-ns-dataschema-map-of-namespaces">
     Likewise, if a context definition is an object, it SHOULD be a map of namespaces, 
     in which keys are namespace prefixes. 
     </span>
     <span class="rfc2119-assertion" id="td-context-ns-dataschema-prefix">Each optional
     namespace specified in the <code>@context</code> array of a DataSchema MUST be bound 
     to an unique prefix.</span>
</p>
</section>
<section><h3><code>ArraySchema</code></h3><p>A JSON array specification ("type": "array").</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-items--ArraySchema"><td><code>items</code></td><td>Used to define the characteristics of an array.</td><td>no</td><td><a href="#dataschema"><code>DataSchema</code></a> or array of <a href="#dataschema"><code>DataSchema</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-minItems--ArraySchema"><td><code>minItems</code></td><td>Defines the minimum number of items that have to be in the array.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#unsignedInt"><code>unsignedInt</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-maxItems--ArraySchema"><td><code>maxItems</code></td><td>Defines the maximum number of items that have to be in the array.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#unsignedInt"><code>unsignedInt</code></a></td></tr></tbody></table></section>
<section><h3><code>BooleanSchema</code></h3><p>A JSON boolean value specification ("type": "boolean").</p></section>
<section><h3><code>NumberSchema</code></h3><p>A JSON number value specification ("type": "number").</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-minimum--NumberSchema"><td><code>minimum</code></td><td>Specifies a minimum numeric value. Only applicable for associated number or integer types.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#double"><code>double</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-maximum--NumberSchema"><td><code>maximum</code></td><td>Specifies a maximum numeric value. Only applicable for associated number or integer types.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#double"><code>double</code></a></td></tr></tbody></table></section>
<section><h3><code>IntegerSchema</code></h3><p>A JSON integer value specification, that is, numbers without a fractional part ("type": "integer").</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-minimum--IntegerSchema"><td><code>minimum</code></td><td>Specifies a minimum numeric value. Only applicable for associated number or integer types.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#integer"><code>integer</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-maximum--IntegerSchema"><td><code>maximum</code></td><td>Specifies a maximum numeric value. Only applicable for associated number or integer types.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#integer"><code>integer</code></a></td></tr></tbody></table></section>
<section><h3><code>ObjectSchema</code></h3><p>A JSON object specification ("type": "object").</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-properties--ObjectSchema"><td><code>properties</code></td><td>Data schema nested definitions.</td><td>no</td><td>map of <a href="#dataschema"><code>DataSchema</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-required--ObjectSchema"><td><code>required</code></td><td>Defines which members of the object type are mandatory.</td><td>no</td><td>array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>StringSchema</code></h3><p>A JSON string value specification ("type": "string").</p></section>
<section><h3><code>NullSchema</code></h3><p>A JSON null value specification ("type": "null"). If the type of null then it has only one acceptable value, namely null. E.g., it can be used as part of oneOf declaration, where it is used to indicate, that a data schema can also be null.</p></section>
      </section>
    
      <section id="sec-security-vocabulary-definition">
      <h2>Security Vocabulary Definition</h2>
    
      <p>
      For the core TD vocabulary only well-established security  
      mechanisms are supported, such as those built into protocols supported by WoT  
      or already in wide use with those protocols.  
      The current set of HTTP security schemes is partly based on 
      <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#securitySchemeObject">OpenAPI 3.0.1</a> (see also [[?OPENAPI]]). 
      Note however that while the HTTP security schemes, 
      vocabulary and syntax given in this specification share many similarities 
      with OpenAPI they are not fully compatible.  
      Also, since OpenAPI primarily targets web services built around HTTP, it does not 
      cover the full set of use cases required for the IoT.  
      Security schemes appropriate 
      for IoT-centered protocols such as CoAP [[?RFC7252]] and MQTT [[?MQTT]] are therefore also included.
      </p>
    
      <p class="ednote" title="Security Scheme Extensions">
      The vocabulary extension mechanism of the 
      WoT Thing Description allows for additional security schemes if needed.
      However, for more information about what additional security schemes 
      or modifications are under discussion for the core WoT vocabulary
      (and to file issues if you have a request) please visit the 
      <a href="https://github.com/w3c/wot-security">WoT Security TF repository.</a>
      </p>
    
        <section><h3><code>SecurityScheme</code></h3><p></p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-at-type--SecurityScheme"><td><code>@type</code></td><td>Known from JSON-LD [[!json-ld]], <code>@type</code> is used to state that a security mechanism configured by the SecurityScheme is an instance of a class.<br/><br/> Each string in the value array represents a class.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr><tr class="rfc2119-table-assertion" id="td-vocab-scheme--SecurityScheme"><td><code>scheme</code></td><td>Identification of security mechanism being configured.</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (one of <code>nosec</code>, <code>basic</code>, <code>cert</code>, <code>digest</code>, <code>bearer</code>, <code>pop</code>, <code>psk</code>, <code>public</code>, <code>oauth2</code>, or <code>apikey</code>)</td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-description--SecurityScheme"><td><code>description</code></td><td>Provides additional (human-readable) information based on a default language.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-descriptions--SecurityScheme"><td><code>descriptions</code></td><td>Can be used to support (human-readable) information in different languages.</td><td>no</td><td><a href="#multilanguage"><code>MultiLanguage</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-proxy--SecurityScheme"><td><code>proxy</code></td><td>URI of the proxy server this security configuration provides access to.  If not given, the corresponding security configuration is for the endpoint.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr></tbody></table><p>The class <code>SecurityScheme</code> has the following subclasses:</p><ul><li><a href="#psksecurityscheme"><code>PSKSecurityScheme</code></a></li>
<li><a href="#apikeysecurityscheme"><code>APIKeySecurityScheme</code></a></li>
<li><a href="#nosecurityscheme"><code>NoSecurityScheme</code></a></li>
<li><a href="#certsecurityscheme"><code>CertSecurityScheme</code></a></li>
<li><a href="#popsecurityscheme"><code>PoPSecurityScheme</code></a></li>
<li><a href="#digestsecurityscheme"><code>DigestSecurityScheme</code></a></li>
<li><a href="#oauth2securityscheme"><code>OAuth2SecurityScheme</code></a></li>
<li><a href="#bearersecurityscheme"><code>BearerSecurityScheme</code></a></li>
<li><a href="#basicsecurityscheme"><code>BasicSecurityScheme</code></a></li>
<li><a href="#publicsecurityscheme"><code>PublicSecurityScheme</code></a></li></ul>
<p>
     <span class="rfc2119-assertion" id="td-context-ns-securityscheme-mandatory">The mandatory
     context definition of the string <code>"http://www.w3.org/ns/wot-security"</code> MUST be 
     the first item in the <code>@context</code> array.</span>
     <span class="rfc2119-assertion" id="td-context-ns-securityscheme-optional">The mandatory
     context definition MAY be followed by one or more context definitions as strings or 
     objects.</span>
</p>
<p>
     <span class="rfc2119-assertion" id="td-context-ns-securityscheme-dereferenceable-url">
     As suggested in JSON-LD [[!json-ld]] specification, if a context definition is 
     a string, it SHOULD be a dereferenceable URL.
     </span>
     <span class="rfc2119-assertion" id="td-context-ns-securityscheme-map-of-namespaces">
     Likewise, if a context definition is an object, it SHOULD be a map of namespaces, 
     in which keys are namespace prefixes. 
     </span>
     <span class="rfc2119-assertion" id="td-context-ns-securityscheme-prefix">Each optional
     namespace specified in the <code>@context</code> array of a SecurityScheme MUST be bound 
     to an unique prefix.</span>
</p>
</section>
<section><h3><code>NoSecurityScheme</code></h3><p>A security configuration corresponding to ("scheme": "nosec"), indicating there is no authentication or other mechanism required to access the resource.</p></section>
<section><h3><code>BasicSecurityScheme</code></h3><p>Basic authentication security configuration ("scheme": "basic"), using an unencrypted username and password.  This scheme should be used with some other security mechanism providing confidentiality, for example, TLS.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-in--BasicSecurityScheme"><td><code>in</code></td><td>Specifies the location of security authentication information (one of header, query, body, or cookie).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-name--BasicSecurityScheme"><td><code>name</code></td><td>Name for query, header, or cookie parameters.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>DigestSecurityScheme</code></h3><p>Digest authentication security configuration ("scheme": "digest"). This scheme is similar to basic authentication but with added features to avoid man-in-the-middle attacks.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-qop--DigestSecurityScheme"><td><code>qop</code></td><td>Quality of protection (one of auth or auth-int).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-in--DigestSecurityScheme"><td><code>in</code></td><td>Specifies the location of security authentication information (one of header, query, body, or cookie).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-name--DigestSecurityScheme"><td><code>name</code></td><td>Name for query, header, or cookie parameters.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>APIKeySecurityScheme</code></h3><p><span class="at-risk">This section is at risk.</span></p><p>API key authentication security configuration ("scheme": "apikey").  This is for the case where the access token is opaque and is not using a standard token format.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-in--APIKeySecurityScheme"><td><code>in</code></td><td>Specifies the location of security authentication information (one of header, query, body, or cookie).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-name--APIKeySecurityScheme"><td><code>name</code></td><td>Name for query, header, or cookie parameters.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>BearerSecurityScheme</code></h3><p>Bearer token authentication security configuration ("scheme": "bearer").  This scheme is intended for situations where bearer tokens are used independently of OAuth2.  If the oauth2 scheme is specified it is not generally necessary to specify this scheme as well as it is implied.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-authorization--BearerSecurityScheme"><td><code>authorization</code></td><td>URI of the authorization server.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-alg--BearerSecurityScheme"><td><code>alg</code></td><td>Encoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-format--BearerSecurityScheme"><td><code>format</code></td><td>Specifies format of security authentication information (one of jwt, jwe, or jws).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-in--BearerSecurityScheme"><td><code>in</code></td><td>Specifies the location of security authentication information (one of header, query, body, or cookie).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-name--BearerSecurityScheme"><td><code>name</code></td><td>Name for query, header, or cookie parameters.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>CertSecurityScheme</code></h3><p><span class="at-risk">This section is at risk.</span></p><p>Certificate-base asymmetric key security configuration ("scheme": "cert").</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-identity--CertSecurityScheme"><td><code>identity</code></td><td>Pre-shared key identity.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>PSKSecurityScheme</code></h3><p><span class="at-risk">This section is at risk.</span></p><p>Pre-shared key authentication security configuration ("scheme": "psk").</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-identity--PSKSecurityScheme"><td><code>identity</code></td><td>Pre-shared key identity.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>PublicSecurityScheme</code></h3><p><span class="at-risk">This section is at risk.</span></p><p>Raw public key asymmetric key security configuration ("scheme": "public").</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-identity--PublicSecurityScheme"><td><code>identity</code></td><td>Pre-shared key identity.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>PoPSecurityScheme</code></h3><p><span class="at-risk">This section is at risk.</span></p><p>Proof-of-possession token authentication security configuration ("scheme": "pop").</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-authorization--PoPSecurityScheme"><td><code>authorization</code></td><td>URI of the authorization server.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-alg--PoPSecurityScheme"><td><code>alg</code></td><td>Encoding, encryption, or digest algorithm (one of MD5, ES256, or ES512-256).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-format--PoPSecurityScheme"><td><code>format</code></td><td>Specifies format of security authentication information (one of jwt, jwe, or jws).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-in--PoPSecurityScheme"><td><code>in</code></td><td>Specifies the location of security authentication information (one of header, query, body, or cookie).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-name--PoPSecurityScheme"><td><code>name</code></td><td>Name for query, header, or cookie parameters.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
<section><h3><code>OAuth2SecurityScheme</code></h3><p><span class="at-risk">This section is at risk.</span></p><p>OAuth2 authentication security configuration ("scheme": "oauth2").  For the implicit flow the authorization and scopes are required.  For the password and client flows both token and scopes are required.  For the code flow authorization, token, and scopes are required.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-authorization--OAuth2SecurityScheme"><td><code>authorization</code></td><td>URI of the authorization server.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-token--OAuth2SecurityScheme"><td><code>token</code></td><td>URI of the token server.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-refresh--OAuth2SecurityScheme"><td><code>refresh</code></td><td>URI of the refresh server.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-scopes--OAuth2SecurityScheme"><td><code>scopes</code></td><td>Set of authorization scope identifiers, provided as an array.  These are provided in tokens returned by an authorization server and associated with forms in order to identify what resources a client may access and how.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> or array of <a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-flow--OAuth2SecurityScheme"><td><code>flow</code></td><td>Authorization flow (one of implicit, password, client, or code).</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr></tbody></table></section>
      </section>
    
      <section id="sec-web-linking-vocabulary-definition">
      <h2>Web Linking Vocabulary Definition</h2>
      <p>
        The present model provides a representation for (typed) Web links exposed by
        a Thing. It is designed after the CoRE Link format [[RFC6690]].
      </p>

        <section><h3><code>Link</code></h3><p>A link can be viewed as a statement of the form "link context has a link relation type resource at link target, which has target attributes".</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Mandatory</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-href--Link"><td><code>href</code></td><td>Each link-value conveys one target IRI as a URI-Reference (after conversion to one, if necessary; see RFC3987, Section 3.1) inside angle brackets ("<>").</td><td>yes</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-type--Link"><td><code>type</code></td><td>Target attribute providing a hint indicating what the media type [IANA-MEDIA-TYPES] of the result of dereferencing the link should be.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-rel--Link"><td><code>rel</code></td><td>A link relation type identifies the semantics of a link.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-anchor--Link"><td><code>anchor</code></td><td>By default, the context, or anchor, of a link conveyed in the Link header field is the URL of the representation it is associated with, as defined in RFC7231, Section 3.1.4.1, and is serialized as a URI.</td><td>no</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#anyURI"><code>anyURI</code></a></td></tr></tbody></table></section>
      </section>

    </section>

  <section id="sec-td-serialization" class="informative">
  <h1>Thing Description Serialization</h1>

  <p>
  Thing Description instances are modeled and structured based on Section
  <a href="#sec-vocabulary-definition"></a>.

</p>
 
<p>
  The JSON serialization of TDs follows the syntax of JSON-LD 1.1 [[json-ld11]] in order to streamline semantic evaluation. 
   Hence, serializations can be parsed either as raw JSON or with a JSON-LD 1.1 processor.
</p>

  <section id="json-serializiation-section">
  <h1>Basic Representation Format Assumptions</h1>

   
  <p>
  As a fundamental basis, 
  all <a>vocabulary terms</a> defined in Section
  <a href="#sec-core-vocabulary-definition"></a>
  will have a JSON name representation.
  </p>


  <p>
  The data types of the vocabulary as defined in Section
  <a href="#sec-data-schema-vocabulary-definition"></a>
  will be transformed to JSON-based types. 
  The following rules are used for vocabulary terms based on some simple type 
  definitions:
  </p>
  <ul>
  <li><span class="rfc2119-assertion" id="td-string-type">
        Vocabulary terms that use simple types string and anyURI
        MUST be serialized as JSON string.
  </span></li>
  <li><span class="rfc2119-assertion" id="td-integer-type">
        Vocabulary terms that use simple type integer
        MUST be serialized as JSON number without a fraction or exponent part.
  </span></li>
  <li><span class="rfc2119-assertion" id="td-number-type">
        Vocabulary terms that use simple type double
        MUST be serialized as JSON number.
  </span></li>
  </ul>


  <!-- p>
    <span class="rfc2119-assertion" id="td-serializiation-default-values">
        If values are not given for certain mandatory fields,
        default values MUST be assumed.
    </span>    
    Default values for these fields are given in table 
    <a href="#default-value-table">Default Values for Vocabulary Terms</a>.
  </p -->


  <p>
        In addition, <span class="rfc2119-assertion" id="td-jsonld-keywords">
        Thing Description instances MAY contain additional JSON-LD [[json-ld11]] keywords such as
        <code>@context</code> and <code>@type</code>. With these the Thing Description can 
        be easily extended. You can find additional details in the Section  <a href="#content-extension-section"></a>.
       </span>


<span class="rfc2119-assertion" id="td-at-type">
        In the case of <code>@type</code> usage in the Thing Description instance, the <code>@type</code> MUST be serialized as JSON String or as JSON array of strings when multiple values are assigned to <code>@type</code>.
</span>
</p>

<p>
        <span class="rfc2119-assertion" id="td-simple-form">
                A Thing Description instance serialization MAY omit one ore more vocabulary terms that are mandatory (<a href="#sec-core-vocabulary-definition"></a>) AND have default values assumed based on the table in <a href="#sec-default-values"></a>.
        </span>
        In this specification, this form is referred to as <i>Simple</i> Thing Description representation. 
        The interpretation of such <i>Simple</i> Thing Descriptions (e.g. via a raw JSON parser) MUST always follow the 
        default value assumptions of the omitted vocabulary terms.
        If a Thing Description instance contains all mandatory vocabulary, we will call this representation as   
        <i>Full</i> Thing Description and can be passed directly to a JSON-LD 1.1 processor for interpretation or 
        RDF semantic processing.
      </p>
    
    
  <p>
  All vocabulary terms in Section
  <a href="#sec-vocabulary-definition"></a>
  associated with more complex class-based types are defined separately for 
  structured JSON type transformation in the following subsections.
  </p>

  <section id="sec-thing-as-a-whole-json">
  <h2>Thing as a whole</h2>

  <p><span class="rfc2119-assertion" id="td-context">
  The root object of a Thing Description instance MAY include the
  <code>@context</code> name known from JSON-LD [[json-ld11]] with the value URI of 
  the Thing description context file <code>http://www.w3.org/ns/td</code>.
  </span></p>

<pre class="example">
{  
    "@context": "http://www.w3.org/ns/td",
    ...
}
</pre>

  <p class="ednote">
  <code>http://www.w3.org/ns/td</code> uses content negotiation to return the
  context file. Thus, it must be fetched with an <code>Accept</code> header set
  to <code>application/ld+json</code>.
  </p>

  <p><span class="rfc2119-assertion" id="td-additional-contexts">
  When a single Thing Description instance involves several contexts, 
  additional namespaces with prefixes MUST be appended to the 
  <code>@context</code> array structure.</span> 
  This option proves relevant if one wants to extend the existing 
  Thing Description context without modifying it. For instance:
  </p>
<pre class="example">
{
    "@context": ["http://www.w3.org/ns/td",
                {"iot": "http://example.org/iot"}],
    ...
}
</pre>

  <p><span class="rfc2119-assertion" id="td-context-toplevel">
  Each mandatory and optional member name
  as defined in the class <a href="#thing" class="sec-ref"><code>Thing</code></a>
  MUST be serialized as a JSON name 
  in the root object of the Thing Description instance.
  </span></p>

  <!-- should this be "the type" or "the elements of"? -->
  <p><span class="rfc2119-assertion" id="td-objects">
  The type of the members <code>properties</code>, <code>actions</code>, 
  <code>events</code>, <code>version</code>,   and <code>securityDefinitions</code> MUST be a JSON object.
  </span></p>

  <p><span class="rfc2119-assertion" id="td-arrays">
  The type of the members <code>forms</code>, <code>links</code>, 
  <code>scopes</code>, and <code>security</code>
  MUST be a JSON array.
  </span></p>

  <p>
  A TD snippet based on the defined members of the class
  <a href="#thing" class="sec-ref"><code>Thing</code></a>
  without the optional member <code>@context</code> is given below:
  </p>
<pre class="example">
{
    "id": "urn:dev:wot:com:example:servient:myThing",
    "name": "MyThing",
    "description": "Human readable information.",
    "descriptions": {...},
    "support": "mailto:support@example.com",
    "securityDefinitions": {...},
    "security": [...],
    "base": "https://servient.example.com/",
    "lastModified" : "2018-11-15T09:12:43.124Z",
    "created" : "2018-11-14T19:10:23.824Z",
    "version" : {...},
    "properties": {...},
    "actions": {...},
    "events": {...},
    "links": [...],
    "forms": [...]
}
</pre>

  <p>Alternatively, the same example can be written instead to 
  explicitly include the (semantic) names used by JSON-LD [[json-ld11]], namely <code>@context</code> and <code>@type</code>:
  </p>
<pre class="example">
{
    "@context": "http://www.w3.org/ns/td",
    "@type": "Thing",
    "id": "urn:dev:wot:com:example:servient:myThing",
    "name": "MyThing",
    "description": "Human readable information.",
    "descriptions": {...},
    "support": "mailto:support@example.com",
    "securityDefinitions": {...},
    "security": [...],
    "base": "https://servient.example.com/",
    "lastModified" : "2018-11-15T09:12:43.124Z",
    "created" : "2018-11-14T19:10:23.824Z",
    "version" : {...},
    "properties": {...},
    "actions": {...},
    "events": {...},
    "links": [...],
    "forms": [...]
}
</pre>

<p>In that case the content can be directly associated as Thing Description based on the namespace  <code>http://www.w3.org/ns/td</code>  provided 
    in the <code>@context</code>. The  <code>"@type": "Thing"</code> associates an instantiations of the Thing class as defined in Section <a href="#thing"></a>.

</p>

 </section> <!-- end of id="sec-thing-as-a-whole-json"-->

 <section id="property-serialization-json">
 <h2><code>properties</code></h2>
  
  <p><span class="rfc2119-assertion" id="td-properties">
  Properties (and sub-properties) offered by a Thing MUST be collected
  in the JSON-object based <code>properties</code> member
  with (unique) Property names as JSON names.
  </span></p>

  <p>
  <span class="rfc2119-assertion" id="td-property-names">
  Each mandatory and optional vocabulary term
  as defined in the class <a href="#property" class="sec-ref"><code>Property</code></a>,
  as well as its two superclasses
  <a href="#interactionaffordance" class="sec-ref"><code>InteractionAffordance</code></a>
  and <a href="#dataschema" class="sec-ref"><code>DataSchema</code></a>,
  MUST be serialized as a JSON name within a Property object. This means that at the level of an interaction property instance, the vocabulary terms
   of  <a href="#interactionaffordance" class="sec-ref"><code>InteractionAffordance</code></a>
  and <a href="#dataschema" class="sec-ref"><code>DataSchema</code></a> can be presented at the same time.
  </span></p>

  <p><span class="rfc2119-assertion" id="td-property-arrays">
  The type of the member <code>forms</code>
  MUST be serialized as a JSON array.
  </span></p>

  <p>
  A TD snippet based on the defined members is given below:
  </p>


<aside class="example ds-selector-tabs changed" id="property-serialization-sample" title="Sample of a property interaction serialization">
        <div class="selectors">
          <button class="selected" data-selects="ex-original">Simple</button>
          <button data-selects="ex-full">Full (JSON-LD 1.1)</button>
          <button data-selects="ex-rdf">RDF</button>
        </div>
        <pre class="ex-original selected">{
        ...
        "properties": {
            "on": {
                "type": "boolean",
                "forms": [...]
            },
            "status": {
                "type": "object",
                "properties": {
                    "brightness": {
                        "type": "number",
                        "minimum": 0.0,
                        "maximum": 100.0
                        },
                        "rgb": {
                        "type": "array",
                        "items" : {
                            "type" : "number",
                            "minimum": 0,
                            "maximum": 255
                        },
                        "minItems": 3,
                        "maxItems": 3
                    }
                },
                "required": ["brightness", "rgb"],
                "forms": [...]
            }
        }
        ...
    }</pre>
        <pre class="ex-full">{
    ...
    "properties": {
        "on": {
            "type": "boolean",
            "forms": [...]
        },
        "status": {
            "type": "object",
            "properties": {
                "brightness": {
                    "type": "number",
                    "minimum": 0.0,
                    "maximum": 100.0
                },
                "rgb": {
                    "type": "array",
                    "items" : {
                        "type" : "number",
                        "minimum": 0,
                        "maximum": 255
                    },
                    "minItems": 3,
                    "maxItems": 3
                }
            },
            "required": ["brightness", "rgb"],
            "forms": [...]
        }
    }
    ...
}</pre>
<pre class="ex-rdf">_:b0 &lt;http://www.w3.org/ns/td#properties&gt; _:b1 .
_:b0 &lt;http://www.w3.org/ns/td#properties&gt; _:b2 .
_:b1 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#BooleanSchema&gt; .
_:b1 &lt;http://www.w3.org/ns/td#observable&gt; &quot;false&quot;^^&lt;http://www.w3.org/2001/XMLSchema#boolean&gt; .
_:b2 &lt;http://w3.org/ns/json-schema#properties&gt; _:b3 .
_:b2 &lt;http://w3.org/ns/json-schema#properties&gt; _:b4 .
_:b2 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#ObjectSchema&gt; .
_:b2 &lt;http://www.w3.org/ns/json-schema#required&gt; &quot;brightness&quot; .
_:b2 &lt;http://www.w3.org/ns/json-schema#required&gt; &quot;rgb&quot; .
_:b3 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#NumberSchema&gt; .
_:b3 &lt;http://www.w3.org/ns/json-schema#maximum&gt; &quot;100&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
_:b3 &lt;http://www.w3.org/ns/json-schema#minimum&gt; &quot;0&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
_:b4 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#ArraySchema&gt; .
_:b4 &lt;http://www.w3.org/ns/json-schema#items&gt; _:b5 .
_:b4 &lt;http://www.w3.org/ns/json-schema#maxItems&gt; &quot;3&quot;^^&lt;http://www.w3.org/2001/XMLSchema#decimal&gt; .
_:b4 &lt;http://www.w3.org/ns/json-schema#minItems&gt; &quot;3&quot;^^&lt;http://www.w3.org/2001/XMLSchema#decimal&gt; .
_:b5 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#NumberSchema&gt; .
_:b5 &lt;http://www.w3.org/ns/json-schema#maximum&gt; &quot;255&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
_:b5 &lt;http://www.w3.org/ns/json-schema#minimum&gt; &quot;0&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
</pre>
    </aside>


  </section> <!-- end of id="property-serialization-json"-->

  <section id="action-serialization-json">
  <h2><code>actions</code></h2>

  <p><span class="rfc2119-assertion" id="td-actions">
  Actions offered by a Thing MUST be collected
  in the JSON-object based <code>actions</code> member
  with (unique) Action names as JSON names.
  </span></p>

  <p>
  <span class="rfc2119-assertion" id="td-action-names">
  Each optional vocabulary term
  as defined in the class <a href="#action" class="sec-ref"><code>Action</code></a>
  and its superclass
  <a href="#interactionaffordance" class="sec-ref"><code>InteractionAffordance</code></a>
  MUST be serialized as a JSON name within an Action object.
  </span></p>

  <p><span class="rfc2119-assertion" id="td-action-objects">
  The type of the members <code>input</code> and <code>output</code>
  MUST be serialized as a JSON object.
  </span></p>

  <p>The names  <code>input</code> and <code>output</code>
  rely on the the class <a href="#dataschema" class="sec-ref"><code>DataSchema</code></a> and will follow the serialization introduction provided in <a href="#data-schema-serialization-json"></a>.
  </p>

  <p><span class="rfc2119-assertion" id="td-action-arrays">
  The type of the member <code>forms</code>
  MUST be serialized as a JSON array.
  </span></p>

  <p>
  A TD snippet based on the defined members is given below:
  </p>

  <aside class="example ds-selector-tabs changed" id="action-serialization-sample" title="Sample of an action interaction serialization">
        <div class="selectors">
          <button class="selected" data-selects="ex-original">Simple</button>
          <button data-selects="ex-full">Full (JSON-LD 1.1)</button>
          <button data-selects="ex-rdf">RDF</button>
        </div>
        <pre class="ex-original selected">{
    ...
    "actions": {
        "fade" : {
            "title": "Fade in/out",
            "description": "Smooth fade in and out animation.",
            "input": {
                "type": "object",
                "properties": {
                    "from": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "to": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "duration": {"type": "number"}
                },
                "required": ["to","duration"],
            },
            "output": {"type": "string"},
            "forms": [...]
        }
        ...
    }
    ...
</pre>
<pre class="ex-full">{
    ...
    "actions": {
        "fade" : {
            "title": "Fade in/out",
            "description": "Smooth fade in and out animation.",
            "idempotent" :  false,
            "safe" :  false,
            "input": {
                "type": "object",
                "properties": {
                    "from": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "to": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "duration": {"type": "number"}
                },
                "required": ["to","duration"],
            },
            "output": {
                "type": "string"
            },
            "forms": [...]
        }
        ...
    }
    ...
}</pre>
<pre class="ex-rdf">_:b0 &lt;http://www.w3.org/ns/td#actions&gt; _:b1 .
_:b1 &lt;http://www.w3.org/ns/td#description&gt; &quot;Smooth fade in and out animation.&quot; .
_:b1 &lt;http://www.w3.org/ns/td#idempotent&gt; &quot;false&quot;^^&lt;http://www.w3.org/2001/XMLSchema#boolean&gt; .
_:b1 &lt;http://www.w3.org/ns/td#input&gt; _:b2 .
_:b1 &lt;http://www.w3.org/ns/td#output&gt; _:b6 .
_:b1 &lt;http://www.w3.org/ns/td#safe&gt; &quot;false&quot;^^&lt;http://www.w3.org/2001/XMLSchema#boolean&gt; .
_:b1 &lt;http://www.w3.org/ns/td#title&gt; &quot;Fade in/out&quot; .
_:b2 &lt;http://w3.org/ns/json-schema#properties&gt; _:b3 .
_:b2 &lt;http://w3.org/ns/json-schema#properties&gt; _:b4 .
_:b2 &lt;http://w3.org/ns/json-schema#properties&gt; _:b5 .
_:b2 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#ObjectSchema&gt; .
_:b2 &lt;http://www.w3.org/ns/json-schema#required&gt; &quot;duration&quot; .
_:b2 &lt;http://www.w3.org/ns/json-schema#required&gt; &quot;to&quot; .
_:b3 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#NumberSchema&gt; .
_:b4 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#IntegerSchema&gt; .
_:b4 &lt;http://www.w3.org/ns/json-schema#maximum&gt; &quot;100&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
_:b4 &lt;http://www.w3.org/ns/json-schema#minimum&gt; &quot;0&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
_:b5 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#IntegerSchema&gt; .
_:b5 &lt;http://www.w3.org/ns/json-schema#maximum&gt; &quot;100&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
_:b5 &lt;http://www.w3.org/ns/json-schema#minimum&gt; &quot;0&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
_:b6 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#StringSchema&gt; .
</pre>
</aside>
 

  </section> <!-- end of id="action-serialization-json"-->

  <section id="event-serialization-json">
  <h2><code>events</code></h2>

  <p><span class="rfc2119-assertion" id="td-events">
  Events offered by a Thing MUST be collected
  in the JSON-object based <code>events</code> member
  with (unique) Event names as JSON names.
  </span></p>

  <p>
  <span class="rfc2119-assertion" id="td-event-names">
  Each optional vocabulary term
  as defined in the class <a href="#event" class="sec-ref"><code>Event</code></a>,
  as well as its two superclasses
  <a href="#interactionaffordance" class="sec-ref"><code>InteractionAffordance</code></a>
  and <a href="#dataschema" class="sec-ref"><code>DataSchema</code></a>,
  MUST be serialized as a JSON name within an Event object.
  </span></p>

  <p><span class="rfc2119-assertion" id="td-event-objects">
    The type of the members <code>subscription</code>, <code>data</code>, and <code>cancellation</code>
    MUST be serialized as a JSON object.
    </span></p>
  
    <p>The JSON names of <code>subscription</code>, <code>data</code>, and <code>cancellation</code>
    rely on the the class <a href="#dataschema" class="sec-ref"><code>DataSchema</code></a>  and will follow the serialization introduction provided in <a href="#data-schema-serialization-json"></a>.
    </p>

  <p><span class="rfc2119-assertion" id="td-event-arrays">
  The type of the member <code>forms</code>
  MUST be serialized as a JSON array.
  </span></p>

  <p>
  A TD snippet based on the defined members is given below:
  </p>

<aside class="example ds-selector-tabs changed" id="event-serialization-sample" title="Sample of a event interaction serialization">
        <div class="selectors">
          <button class="selected" data-selects="ex-original">Simple</button>
          <button data-selects="ex-full">Full (JSON-LD 1.1)</button>
          <button data-selects="ex-rdf">RDF</button>
        </div>
        <pre class="ex-original selected">{
        ...
        "events": {
            "overheated": {
                "data" : {
                    "type": "object"
                },
                "forms": [...]
            }
            ...
        }
        ...
</pre>
<pre class="ex-full">{
    ...
    "events": {
        "overheated": {
            "data" : {
                "type": "object"
            },
            "forms": [...]
        }
        ...
    }
    ...
}</pre>
<pre class="ex-rdf">_:b0 &lt;http://www.w3.org/ns/td#events&gt; _:b1 .
_:b1 &lt;http://www.w3.org/ns/td#data&gt; _:b2 .
_:b2 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#ObjectSchema&gt; .
</pre>
</aside>
 
Please note that the definition of the event affordance is flexibly defined in order to adopt existing (e.g. WebSub) or customer-oriented event mechanisms. 
For this reason, <code>subscription</code> and <code>cancellation</code> can be defined according to the desired mechanism. Please find further details in [[!WOT-PROTOCOL-BINDING]].
Example <a href="#t2t-event-example-serialization"></a> provides a Thing-to-Thing (T2T) use case that offers an event and uses <code>subscription</code> and <code>cancellation</code>.
</p>

  </section> <!-- end of id="event-serialization-json"-->

  <section id="form-serialization-json">
  <h2><code>forms</code></h2>

  <p><span class="rfc2119-assertion" id="td-forms">
  Each mandatory and optional vocabulary term
  as defined in the class <a href="#form" class="sec-ref"><code>Form</code></a>,
  MUST be serialized as a JSON name.
  </span></p>

  <p><span class="rfc2119-assertion" id="td-form-response-object">
    If required, the type of the member <code>response</code> 
        MUST be serialized as a JSON object.
        </span>
    </p>

  <p><span class="rfc2119-assertion" id="td-form-protocolbindings">
  If required, <code>forms</code> 
  MAY be supplemented with protocol-specific vocabulary terms 
  identified with a prefix. 
  </span>
  See also <a href="#content-extension-section"></a>.
  </p>


  <p>A TD snippet based on the defined members is given below:</p>
<pre class="example">
{
  "@context": ["http://www.w3.org/ns/td",
    {"htv": "http://www.w3.org/2011/http#"}],
  ...
  "securityDefinitions": {
      "basic_sc": {"scheme":"basic", "in":"header"}
  },
    ...
    "forms": [{
        "href" : "http://mytemp.example.com:5683/temp",
        "contentType": "application/json",
        "htv:methodName": "POST",
        "op": ["writeproperty"],
        "security": ["basic_sc"]
    }]
    ...
}
</pre>

    <p><code>href</code> may also carry an URI that contains dynamic variables such as p and d in http://192.168.1.25/left?p=2&amp;d=1. In that case the URI can be defined as template as defined in [[!RFC6570]]: http://192.168.1.25/left{?p,d}</p>

    <p><span class="rfc2119-assertion" id="td-uriVariables-names">
        In such a case these variables in the URI MUST be collected
        in the JSON-object based <code>uriVariables</code> member
        with the associated (unique) variables names as JSON names.
    </span></p>

    <p><span class="rfc2119-assertion" id="td-uriVariables-dataschema">
            Each defined JSON name of the <code>uriVariables</code> collection MUST
            rely on the the class <a href="#dataschema" class="sec-ref"><code>DataSchema</code></a>.
    </span></p>

 
    <p>A TD snippet using URI template and <code>uriVariables</code> is given below:</p>

    <pre class="example">
        "@context": ["http://www.w3.org/ns/td",
            {"htv": "http://www.w3.org/2011/http#"},
            {"eg": "http://www.example.org/iot"}],
        ...
        "actions": {
            "LeftDown": {
              "uriVariables": {
                "p" : { "type": "integer", "minimum": 0, "maximum": 16, "@type": "eg:SomeKindOfAngle" },
                "d" : { "type": "integer", "minimum": 0, "maximum": 1, "@type": "eg:Direction" }
                }
              },
              "forms": [{
                "htv:method": "GET",
                "href" : "http://192.168.1.25/left{?p,d}"
              }]
            }
        ...
    </pre>


   <p>The <code>contentType</code> is used to assign a media types [[!IANA-MEDIA-TYPES]] and MAY contain one or more parameters as 
    attribute-value pair separated by a <code>;</code> character. Example:</p>

   <pre class="example">
    ...
    "contentType" : "text/plain; charset=utf-8"
    ...
</pre>

<p>In some use cases, the form metadata of the interaction affordance must be distinguished between request and response based messages. E.g., an action 'takePhoto'
defines an <code>input</code> to submit parameter settings of a camera (aperture priority, timer,..) using json as content type (="contentType":"application/json"). 
The <code>output</code> of this action is the photo taken, which is available in jpeg format, for example. In such cases, the <code>response</code> can be used to provide a 
 response content type (e.g., "contentType":"image/jpeg").
</p>

<p><span class="rfc2119-assertion" id="td-forms-response">
  If the <code>response</code> member is used in <code>forms</code>, it MUST contain the <code>contentType</code> as 
  defined in class <a href="#expectedresponse" class="sec-ref"><code>ExpectedResponse</code></a>.
</span></p>

<p>A <code>form</code> snippet with the <code>response</code> member is listed below based on the use case of the action 'takePhoto' described above:</p>

<pre class="example">
    "@context": ["http://www.w3.org/ns/td",
        {"htv": "http://www.w3.org/2011/http#"}],
    ...
    "forms": [
        {
          "href": "http://upsq1c.local:9191/api/frame/crop",
          "contentType": "application/json",
          "op": ["invokeaction"],
          "htv:methodName": "POST",
          "response": {
            "contentType": "image/jpeg"
          }
        }
      ]
    ...
</pre>

<p>When <code>forms</code> is present at the top level, it can be used to describe meta interactions supported by a <a href="#thing" class="sec-ref"><code>Thing</code></a> instance. For example, operations "readallproperties" and "writeallproperties" are meta interactions by which clients can read and write all properties of the thing at once. In the example below, <code>forms</code> is used at the top level, and the clients can access end point (i.e. <code>https://mylamp.example.com/allproperties</code>) both to read or write all properties (i.e. <code>"on"</code>, <code>"brightness"</code> and <code>"timer"</code> property) of the thing in a single interaction.</p>

<pre class="example" id="td-forms-readall-example">
{
    "@context": ["http://www.w3.org/ns/td",
        {"htv": "http://www.w3.org/2011/http#"}],
    "id": "urn:dev:wot:com:example:servient:lamp",
    ...
    "forms": [
        {
          "href": "https://mylamp.example.com/allproperties",
          "contentType": "application/json",
          "op": ["readallproperties"],
          "htv:methodName": "GET"
        },
        {
          "href": "https://mylamp.example.com/allproperties",
          "contentType": "application/json",
          "op": ["writeallproperties"],
          "htv:methodName": "PUT"
        }
    ],
    ...
    "properties": {
        "on": {
          "type": "boolean",
          "forms": [...]
        },
        "brightness": {
          "type": "number",
          "forms": [...]
        },
        "timer": {
          "type": "integer",
          "forms": [...]
        }
    },
    ...
}
</pre>


    </section> <!-- end of id="form-serialization-json"-->

    <section id="links-serialization-json">
    <h2><code>links</code></h2>

    <p><span class="rfc2119-assertion" id="td-links">
    Each mandatory and optional vocabulary term
    as defined in the class <a href="#link" class="sec-ref"><code>Link</code></a>,
    MUST be serialized as a JSON name.
    </span></p>

    <p>A TD snippet based on the defined members is given below:</p>

<pre class="example">
    ...
    "links": [{
        "href": "https://servient.example.com/things/lampController",
        "rel": "controlledBy",
        "type": "application/td+json"
    }]
    ...
</pre>

    </section> <!-- end of id="links-serialization-json"-->

    <section id="security-serialization-json">
    <h2><code>securityDefinitions</code> and <code>security</code></h2>

    <p><span class="rfc2119-assertion" id="td-security-schemes">
    Each mandatory and optional vocabulary term
    as defined in the class 
    <a href="#securityscheme" class="sec-ref"><code>SecurityScheme</code></a>,
    MUST be serialized as a JSON name.
    </span></p>

    <p>
    The following TD snippet shows a simple security configuration specifying
    basic username/password authentication in the header.
    The value of <code>in</code> given is actually the default value of
    <code>header</code>.  
   First, a named security configuration must be given
   in a <code>securityDefinitions</code> block.
   Second, that definition must be activated in a <code>security</code>
   block.
    </p>
<pre class="example" id="security-basic-example">
   ...
   "securityDefinitions": {
       "basic_sc": {
           "scheme": "basic",
           "in": "header"
       }
   },
   ...
   "security": ["basic_sc"]
   ...
</pre>

    <p>
    Here is a more complex example: a TD snippet showing digest 
    authentication on a proxy combined with bearer token authentication 
    on an endpoint.  
    Here the default 
    value of <code>in</code> in the <code>digest</code> scheme,
    <code>header</code>, is implied.
    </p>
<pre class="example" id="security-digest-example">
    ...
    "securityDefinitions": {
        "basic_sc": {
           "scheme": "digest",
           "proxy": "https://portal.example.com/"
        },
        "bearer_sc": {
           "in":"header",
           "scheme": "bearer",
           "format": "jwt",
           "alg": "ES256",
           "authorization": "https://servient.example.com:8443/"
        }
    },
    ...
    "security": ["basic_sc","bearer_sc"],
    ...
</pre>

    <p>
    Security configuration is mandatory. 
    <span class="rfc2119-assertion" id="td-security-mandatory">
    Every Thing MUST have at least one security scheme specified at the top level. 
    </span>
    <span class="rfc2119-assertion" id="td-security-overrides">
    Security schemes MAY also be specified at the form level.
    In this case, definitions at the form level override (completely replace)
    all definitions given at the top level. 
    </span>
    </p>
    <p>
    The <code>nosec</code> security scheme is provided for the case that 
    no security is needed.
    The minimal security configuration for a Thing is configuration 
    of the <code>nosec</code> security scheme 
    at the top level, as in the following example:
    </p>
<pre class="example">
{
    "id": "urn:dev:wot:com:example:servient:myThing",
    "name": "MyThing",
    "description": "Human readable information.",
    "support": "https://servient.example.com/contact",
    "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
    "security": ["nosec_sc"],
    "properties": {...},
    "actions": {...},
    "events": {...},
    "links": [...]
}
</pre> 

    <p>
    To give a more complex example, 
    suppose we have a Thing where all interactions
    require basic authentication except for one interaction for which
    no authentication is required.
    In the following, the <code>nosec</code> scheme for
    the security configuration in the <code>overheating</code> event 
    to indicate no authentication is required.  
    For the <code>status</code> property and the <code>toggle</code>
    action, however, <code>basic</code> authentication is required as defined
    at the top level of the Thing.
    </p>
<pre class="example">
{
    ...
    "securityDefinitions": {
        "nosec_sc": {"scheme": "nosec"},
        "basic_sc": {"scheme": "basic"}
    },
    "security": ["basic_sc"],
    ...
    "properties": {
        "status": {
            ...
            "forms": [{
                "href": "https://mylamp.example.com/status",
                "contentType": "application/json",
            }]
        }
    },
    "actions": {
        "toggle": {
            ...
            "forms": [{
                "href": "https://mylamp.example.com/toggle",
                "contentType": "application/json"
            }]
        }
    },
    "events": {
        "overheating": {
            ...
            "forms": [{
                "href": "https://mylamp.example.com/oh",
                "contentType": "application/json",
                "security": ["nosec_sc"] 
            }]
        }
    }
}
</pre>

      <p>
      Security configurations can also can be specified for different forms
      within the same interaction.  This may be required for devices that support
      multiple protocols, for example CoAP [[?RFC7252]] and HTTP, with support for different
      security mechanisms.  This is also useful when alternative authentication
      mechanisms are allowed.  Here is a TD snippet demonstrating three possible
      ways to access a resource: via HTTPS with basic authentication, via HTTPS
      via digest authentication, or via CoAPS with an API key.
      In other words, 
      the use of multiple security configurations at the same level 
      provides a way to combine security mechanisms an in "OR" fashion.
      In contrast, putting multiple security configurations in the same
      <code>security</code> member combines them in an "AND" fashion, 
      since in that case
      they would all need to be satisfied to allow access to the resource.
      Note that a <code>security</code> declaration is still mandatory at the 
      Thing level.  Here we use a <code>nosec</code> scheme for symmetry
      but could also have used any one of the other ones as it will be
      overridden in each form.
      </p>
<pre class="example">
    "securityDefinitions": {
        "nosec_sc": {"scheme": "nosec"},
        "basic_sc": {"scheme": "basic"},
        "digest_sc": {"scheme": "digest","qop":"auth","in":"header"},
        "apikey_sc": {"scheme": "apikey","in":"header"}
    },
    "security": ["nosec_sc"]
    ...
    "properties": {
        "status": {
            ...
            "forms": [
                {
                    "href": "https://mylamp.example.com/status",
                    "contentType": "application/json",
                    "security": ["basic_sc"]
                },
                {
                    "href": "https://mylamp.example.com/status",
                    "contentType": "application/json",
                    "security": ["digest_sc"]
                },
                {
                    "href": "coaps://mylamp.example.com:5683/status",
                    "contentType": "application/json",
                    "security": ["apikey_sc"]
                }
            ]
        }
    },
    ...
</pre>
  <p>As another more complex example, OAuth2 makes use of scopes. 
  These are identifiers that 
  may appear in tokens and must match with corresponding identifiers in a resource to allow 
  access to that resource. 
  For example, in the following, the "status" property can be 
  read by users using bearer tokens containing the scope "limited" 
  but the "configure" action can only be 
  used when the interaction is invoked with a token containing the "special" scope. 
  Scopes are not identical to roles but are often associated with them; 
  for example, perhaps only those in an administrative role can perform "special" interactions.
  Tokens can have more than one scope.  
  In this example, an administrator would
  probably be issued tokens with both the "limited" and "special" scopes while ordinary
  users would only be issued tokens with the "limited" scope.
  </p>
<pre class="example">
    ...
    "securityDefinitions": {
        "oauth2_sc": {
            "scheme": "oauth2",
            ...
            "scopes": ["limited","special"]
        }
    },
    "security": ["oauth2_sc"],
    "properties": {
        "status": {
            ...
            "forms": [
                {
                    "href": "https://scopes.example.com/status",
                    "contentType": "application/json",
                    "scopes": ["limited"]
                }
            ]
        }
    },
    "action": {
        "configure": {
            ...
            "forms": [
                {
                    "href": "https://scopes.example.com/configure",
                    "contentType": "application/json",
                    "scopes": ["special"]
                }
            ]
        }
    },
    ...
</pre>

</section> <!-- end of id="security-serialization-json"-->
<section id="version-serialization-json">
    <h2><code>version</code></h2>

    <p><span class="rfc2119-assertion" id="td-version">
        The mandatory vocabulary term
        as defined in the class <a href="#versioninfo" class="sec-ref"><code>VersionInfo</code></a>,
        MUST be serialized as a JSON name.
    </span></p>

    <p>The recommended version identification pattern value is to rely on the semantic versioning policy: [[?SemVer]]</p>

    <p>A TD snippet based on the defined members is given below:</p>
    <pre class="example">
        ...
        "version": {"instance":"1.2.1"}
        ...
    </pre>

    <p><span class="rfc2119-assertion" id="td-version-container">
        The version container MAY be used to provide additional application and/or device specific version information based on terms from non-TD namespaces. 
    </span></p>

    <p>A TD snippet based on such additional version metadata from a <code>v</code> context is given below:</p>
    <pre class="example">
        "@context": ["http://www.w3.org/ns/td",
                    {"v": "http://www.example.org/versioningTerms#"}],
        ...
        "version": {"instance":"1.2.1", "v:firmware": "0.9.1", "v:hardware": "1.0"}
        ...
    </pre>

    </section> <!-- end of id="version-json"-->

    <section id="data-schema-serialization-json">
            <h2>Data Schema Representation</h2>
            <p>The data schema concept within the Thing Description is based on a subset of JSON schema terms.  The data schema concept is applied 
                to the <a href="#event-serialization-json">properties</a> interaction declaration, <code>input</code> and <code>output</code> within <a href="#form-serialization-json">actions</a> 
                interaction declaration,  <code>subscription</code>, <code>data</code> and <code>cancellation</code> within <a href="#event-serialization-json">events</a> interaction declaration, 
                and <code>uriVariables</code> that can be used within the <a href="#form-serialization-json">forms</a> container. 
            </p>

            <p>
                <span class="rfc2119-assertion" id="td-data-schema">
                    Each mandatory and optional vocabulary term as defined in the class 
                        <a href="#dataschema" class="sec-ref"><code>DataSchema</code></a>,
                        MUST be serialized as a JSON name.
                 </span>
            </p>


            <p><span class="rfc2119-assertion" id="td-data-schema-objects">
                The type of the members <code>properties</code> and <code>items</code> 
                MUST be serialized as a JSON object.
                </span></p>

            <p><span class="rfc2119-assertion" id="td-data-schema-arrays">
                    The type of the member <code>enum</code>, <code>required</code>, and <code>oneOf</code> MUST be serialized as a JSON array.
                    </span></p>


                    <p>
                            A TD snippet based on the defined members is given below:
                            </p>
        <pre class="example">
        ...
        "type": "object",
        "properties": {
            "status": {
                "title": "Status",
                "type": "string",
                "enum": ["On", "Off", "Error"]
            },
            "brightness": {
                "title": "Brightness value",
                "type": "number",
                "minimum": 0.0,
                "maximum": 100.0
            },
            "rgb": {
                "title": "RGB color value",
                "type": "array",
                "items" : {
                    "type" : "number",
                    "minimum": 0,
                    "maximum": 255
                },
                "minItems": 3,
                "maxItems": 3
            }
        },
        ...
        </pre>

        <p>The terms <code>readOnly</code> and <code>writeOnly</code> MAY be used as hints to signalize which data members are 
            exchanged for a read request (e.g., read an interaction property) and which one for a write process 
            (e.g. write an interaction property).     
        </p>

        <p>
          An TD snippet with the usage of <code>readOnly</code> and <code>writeOnly</code> is given below:
        </p>
<pre class="example">
    ...
        "properties": {
            "status": {
              "description": "Read or write On/Off status.",
              "type": "object",
              "properties": {
                "latestStatus": {
                  "type": "string",
                  "enum": ["On", "Off"],
                  "readOnly": true
                },
                "newStatusValue": {
                  "type": "string",
                  "enum": ["On", "Off"],
                  "writeOnly": true
                }
              },
              forms:[...]
            }
          }
    ...
</pre>
<p>If the interaction property <code>status</code> is read, the status data is returned using <code>latestStatus</code> in the payload.
    To manipulate the status of the interaction property, the new value must be provided by assigning <code>newStatusValue</code> in 
    the payload. 
</p>

<p>As an additional feature, a Thing Description instance allows the usage of the term <code>unit</code> within data schema definitions.
    This can be used to associates some 
    unit information to some data members. The unit values can be
    free selected, however, it is recommended to select units based on existing definitions by integrating 
    the corresponding namespace context (e.g., from Smart Appliances REFerence (SAREF) ontology or Ontology of units of Measure (OM)).
</p>

<pre class="example">
    {
    "@context": ["http://www.w3.org/ns/td",
                {"om": "http://www.wurvoc.org/vocabularies/om-1.8/"}],
    ...
    "properties": {
        "latestValues": {
            "description": "Provides all current values of the weather station.",
            "type": "object",
            "properties": {
            "temperature": {
                "type": "number",
                "minimum" : -32.5,
                "maximum" : -55.2,
                "unit": "om:degree_Celsius"
            },
            "humidity": {
                "type": "number",
                "minimum" : 0,
                "maximum" : 100,
                "unit": "om:percent"
            }
            },
            forms:[...]
        }
    }
    ...
</pre>


    </section> <!-- end of id="data-schema-serialization-json"-->


    <section id="titles-descriptions-serialization-json">
            <h2><code>titles</code> and <code>descriptions</code></h2>

            <p>The vocabulary terms <code>titles</code> and <code>descriptions</code> enables human-readable text description in multi-languages using  
                language tags described in [[!BCP47]].
              <span class="rfc2119-assertion" id="td-multi-languages">
                  Whenever the vocabulary terms <code>titles</code> and <code>descriptions</code> can be used, both MUST be serialized as JSON Object. The member names of the JSON Object MUST be 
                  the language tags as defined in [[!BCP47]] (e.g., "en", "de", "ja", "zh-Hans", "zh-Hant"). The value of each member MUST be serialized as JSON string.
              </span>
            </p>

            <p>A TD snippet using <code>titles</code> and <code>descriptions</code> in different levels is given below: </p>

            <pre class="example">
                    {
                        "name": "MyThing",
                        "descriptions": {
                            "en":"Human readable information.",
                            "de": "Menschenlesbare Informationen.",
                            "ja" : "人間が読むことができる情報",
                            "zh-Hans" : "人们可阅读的信息", 
                            "zh-Hant" : "人們可閱讀的資訊"
                        },
                        ...
                        "properties": {
                            "on": {
                                "titles": {
                                    "en": "On/Off",
                                    "de": "An/Aus",
                                    "ja": "オンオフ",
                                    "zh-Hans": "开关",
                                    "zh-Hant": "開關" },
                                "type": "boolean",
                                "forms": [...]
                            },
                            "status": {
                                "titles": {
                                    "en": "Status",
                                    "de": "Zustand",
                                    "ja": "状態",
                                    "zh-Hans": "状态",
                                    "zh-Hant": "狀態" },
                                "type": "object",
                                ...
                    }
                    </pre>

    <p>TD instances may also additional use <code>title</code> and <code>description</code>  beside of <code>titles</code> and <code>descriptions</code>. 
        <span class="rfc2119-assertion" id="td-title-description">
              If <code>title</code> and <code>titles</code>   <code>description</code> and <code>descriptions</code> are defined at the same time at the JSON level,
              <code>title</code> and <code>description</code> MAY be seen as default text.
        </span>
          
    </p>

    <pre class="example">
            {
                "name": "MyThing",
                "description": "Menschenlesbare Informationen.",
                "descriptions": {
                    "en":"Human readable information.",
                    "de": "Menschenlesbare Informationen.",
                    "ja" : "人間が読むことができる情報",
                    "zh-Hans" : "人们可阅读的信息", 
                    "zh-Hant" : "人們可閱讀的資訊"
                },
                ...
                "properties": {
                    "on": {
                        "title" : "An/Aus",
                        "titles": {
                            "en": "On/Off",
                            "de": "An/Aus",
                            "ja": "オンオフ",
                            "zh-Hans": "开关",
                            "zh-Hant": "開關" },
                        "type": "boolean",
                        "forms": [...]
                    },
                    "status": {
                        "title" : "Zustand",
                        "titles": {
                            "en": "Status",
                            "de": "Zustand",
                            "ja": "状態",
                            "zh-Hans": "状态",
                            "zh-Hant": "狀態" },
                        "type": "object",
                        ...
            }
            </pre>


    </section> <!-- end of id="data-schema-serialization-json"-->


  </section> <!-- end of id="serialization-json"-->

  <section id="content-extension-section">
        <h1>Context Extension</h1>
 <p>In addition to the standard vocabulary definitions as defined in Section <a href="#sec-vocabulary-definition"></a>, the Thing Description offers the possibility to add
    context knowledge from different namespaces. This mechanism can be used to enrich the content of the Thing Description instances with additional 
    (e.g., domain specific) semantics. In addition, it can also be used to specify some configurations and behaviors of the underlying communication 
    protocols announced in the <code>forms</code> field.
 <p>
    For this extension the Thing Description uses the <code>@context</code> mechanism known from JSON-LD [[json-ld11]]. The usage and serialization of the <code>@context</code> 
    within the Thing Description is specified in Section <a href="#sec-thing-as-a-whole-json"></a>.
 </p>

 <p>
When adding additional vocabulary to a Thing Description instance, it is recommended that these vocabulary be linked to a namespace context that is within 
the JSON name <code>@context</code> container is specified.
</p>

<p>
If included namespaces are based on class definitions such as those provided by the RDF Schema or OWL, the Things Description also allows the use of 
 <code>@type</code> known from JSON-LD [[json-ld11]] to associate the affiliation to a class.
</p>


<pre class="example">
        {
            "@context": [
                "http://www.w3.org/ns/td",
                {"om": "http://www.wurvoc.org/vocabularies/om-1.8/"},
                {"saref": "https://w3id.org/saref#"}
            ],
            "@type": "Thing",
            ...
            "properties": {
                "Temperature": {
                    "@type": "saref:Temperature",
                    "description": "Temperature value of the weather station",
                    "om:unit_of_measure": "om:degree_Celsius",
                    "readOnly": true,
                    "observable": true,
                    "writeOnly": false,
                    "type": "number",
                    "forms" : [...]
                },
                ...
            }
        }
    </pre>

    <p>
    With the context extension in the Thing Description, communication metadata can be supplemented or specified in the declarations <code>forms</code>. 
    This is useful when default assumptions as defined in [[[!WOT-PROTOCOL-BINDING]]] need to be overwritten.</p>
    
    <p>The following example shows
    a property "brightness" that offers a read, write, and observe operation within the <code>forms</code> declaration. 
    </p>

    <aside class="example ds-selector-tabs changed" id="context-extension-for-forms" title="Specialization of the form definition by context extension.">
            <div class="selectors">
              <button class="selected" data-selects="ex-original">Simple</button>
              <button data-selects="ex-full">Full (JSON-LD 1.1)</button>
              <button data-selects="ex-rdf">RDF</button>
            </div>
<pre class="ex-original selected">{
        "@context": [
            "http://www.w3.org/ns/td",
            {
                "iot": "http://www.example.org/iot/",
                "htv": "http://www.w3.org/2011/http#"
            }
        ],
        ...
        "properties": {
            "brightness": {
                "description": "The current brightness setting",
                "@type": [
                    "iot:CurrentLevel",
                    "iot:LevelData"
                ],
                "type": "integer",
                "minimum": -64,
                "maximum": 64,
                "observable": true,
                    "forms": [
                    {
                        "href": "http://example.org:9191/api/brightness",
                        "op": ["readproperty"]
                    },
                    {
                        "href": "http://example.org:9191/api/brightness",
                        "op": ["writeproperty"],
                        "htv:methodName": "POST"
                    },
                    {
                        "href": "http://example.org:9191/api/brightness/observe",
                        "op": ["observeproperty"],
                        "htv:methodName": "GET",
                        "subProtocol": "longpoll"
                    }
                ]
            }
        }
    }</pre>
<pre class="ex-full">{
        "@context": [
            "http://www.w3.org/ns/td",
            {
                "iot": "http://www.example.org/iot/",
                "htv": "http://www.w3.org/2011/http#"
            }
        ],
        ...
        "properties": {
            "brightness": {
                "description": "The current brightness setting",
                "@type": [
                    "iot:CurrentLevel",
                    "iot:LevelData"
                ],
                "type": "integer",
                "minimum": -64,
                "maximum": 64,
                "observable": true,
                "forms": [
                    {
                        "href": "http://example.org:9191/api/brightness",
                        "contentType": "application/json",
                        "op": ["readproperty"]
                    },
                    {
                        "href": "http://example.org:9191/api/brightness",
                        "contentType": "application/json",
                        "op": ["writeproperty"],
                        "htv:methodName": "POST"
                    },
                    {
                        "href": "http://example.org:9191/api/brightness/observe",
                        "contentType": "application/json",
                        "op": ["observeproperty"],
                        "htv:methodName": "GET",
                        "subProtocol": "longpoll"
                    }
                ]
            }
        }
    }</pre>
    <pre class="ex-rdf">_:b0 &lt;http://www.w3.org/ns/td#properties&gt; _:b1 .
_:b1 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://w3.org/ns/json-schema#IntegerSchema&gt; .
_:b1 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://www.example.org/iot/CurrentLevel&gt; .
_:b1 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://www.example.org/iot/LevelData&gt; .
_:b1 &lt;http://www.w3.org/ns/json-schema#maximum&gt; &quot;64&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
_:b1 &lt;http://www.w3.org/ns/json-schema#minimum&gt; &quot;-64&quot;^^&lt;http://www.w3.org/2001/XMLSchema#integer&gt; .
_:b1 &lt;http://www.w3.org/ns/td#description&gt; &quot;The current brightness setting&quot; .
_:b1 &lt;http://www.w3.org/ns/td#forms&gt; _:b2 .
_:b1 &lt;http://www.w3.org/ns/td#forms&gt; _:b3 .
_:b1 &lt;http://www.w3.org/ns/td#forms&gt; _:b4 .
_:b1 &lt;http://www.w3.org/ns/td#observable&gt; &quot;true&quot;^^&lt;http://www.w3.org/2001/XMLSchema#boolean&gt; .
_:b2 &lt;http://www.w3.org/ns/td#contentType&gt; &quot;application/json&quot; .
_:b2 &lt;http://www.w3.org/ns/td#href&gt; &quot;http://example.org:9191/api/brightness&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b2 &lt;http://www.w3.org/ns/td#op&gt; &quot;readproperty&quot; .
_:b3 &lt;http://www.w3.org/2011/http#methodName&gt; &quot;POST&quot; .
_:b3 &lt;http://www.w3.org/ns/td#contentType&gt; &quot;application/json&quot; .
_:b3 &lt;http://www.w3.org/ns/td#href&gt; &quot;http://example.org:9191/api/brightness&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b3 &lt;http://www.w3.org/ns/td#op&gt; &quot;writeproperty&quot; .
_:b4 &lt;http://www.w3.org/2011/http#methodName&gt; &quot;GET&quot; .
_:b4 &lt;http://www.w3.org/ns/td#contentType&gt; &quot;application/json&quot; .
_:b4 &lt;http://www.w3.org/ns/td#href&gt; &quot;http://example.org:9191/api/brightness/observe&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b4 &lt;http://www.w3.org/ns/td#op&gt; &quot;observeproperty&quot; .
</pre>
        </aside>

        <p>For the read operation, the corresponding form declaration follows the default assumption to execute an HTTP GET as defined  
            in [[[!WOT-PROTOCOL-BINDING]]]. The write operation overwrites the default assumption (= HTTP PUT) and 
            declares with the context extension the HTTP POST method to be used for this operation. In order to observe this property, the 
            context extension is used here to announce that an HTTP GET is always running to follow the long poll mechanism.          
        </p>

 </section>

  <section id="media-type-section">  
  <h1>Media Type</h1>

  <p>
  The JSON-based serialization of the TD is identified by 
  the media type [[!IANA-MEDIA-TYPES]] <code>application/td+json</code>.
  </p>

  <p class="ednote" title="CoAP Content Format">
  CoAP-based WoT implementations can use the experimental Content-Format
  <code>65100</code> until a proper identifier has been registered.
  </p>

  <p><span class="rfc2119-assertion" id="td-media-type">
  The media type <code>application/td+json</code>
  MUST be also associated with the JSON-LD context 
  <code>http://www.w3.org/ns/td</code>.
  </span>
  That means that this media type can also be used for contextual  
  identification of the vocabulary within a (simplified) TD instance 
  that may omit the <code>@context</code> name term.
  </p>

  <p class="ednote" title="IANA Considerations">
  Neither the <code>application/td+json</code> content type nor
  a CoAP Content-Format identifier have been registered with IANA yet.
  </p>

  </section>

</section> <!-- end of id="sec-td-serialization"-->

<section id="behavior">
<h2>Behavioral Constraints</h2>
 <p>
 The following assertions relate to the behavior of components of a 
 WoT system, as opposed to the representation or information model of the TD. 
 However, note that TDs are descriptive, 
 and must in particular may be used to describe pre-existing network interfaces. 
 In these cases, assertions cannot be made that constrain the behaviour of such 
 pre-existing interfaces.  Instead, the assertions must be interpreted as 
 constraints on the TD to accurately represent such interfaces. 
 </p> 
<section id="behavior-security">
<h3>Security Behavior</h3>
 <p>
 To enable secure interoperation, 
 security configurations must accurately reflect the requirements of the Thing:
<ul>
<li>
 <span class="rfc2119-assertion" id="td-security-binding">
 If a Thing requires a specific access mechanism for a resource, that 
 mechanism MUST be specified in the Thing Description's security scheme configuration 
 for that resource. 
 </span>  
</li>
<li>
 <span class="rfc2119-assertion" id="td-security-no-extras">
 If a Thing does not require a specific access mechanism for a resource, that 
 mechanism MUST NOT be specified in the Thing Description's security scheme configuration 
 for that resource. 
 </span>  
</li>
</ul>
 Some security protocols may ask for authentication 
 information dynamically, including required encoding or encryption schemes. 
 One consequence of the above is that if a protocol asks for
 a form of security credentials or an encoding or encryption scheme 
 not declared in the Thing Description 
 then the Thing Description is to be considered invalid.
 </p>
</section> <!-- end of id="behavior-security"-->
<section id="behavior-data">
<h3>Data Constraints</h3>
<p>The data schemas provided in the TD should accurately represent the 
data payloads returned and accepted by the described Thing
in the interactions specified in the TD.  In general, clients should
follow the data schemas strictly, not generating anything not given
in the WoT Thing Description, but should accept additional data from
the server not given explicitly in the WoT Thing Decription for that
server.  In general, servers are <em>described</em> by WoT Thing Descriptions,
but clients are <em>constrained</em> to follow WoT Thing Descriptions when
interacting with servers.
<ul>
<li>
<span class="rfc2119-assertion" 
      id="client-data-schema">
A WoT Thing acting as a client when interacting with another target Thing 
described in a WoT Thing Description MUST generate data  
organized according to the data schemas given in the corresponding
interactions.
</span>
</li>
<li>
<span class="rfc2119-assertion" 
      id="server-data-schema">
A WoT Thing Description describing a server MUST accurately describe the 
data returned and accepted by each interaction.
</span>
</li>
<li>
<span class="rfc2119-assertion" 
      id="server-data-schema-extras">
A WoT Thing acting as a server MAY return additional data from an interaction  
even when such data is 
not described in the data schemas given in the target Thing's WoT Thing Description.
</span>
</li>
<li>
<span class="rfc2119-assertion" 
      id="client-data-schema-accept-extras">
A WoT Thing acting as a client when interacting with another Thing MUST accept without
error any additional data  
not described in the data schemas given in the target Thing's WoT Thing Description.
</span>
</li>
<li>
<span class="rfc2119-assertion" 
      id="client-data-schema-no-extras">
A WoT Thing acting as a client when interacting with another Thing MUST NOT generate data  
not described in the data schemas given in that Thing's WoT Thing Description.
</span>
</li>
<li>
<span class="rfc2119-assertion" 
      id="client-uri-template">
A WoT Thing acting as a client when interacting with another Thing MUST generate URIs 
according to the URI templates, base URLs, and form href parameters 
given in the target Thing's WoT Thing Description.
</span>
</li>
<li>
<span class="rfc2119-assertion" 
      id="server-uri-template">
URI templates, base URLs, and form href parameters 
in a WoT Thing Description MUST accurately describe URIs
returned by a target Thing acting as a server.
</span>
</li>
</ul>
</p>
</section> <!-- end of id="behavior-data"-->
</section> <!-- end of id="behavior"-->

  <section id="example-serialization" class="informative">
  <h2>Example Thing Description Instances</h2>

  <section id="myLampThing-example-serialization">
  <h3>MyLampThing Example with CoAP Binding</h3>

  <p>Feature list of the Thing:</p>

  <ul>
      <li>Name: MyLampThing</li>
      <li>Context extension: none</li>
      <li>Offered interactions: 1 property, 1 action, 1 event</li>
      <li>Security: PSKSecurityScheme</li>
      <li>Protocol binding: CoAP [[?RFC7252]] over TLS</li>
      <li>Serializiation: default (JSON)</li>
      <li>Comment: none</li>

  </ul>

<pre class="example" title="MyLampThing represented as a compact JSON serialization">
{
    "id": "urn:dev:wot:com:example:servient:lamp",
    "name": "MyLampThing",
    "description" : "MyLampThing uses JSON serialization",
    "securityDefinitions": {"psk_sc":{"scheme": "psk"}},
    "security": ["psk_sc"],
    "properties": {
        "status": {
            "description" : "Shows the current status of the lamp",
            "type": "string",
            "forms": [{
                "href": "coaps://mylamp.example.com/status"
            }]
        }
    },
    "actions": {
        "toggle": {
            "description" : "Turn on or off the lamp",
            "forms": [{
                "href": "coaps://mylamp.example.com/toggle"
            }]
        }
    },
    "events": {
        "overheating": {
            "description" : "Lamp reaches a critical temperature (overheating)",
            "data": {"type": "string"},
            "forms": [{
                "href": "coaps://mylamp.example.com/oh"
            }]
        }
    }
}
</pre>
</section>

  <section id="myLampThing-example-serialization">
  <h3>MyLightSensor Example with MQTT Binding</h3>

  <p>Feature list of the Thing:</p>

  <ul>
      <li>Name: MyLightSensor</li>
      <li>Context extension: none</li>
      <li>Offered interactions: 1 event</li>
      <li>Security: none</li>
      <li>Protocol binding: MQTT [[?MQTT]]</li>
      <li>Serializiation: text </li>
      <li>Comment: An MQTT client frequently publishes the light sensor data (number is serialized in text format) to 
          the topic /lightSensor by the MQTT broker running behind the address 192.168.1.187:1883. </li>
  </ul>

<pre class="example" title="MyLightSensor with MQTT binding">
        {
            "name": "MyLightSensor",
            "id": "urn:dev:wot:com:example:servient:lightsensor",
            "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
            "security": ["nosec_sc"],
            "events": {
                "lightSensor": {
                    "data":{"type": "integer"},
                    "forms": [
                        {
                            "href": "mqtt://192.168.1.187:1883/lightSensor",
                            "contentType" : "text/plain"
                        }
                    ]
                }
            } 
        }
</pre>
  </section>


  <section id="t2t-event-example-serialization">
    <h3>Thing-2-Thing (T2T) Event Example</h3>
  
    <p>Feature list of the Thing:</p>
  
    <ul>
        <li>Name: TemperatureForT2T</li>
        <li>Context extension: include HTTP (by htv prefix) vocabulary set</li>
        <li>Offered interactions: 1 event</li>
        <li>Security: none</li>
        <li>Protocol binding: HTTP</li>
        <li>Serializiation: default (JSON) </li>
        <li>Comment: <i>TemperatureForT2T</i> Thing provides an event <i>temperatureValueForT2T</i>, with which an instruction can be passed, to which other Thing the periodically provided temperature values are to be sent.
            Doing this, the <code>subscription</code> container defines an input to which target URL the temperature value (defined within the <code>data</code> container) 
            has to be sent. To submit such information, a client must call the resource http://192.168.0.124:8080/events/TempForT2T/subscribe (via the POST method) and 
            provide the target URL information in the payload (JSON serialization).  As defined in the output container, 
            the <i>TemperatureForT2T</i> Thing would response with a subscription ID that can be used, e.g., for cancellation the subscription (as defined in the <code>cancellation</code> 
            container). 
        </li>
    </ul>
  
  <pre class="example" title="Temperature event with subscripton and cancellation for a Thing-2-Thing interaction">
        {
            "@context": [
                "http://www.w3.org/ns/td",
                {"htv": "http://www.w3.org/2011/http#"}],
            "id": "urn:dev:wot:org:eclipse:thingweb:event-example",
            "name": "TemperatureForT2T",
            "description": "Event with subscription / cancellation (Thing-2-Thing use case).",
            "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
            "security": ["nosec_sc"],
            "events": {
                "temperatureValueForT2T": {
                    "description": "Provides periodic temperature values as event affordance.",
                    "subscription": {
                        "input": {
                            "targetURL": {
                                "type": "string",
                                "format": "uri",
                                "description": "Requester provides target URL to initate T2T."
                        }},
                        "output": {
                            "subscriptionID": {
                                "type": "integer",
                                "description": "Responses an unique subscription ID."
                        }}
                    },
                    "data": {
                        "type": "number",
                        "description": "Actual temperature value that is sent to the target URL. "
                    },
                    "cancellation": {
                        "input": {
                            "subscriptionID": {
                                "type": "integer",
                                "writeOnly": true,
                                "description": "Provide subscription ID that have to be cancelled."
                    }}},
                    "forms": [
                        {
                            "href": "http://192.168.0.124:8080/events/TempForT2T/subscribe",
                            "op": ["subscribeevent"],
                            "htv:methodName": "POST",
                            "contentType": "application/json"
                        },
                        {
                            "href": "http://192.168.0.124:8080/events/TempForT2T/unsubscribeevent",
                            "op": ["unsubscribeevent"],
                            "htv:methodName": "PUT",
                            "contentType": "application/json"
                        }
                    ]
            }}
        }
  </pre>
    </section>

  </section>

  <section id="sec-security-consideration" class="informative">
  <h4>Security and Privacy Considerations</h4>
  
  <p>
  In general the security measures taken to protect a WoT 
  system will depend on the threats and attackers that system
  may face and the value of the assets needs to protect.
  A detailed discussion of security and privacy considerations for the Web of Things,
  including a threat model that can be adapted to various circumstances, is
  presented in the informative document [[!WOT-SECURITY-CONSIDERATIONS]].  
  This section discusses only security and privacy risks
  and possible mitigations directly relevant to the WoT Thing Description.
  </p>
  <p>A WoT Thing Description can describe both secure and 
  insecure network interfaces.  When a Thing Description is 
  retro-fitted to an existing network interface, no change in the 
  security status of the network interface is to be expected.
  </p>
  <p>
  When designing new devices and services for use with the WoT,
  we have documented a suggested set of best practices
  in [[!WOT-SECURITY-BEST-PRACTICES]] to improve security.
  This best-practices document may be updated as security measures evolve.
  Following these practices does not guarantee security, 
  but it at least will help to avoid common known vulnerabilities.
  </p>
  <p>The use of a WoT Thing Description introduces  
  the security and privacy risks given in the following sections.
  After each risk, we suggest some possible mitigations.
  </p>
  <section id="sec-security-consideration-context">
  <h5>Context Dereferencing Privacy Risk</h5>
      <p>Deferencing the vocabulary files given in the <code>@context</code>
          member of any JSON-LD [[json-ld11]] document can be a privacy risk.
          In the case of the WoT, an attacker can observe the network
          traffic produced by such deferences and can use the metadata
          of the dereference, such as the destination IP address,
          to infer information about the device especially if domain-specific
          vocabularies are used.  This is a risk even if the connection
          is encrypted, and is related to DNS privacy leaks.
      </p>
      <dl><dt>Mitigation:</dt><dd>
          Avoid actual dereferencing of vocabulary files.
          Vocabulary files should be cached whenever possible.
          Ideally they would be made immutable, built into the interpreting device,
          and not derefenced at all,
          with the URI in the <code>@context</code> member serving only as 
          an identifier of the (known) vocabulary. 
          This requires the use of strict version control, as updates
          should use a new URI to ensure that existing URIs can refer to 
          immutable data.
          Use well-known standard vocabulary files whenever possible to
          improve the chances that the context file will be available locally
          to systems interpreting the metadata in a Thing Description.
      </dd></dl>
   </section>
   <section id="sec-security-consideration-id">
   <h5>Immutable Identifiers Privacy Risk</h5>
      <p>The fact that a Thing Description contains a unique
          identifier means that should it be associated with
          a person it can be used to track that person and 
          therefore pose a risk to privacy.
      </p>
      <dl><dt>Mitigation:</dt><dd>
          All identifiers should be mutable,
          and there should be a mechanism to update the <code>id</code>
          of a Thing.
          Specifically,
          the <code>id</code> of a Thing should not be fixed in hardware.
          This does, however, conflict with the Linked Data ideal that
          identifiers are fixed URIs.  In many circumstances it
          will be acceptable to only allow updates to identifiers if
          a Thing is reinitialized.  In this case as a software entity the
          old Thing ceases to exist and a new Thing is created.
          This can be sufficient to break a tracking chain when, for
          example, a device is sold to a new owner.
          Alternatively, if more frequent changes are desired during 
          the operational phase of a device,
          a mechanism can be put into place to notify only authorized users
          of the change in identifier when a change is made.
          Note however that some classes of devices, e.g. medical devices,
          may require immutable IDs by law in some jurisdictions.
          In this case extra attention should be paid to secure 
          access to files, such as Thing Descriptions, containing such
          immutable identifiers.
          </dd></dl>
      </p>
   </section>
   <section id="sec-security-consideration-fingerprint">
   <h5>Fingerprinting Privacy Risk</h5>
      <p>As noted above, the <code>id</code> member in a TD can pose a privacy risk.  
      However, even if the <code>id</code> is updated as described to mitigate its
      tracking risk, it may still be possible to associate
      a TD with a particular physical device, and from there to a person, through fingerprinting.
      </p>
      <dl><dt>Mitigation:</dt><dd>
          Only authorized users should be provided access
          to the Thing Description for a Thing.
          If the TD is only distributed to authorized users 
          through secure and confidential channels, for
          example through a directory service that requires authentication,
          the risk can be minimized.  
      </dd></dl>
   </section>
   <section id="sec-security-consideration-tampering">
   <h5>TD Interception and Tampering Security Risk</h5>
      <p>Intercepting and tampering with TDs can be used to launch man-in-the-middle attacks,
      for example by rewriting URLs in TDs to redirect accesses to a malicious 
      intermediary that can capture or manipulate data.
      </p>
      <dl><dt>Mitigation:</dt><dd>
          Obtain Thing Descriptions only through
          mutually authenticated channels.
          This ensures that the client and the server are both sure of the 
          identity of the other party to the communication.
          This is also necessary in order to deliver TDs only to authorized users.
      </dd></dl>
   </section>
   <section id="sec-security-consideration-tampering">
   <h5>Context Interception and Tampering Security Risk</h5>
      <p>Intercepting and tampering with context files can be used to facilitate attacks
      by modifying the interpretation of vocabulary. 
      </p>
      <dl><dt>Mitigation:</dt><dd>
	      Ideally context files would only be obtained through authenticated channels
	      but it is notable (and unfortunate) that many contexts are indicated using
	      HTTP URLs, which are vulnerable to interception and modification if 
	      dereferenced.  However, if context files are immutable and cached, 
	      and dereferencing is avoided whenever possible, then this risk can be reduced.
      </dd></dl>
   </section>
   <section id="sec-security-consideration-inferencing">
   <h5>Inferencing of Personally Identifiable Information Privacy Risk</h5>
      <p>In many locales, in order to protect the privacy of users,
      there are legal requirements for the handling of
      personally identifiable information,
      that is,
      information that can be associated with a particular person.
      Such information can of course be generated by IoT devices directly.
      However,
      the existence and metadata of IoT devices
      (the kind of data stored in a Thing Description)
      can also contain or be used to infer personally identifiable information.
      This information can be as simple as the fact that a certain person owns a certain
      type of device,
      which can lead to additional inferences about that person.
      </p>
      <dl><dt>Mitigation:</dt><dd>
          Treat a Thing Description associated with a 
	      personal device as if it contained
	      personally identifiable information.
          As an example application of this principle,
          consider how to obtain user consent.  
          Consent for usage of personally identifiable data
          generated by a Thing is often obtained when a Thing is paired with system
          consuming the data,
          which is frequently also when the Thing Description
          is registered with a local directory or the system consuming the 
          Thing Description in order to access the device.
          In this case consent for using data from a Thing can be combined with
          consent for accessing the Thing's Thing Description.
          As a second example, if we consider a TD to contain personally
          identifiable information, then it should not be retained indefinitely
          or used for purposes other than those for which consent was given.
      </dd></dt>
  </section>

  </section>

  <section id="json-schema-4-validation" class="appendix normative">
  <h1>JSON Schema for TD Instance Validation</h1>
  <p>Below are two JSON Schema [[?JSON-SCHEMA-VALIDATION]] documents (one for the <i>Simple</i> and <i>Full</i> TD representation form) for syntactically validating Thing Description instances serialized in 
  JSON based format.
</p>
  <p class="note">The Thing Description defined by this document allows for 
    adding external vocabularies by using <code>@context</code> mechanism 
    known from JSON-LD [[json-ld11]], and the terms in those external vocabularies can be 
    used in addition to the terms defined in Section <a href="#sec-vocabulary-definition"></a>. 
    For this reason, the below JSON schema is intentionally non-strict in that 
    regard. You can replace the value of <code>additionalProperties</code> schema 
    property <code>true</code> with <code>false</code> in different scopes/levels in 
    order to perform a stricter validation in case no external vocabularies are used.
</p>

<section id="json-schema-4-validation-simple">
        <h2>JSON Schema for <i>Simple</i> TD Validation</h2>
        <p>
        JSON Schema for validating TD instances in <i>Simple</i> form 
        (checks, if all manditory terms without default values from the TD model are present; also see <a href="#json-serializiation-section"></a>).  
    </p>
        <pre class="advisement">
    {
    "title": "WoT TD Schema - March 2019",
    "description": "JSON Schema representation of the TD serialisation format. This schema validates a plain JSON TD which doesn't have to contain vocabulary terms defined in 5.1.1",
    "$schema ": "http://json-schema.org/draft-06/schema#",
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "format": "uri"
        },
        "name": {
            "type": "string"
        },
        "properties": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/property_element"
            }
        },
        "actions": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/action_element"
            }
        },
        "events": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/event_element"
            }
        },
        "description": {
            "$ref": "#/definitions/description"
        },
        "descriptions": {
            "$ref": "#/definitions/descriptions"
        },
        "version": {
            "type": "object",
            "properties": {
                "instance": {
                    "type": "string"
                }
            },
            "required": [
                "instance"
            ]
        },
        "links": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/link_element"
            }
        },
        "forms": {
            "type": "array",
            "minItems": 1,
            "items": {
                "$ref": "#/definitions/form_element_root"
            }
        },
        "base": {
            "$ref": "#/definitions/url"
        },
        "securityDefinitions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
                "$ref": "#/definitions/securityScheme"
            }
        },
        "support": {
            "type": "string"
        },
        "created": {
            "type": "string"
        },
        "lastModified": {
            "type": "string"
        },
        "security": {
            "type": "array",
            "minItems": 1,
            "items": {
                "type": "string"
            }
        },
        "@type": {
            "$ref": "#/definitions/type_declaration"
        },
        "@context": {
            "$ref": "#/definitions/thing-context"
        }
    },
    "required": [
        "name",
        "id",
        "security",
        "securityDefinitions"
    ],
    "additionalProperties": true,
    "definitions": {
        "thing-context": {
            "oneOf": [{
                    "type": "array",
                    "items": {
                        "anyOf": [{
                                "$ref": "#/definitions/url"
                            },
                            {
                                "type": "object"
                            }
                        ]
                    },
                    "contains": {
                        "type": "string",
                        "enum": [
                            "http://www.w3.org/ns/td", "http://w3.org/ns/td"
                        ]
                    }
                },
                {
                    "type": "string",
                    "enum": [
                        "http://www.w3.org/ns/td", "http://w3.org/ns/td"
                    ]
                }
            ]
        },
        "security-context": {
            "oneOf": [{
                    "type": "array",
                    "items": {
                        "anyOf": [{
                                "$ref": "#/definitions/url"
                            },
                            {
                                "type": "object"
                            }
                        ]
                    },
                    "contains": {
                        "type": "string",
                        "enum": [
                            "https://www.w3.org/ns/wot-security", "https://w3.org/ns/wot-security"
                        ]
                    }
                },
                {
                    "type": "string",
                    "enum": [
                        "https://www.w3.org/ns/wot-security", "https://w3.org/ns/wot-security"
                    ]
                }
            ]
        },
        "data-context": {
            "oneOf": [{
                    "type": "array",
                    "items": {
                        "anyOf": [{
                                "$ref": "#/definitions/url"
                            },
                            {
                                "type": "object"
                            }
                        ]
                    },
                    "contains": {
                        "type": "string",
                        "enum": [
                            "https://www.w3.org/ns/json-schema", "https://w3.org/ns/json-schema"
                        ]
                    }
                },
                {
                    "type": "string",
                    "enum": [
                        "https://www.w3.org/ns/json-schema", "https://w3.org/ns/json-schema"
                    ]
                }
            ]
        },
        "type_declaration": {
            "oneOf": [{
                    "type": "string"
                },
                {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            ]
        },
        "property_element": {
            "type": "object",
            "properties": {
                "@context": {
                    "$ref": "#/definitions/data-context"
                },
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "description": {
                    "$ref": "#/definitions/description"
                },
                "title": {
                    "$ref": "#/definitions/title"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "uriVariables": {
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "forms": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/form_element_property"
                    }
                },
                "observable": {
                    "type": "boolean"
                },
                "writeOnly": {
                    "type": "boolean"
                },
                "readOnly": {
                    "type": "boolean"
                },
                "oneOf": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "unit": {
                    "type": "string"
                },
                "enum": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true
                },
                "format": {
                    "type": "string"
                },
                "const": {},
                "type": {
                    "type": "string",
                    "enum": [
                        "boolean",
                        "integer",
                        "number",
                        "string",
                        "object",
                        "array",
                        "null"
                    ]
                },
                "items": {
                    "oneOf": [{
                            "$ref": "#/definitions/dataSchema"
                        },
                        {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/dataSchema"
                            }
                        }
                    ]
                },
                "maxItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minimum": {
                    "type": "number"
                },
                "maximum": {
                    "type": "number"
                },
                "properties": {
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "required": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": [
                "forms"
            ],
            "additionalProperties": true
        },
        "action_element": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "title": {
                    "type": "string"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "uriVariables": {
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "forms": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/form_element_action"
                    }
                },
                "input": {
                    "$ref": "#/definitions/dataSchema"
                },
                "output": {
                    "$ref": "#/definitions/dataSchema"
                },
                "safe": {
                    "type": "boolean"
                },
                "idempotent": {
                    "type": "boolean"
                }
            },
            "required": [
                "forms"
            ],
            "additionalProperties": true
        },
        "event_element": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string"
                },
                "title": {
                    "type": "string"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "uriVariables": {
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "forms": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/form_element_event"
                    }
                },
                "subscription": {
                    "$ref": "#/definitions/dataSchema"
                },
                "data": {
                    "$ref": "#/definitions/dataSchema"
                },
                "cancellation": {
                    "$ref": "#/definitions/dataSchema"
                },
                "type": {
                    "not": {}
                },
                "enum": {
                    "not": {}
                },
                "const": {
                    "not": {}
                }
            },
            "required": [
                "forms"
            ],
            "additionalProperties": true
        },
        "form_element_property": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [{
                            "type": "string",
                            "enum": [
                                "readproperty",
                                "writeproperty",
                                "observeproperty",
                                "unobserveproperty"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "readproperty",
                                    "writeproperty",
                                    "observeproperty",
                                    "unobserveproperty"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll",
                        "websub",
                        "sse"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "form_element_action": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [{
                            "type": "string",
                            "enum": [
                                "invokeaction"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "invokeaction"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll",
                        "websub",
                        "sse"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "form_element_event": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [{
                            "type": "string",
                            "enum": [
                                "subscribeevent",
                                "unsubscribeevent"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "subscribeevent",
                                    "unsubscribeevent"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll",
                        "websub",
                        "sse"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "form_element_root": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [{
                            "type": "string",
                            "enum": [
                                "readallproperties",
                                "writeallproperties",
                                "readmultipleproperties",
                                "writemultipleproperties"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "readallproperties",
                                    "writeallproperties",
                                    "readmultipleproperties",
                                    "writemultipleproperties"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll",
                        "websub",
                        "sse"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "description": {
            "type": "string"
        },
        "title": {
            "type": "string"
        },
        "descriptions": {
            "type": "object"
        },
        "titles": {
            "type": "object"
        },
        "dataSchema": {
            "type": "object",
            "properties": {
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "description": {
                    "$ref": "#/definitions/description"
                },
                "title": {
                    "$ref": "#/definitions/title"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "writeOnly": {
                    "type": "boolean"
                },
                "readOnly": {
                    "type": "boolean"
                },
                "oneOf": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "unit": {
                    "type": "string"
                },
                "enum": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true
                },
                "format": {
                    "type": "string"
                },
                "const": {},
                "type": {
                    "type": "string",
                    "enum": [
                        "boolean",
                        "integer",
                        "number",
                        "string",
                        "object",
                        "array",
                        "null"
                    ]
                },
                "items": {
                    "oneOf": [{
                            "$ref": "#/definitions/dataSchema"
                        },
                        {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/dataSchema"
                            }
                        }
                    ]
                },
                "maxItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minimum": {
                    "type": "number"
                },
                "maximum": {
                    "type": "number"
                },
                "properties": {
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "required": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "link_element": {
            "type": "object",
            "properties": {
                "anchor": {
                    "$ref": "#/definitions/url"
                },
                "href": {
                    "$ref": "#/definitions/url"
                },
                "rel": {
                    "type": "string"
                },
                "type": {
                    "type": "string"
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "securityScheme": {
            "oneOf": [{
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "nosec"
                            ]
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "basic"
                            ]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "cert"
                            ]
                        },
                        "identity": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "digest"
                            ]
                        },
                        "qop": {
                            "type": "string",
                            "enum": ["auth", "auth-int"]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "bearer"
                            ]
                        },
                        "authorization": {
                            "$ref": "#/definitions/url"
                        },
                        "alg": {
                            "type": "string",
                            "enum": ["MD5", "ES256", "ES512-256"]
                        },
                        "format": {
                            "type": "string",
                            "enum": ["jwt", "jwe", "jws"]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "psk"
                            ]
                        },
                        "identity": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "public"
                            ]
                        },
                        "identity": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "oauth2"
                            ]
                        },
                        "authorization": {
                            "$ref": "#/definitions/url"
                        },
                        "token": {
                            "$ref": "#/definitions/url"
                        },
                        "refresh": {
                            "$ref": "#/definitions/url"
                        },
                        "scopes": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        },
                        "flow": {
                            "type": "string",
                            "enum": ["implicit", "password", "client", "code"]
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "apikey"
                            ]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "pop"
                            ]
                        },
                        "authorization": {
                            "$ref": "#/definitions/url"
                        },
                        "format": {
                            "type": "string",
                            "enum": ["jwt", "jwe", "jws"]
                        },
                        "alg": {
                            "type": "string",
                            "enum": ["MD5", "ES256", "ES512-256"]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                }
            ]
        },
        "url": {
            "type": "string",
            "format": "uri-reference"
        }
    }
}

    </pre>
</section>

<section id="json-schema-4-validation-full">
        <h2>JSON Schema for <i>Full</i> TD Validation</h2>
        <p>
        JSON Schema for validating TD instances in <i>Full</i> form (checks, if all manditory terms from the TD model are present; also see <a href="#json-serializiation-section"></a>).  
    </p>
        <pre class="advisement">
        {
    "title": "WoT TD Schema - March 2019",
    "description": "JSON Schema representation of the TD serialisation in JSON-LD format. For a TD to validate this schema it must contain all the term defined in section 5.1.1",
    "$schema ": "http://json-schema.org/draft-06/schema#",
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "format": "uri"
        },
        "name": {
            "type": "string"
        },
        "properties": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/property_element"
            }
        },
        "actions": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/action_element"
            }
        },
        "events": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/event_element"
            }
        },
        "description": {
            "$ref": "#/definitions/description"
        },
        "descriptions": {
            "$ref": "#/definitions/descriptions"
        },
        "version": {
            "type": "object",
            "properties": {
                "instance": {
                    "type": "string"
                }
            },
            "required": [
                "instance"
            ]
        },
        "links": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/link_element"
            }
        },
        "forms": {
            "type": "array",
            "minItems": 1,
            "items": {
                "$ref": "#/definitions/form_element_root"
            }
        },
        "base": {
            "$ref": "#/definitions/url"
        },
        "securityDefinitions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
                "$ref": "#/definitions/securityScheme"
            }
        },
        "support": {
            "type": "string"
        },
        "created": {
            "type": "string"
        },
        "lastModified": {
            "type": "string"
        },
        "security": {
            "type": "array",
            "minItems": 1,
            "items": {
                "type": "string"
            }
        },
        "@type": {
            "$ref": "#/definitions/type_declaration"
        },
        "@context": {
            "$ref": "#/definitions/thing-context"
        }
    },
    "required": [
        "name",
        "id",
        "security",
        "securityDefinitions",
        "@context"
    ],
    "additionalProperties": true,
    "definitions": {
        "thing-context": {
            "oneOf": [{
                    "type": "array",
                    "items": {
                        "anyOf": [{
                                "$ref": "#/definitions/url"
                            },
                            {
                                "type": "object"
                            }
                        ]
                    },
                    "contains": {
                        "type": "string",
                        "enum": [
                            "http://www.w3.org/ns/td", "http://w3.org/ns/td"
                        ]
                    }
                },
                {
                    "type": "string",
                    "enum": [
                        "http://www.w3.org/ns/td", "http://w3.org/ns/td"
                    ]
                }
            ]
        },
        "security-context": {
            "oneOf": [{
                    "type": "array",
                    "items": {
                        "anyOf": [{
                                "$ref": "#/definitions/url"
                            },
                            {
                                "type": "object"
                            }
                        ]
                    },
                    "contains": {
                        "type": "string",
                        "enum": [
                            "https://www.w3.org/ns/wot-security", "https://w3.org/ns/wot-security"
                        ]
                    }
                },
                {
                    "type": "string",
                    "enum": [
                        "https://www.w3.org/ns/wot-security", "https://w3.org/ns/wot-security"
                    ]
                }
            ]
        },
        "data-context": {
            "oneOf": [{
                    "type": "array",
                    "items": {
                        "anyOf": [{
                                "$ref": "#/definitions/url"
                            },
                            {
                                "type": "object"
                            }
                        ]
                    },
                    "contains": {
                        "type": "string",
                        "enum": [
                            "https://www.w3.org/ns/json-schema", "https://w3.org/ns/json-schema"
                        ]
                    }
                },
                {
                    "type": "string",
                    "enum": [
                        "https://www.w3.org/ns/json-schema", "https://w3.org/ns/json-schema"
                    ]
                }
            ]
        },
        "type_declaration": {
            "oneOf": [{
                    "type": "string"
                },
                {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            ]
        },
        "property_element": {
            "type": "object",
            "properties": {
                "@context": {
                    "$ref": "#/definitions/data-context"
                },
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "description": {
                    "$ref": "#/definitions/description"
                },
                "title": {
                    "$ref": "#/definitions/title"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "uriVariables": {
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "forms": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/form_element_property"
                    }
                },
                "observable": {
                    "type": "boolean"
                },
                "writeOnly": {
                    "type": "boolean"
                },
                "readOnly": {
                    "type": "boolean"
                },
                "oneOf": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "unit": {
                    "type": "string"
                },
                "enum": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true
                },
                "format": {
                    "type": "string"
                },
                "const": {},
                "type": {
                    "type": "string",
                    "enum": [
                        "boolean",
                        "integer",
                        "number",
                        "string",
                        "object",
                        "array",
                        "null"
                    ]
                },
                "items": {
                    "oneOf": [{
                            "$ref": "#/definitions/dataSchema"
                        },
                        {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/dataSchema"
                            }
                        }
                    ]
                },
                "maxItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minimum": {
                    "type": "number"
                },
                "maximum": {
                    "type": "number"
                },
                "properties": {
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "required": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": [
                "forms",
                "observable",
                "writeOnly",
                "readOnly"
            ],
            "additionalProperties": true
        },
        "action_element": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "title": {
                    "type": "string"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "uriVariables": {
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "forms": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/form_element_action"
                    }
                },
                "input": {
                    "$ref": "#/definitions/dataSchema"
                },
                "output": {
                    "$ref": "#/definitions/dataSchema"
                },
                "safe": {
                    "type": "boolean"
                },
                "idempotent": {
                    "type": "boolean"
                }
            },
            "required": [
                "forms", "safe", "idempotent"
            ],
            "additionalProperties": true
        },
        "event_element": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string"
                },
                "title": {
                    "type": "string"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "uriVariables": {
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "forms": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/form_element_event"
                    }
                },
                "subscription": {
                    "$ref": "#/definitions/dataSchema"
                },
                "data": {
                    "$ref": "#/definitions/dataSchema"
                },
                "cancellation": {
                    "$ref": "#/definitions/dataSchema"
                },
                "type": {
                    "not": {}
                },
                "enum": {
                    "not": {}
                },
                "const": {
                    "not": {}
                }
            },
            "required": [
                "forms"
            ],
            "additionalProperties": true
        },
        "form_element_property": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [{
                            "type": "string",
                            "enum": [
                                "readproperty",
                                "writeproperty",
                                "observeproperty",
                                "unobserveproperty"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "readproperty",
                                    "writeproperty",
                                    "observeproperty",
                                    "unobserveproperty"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll",
                        "websub",
                        "sse"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href", "contentType"
            ],
            "additionalProperties": true
        },
        "form_element_action": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [{
                            "type": "string",
                            "enum": [
                                "invokeaction"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "invokeaction"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll",
                        "websub",
                        "sse"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href", "contentType"
            ],
            "additionalProperties": true
        },
        "form_element_event": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [{
                            "type": "string",
                            "enum": [
                                "subscribeevent",
                                "unsubscribeevent"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "subscribeevent",
                                    "unsubscribeevent"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll",
                        "websub",
                        "sse"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href", "contentType"
            ],
            "additionalProperties": true
        },
        "form_element_root": {
            "type": "object",
            "properties": {
                "href": {
                    "$ref": "#/definitions/url"
                },
                "op": {
                    "oneOf": [{
                            "type": "string",
                            "enum": [
                                "readallproperties",
                                "writeallproperties",
                                "readmultipleproperties",
                                "writemultipleproperties"
                            ]
                        },
                        {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "enum": [
                                    "readallproperties",
                                    "writeallproperties",
                                    "readmultipleproperties",
                                    "writemultipleproperties"
                                ]
                            }
                        }
                    ]
                },
                "contentType": {
                    "type": "string"
                },
                "security": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scopes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "subProtocol": {
                    "type": "string",
                    "enum": [
                        "longpoll",
                        "websub",
                        "sse"
                    ]
                },
                "response": {
                    "type": "object",
                    "properties": {
                        "contentType": {
                            "type": "string"
                        }
                    }
                }
            },
            "required": [
                "href", "contentType"
            ],
            "additionalProperties": true
        },
        "description": {
            "type": "string"
        },
        "title": {
            "type": "string"
        },
        "descriptions": {
            "type": "object"
        },
        "titles": {
            "type": "object"
        },
        "dataSchema": {
            "type": "object",
            "properties": {
                "@type": {
                    "$ref": "#/definitions/type_declaration"
                },
                "description": {
                    "$ref": "#/definitions/description"
                },
                "title": {
                    "$ref": "#/definitions/title"
                },
                "descriptions": {
                    "$ref": "#/definitions/descriptions"
                },
                "titles": {
                    "$ref": "#/definitions/titles"
                },
                "writeOnly": {
                    "type": "boolean"
                },
                "readOnly": {
                    "type": "boolean"
                },
                "oneOf": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "unit": {
                    "type": "string"
                },
                "enum": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true
                },
                "format": {
                    "type": "string"
                },
                "const": {},
                "type": {
                    "type": "string",
                    "enum": [
                        "boolean",
                        "integer",
                        "number",
                        "string",
                        "object",
                        "array",
                        "null"
                    ]
                },
                "items": {
                    "oneOf": [{
                            "$ref": "#/definitions/dataSchema"
                        },
                        {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/dataSchema"
                            }
                        }
                    ]
                },
                "maxItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minItems": {
                    "type": "integer",
                    "minimum": 0
                },
                "minimum": {
                    "type": "number"
                },
                "maximum": {
                    "type": "number"
                },
                "properties": {
                    "additionalProperties": {
                        "$ref": "#/definitions/dataSchema"
                    }
                },
                "required": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "link_element": {
            "type": "object",
            "properties": {
                "anchor": {
                    "$ref": "#/definitions/url"
                },
                "href": {
                    "$ref": "#/definitions/url"
                },
                "rel": {
                    "type": "string"
                },
                "type": {
                    "type": "string"
                }
            },
            "required": [
                "href"
            ],
            "additionalProperties": true
        },
        "securityScheme": {
            "oneOf": [{
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "nosec"
                            ]
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "basic"
                            ]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme", "in"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "cert"
                            ]
                        },
                        "identity": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "digest"
                            ]
                        },
                        "qop": {
                            "type": "string",
                            "enum": ["auth", "auth-int"]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme", "qop", "in"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "bearer"
                            ]
                        },
                        "authorization": {
                            "$ref": "#/definitions/url"
                        },
                        "alg": {
                            "type": "string",
                            "enum": ["MD5", "ES256", "ES512-256"]
                        },
                        "format": {
                            "type": "string",
                            "enum": ["jwt", "jwe", "jws"]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme", "in", "alg", "format"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "psk"
                            ]
                        },
                        "identity": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "public"
                            ]
                        },
                        "identity": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "oauth2"
                            ]
                        },
                        "authorization": {
                            "$ref": "#/definitions/url"
                        },
                        "token": {
                            "$ref": "#/definitions/url"
                        },
                        "refresh": {
                            "$ref": "#/definitions/url"
                        },
                        "scopes": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        },
                        "flow": {
                            "type": "string",
                            "enum": ["implicit", "password", "client", "code"]
                        }
                    },
                    "required": [
                        "scheme", "format", "alg", "in"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "apikey"
                            ]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme", "in"
                    ]
                },
                {
                    "type": "object",
                    "properties": {
                        "@context": {
                            "$ref": "#/definitions/security-context"
                        },
                        "@type": {
                            "$ref": "#/definitions/type_declaration"
                        },
                        "description": {
                            "$ref": "#/definitions/description"
                        },
                        "descriptions": {
                            "$ref": "#/definitions/descriptions"
                        },
                        "proxy": {
                            "$ref": "#/definitions/url"
                        },
                        "scheme": {
                            "type": "string",
                            "enum": [
                                "pop"
                            ]
                        },
                        "authorization": {
                            "$ref": "#/definitions/url"
                        },
                        "format": {
                            "type": "string",
                            "enum": ["jwt", "jwe", "jws"]
                        },
                        "alg": {
                            "type": "string",
                            "enum": ["MD5", "ES256", "ES512-256"]
                        },
                        "in": {
                            "type": "string",
                            "enum": ["header", "query", "body", "cookie"]
                        },
                        "name": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "scheme"
                    ]
                }
            ]
        },
        "url": {
            "type": "string",
            "format": "uri-reference"
        }
    }
}

        </pre>  
</section>

  </section>

  <section id="Thing Templates" class="appendix">
    <h1>Thing Templates</h1>
      
    <p>
    A <em>Thing Template</em> is a description for a <em>class</em> of devices or things.
    It describes the properties, actions, events and common metadata that are shared for an entire group of things,
    to enable the common handling of thousands of devices by a cloud server, which is not practical on a per-thing basis.
    The Thing Template uses the same core vocabulary and information model from section 5.
    </p>
    <p>
    The Thing Template enables:
    <ul>
    <li> management of multiple things by a cloud service. </li>
    <li> simulation of devices/things that have not yet been developed.</li>
    <li> common applications across devices from different manufacturers that share a common thing model.</li>
    <li> combining multiple models into a thing.
    </ul>
    </p>
    <p>
    The Thing Template is a logical description of the interface and possible interaction with devices
    (properties, actions and events), however it does not contain device-specific
    information, such as a serial number, GPS location, security information or concrete protocol endpoints.
    </p><p>
    Since a Thing Template does not contain a protocol binding to specific endpoints and 
    does not define a specific security mechanism, the <em>forms</em> and <em>securityDefinitions</em> and 
    <em>security</em> keys must not be present.
    </p><p>
     The same Thing Template can be implemented by things from multiple vendors,
    a thing can implement multiple thing templates, define additional metadata
    (vendor, location, security) and define bindings to concrete protocols.
    To avoid conflicts between properties, actions and events from different thing templates
    that are combined into a common thing, all thse identifiers must be unique within a thing.
    </p><p>
    A common Thing Template for a class of devices enables writing applications across vendors and
    creates a more attractive market for application developers.
    A concrete Thing Description can implement multiple <em>Thing Templates</em> and
    thus can aggregate function blocks into a combined device.
    </p><p>
    The business models of cloud vendors are typically built on managing thousands of identical devices.
    All devices with the same Thing Template can be managed in the same way by cloud applications.
    It is easy to create multiple simulated devices, if the interface and the instance are treated separately.
    </p><p>
        Since a Thing Template is a subset of the Thing Description in which some optional and mandatory vocabulary terms 
        does not exist, however, it can be serialized in the same way and in the same formats as a Thing Description. Note that Thing 
        Template instances cannot be validated in the same way as Thing Description instances due to missing mandatory terms.
    </p>
    
      <section id="thing-template-examples">
     <h2>Thing Template Examples</h2>
    
    This section defines a Thing Template for a lamp and a Thing Template for a a buzzer.
    The combined thing BuzzerLamp includes both thing templates.
    
      <section id="lamp-thing-template">
      <h3>Thing Template: Lamp</h3>
    
    <pre class="example" title="MyLampThingTemplate serialized in JSON">
    {
        "@context": ["http://www.w3.org/ns/td"], 
        "@type" : "ThingTemplate",
        "id": "urn:dev:wot:com:example:servient:lamp:model",
        "name": "Lamp Thing Template",
        "description" : "Lamp Thing Template",
        "properties": {
            "status": {
                "description" : "current status of the lamp (on|off)",
                "type": "string",
                "readOnly": true
            }
        },
        "actions": {
            "toggle": {
                "description" : "Turn the lamp on or off"
            }
        },
        "events": {
            "overheating": {
                "description" : "Lamp reaches a critical temperature (overheating)",
                "data": {"type": "string"}
            }
        }
    }
    </pre>
    </section>
    
    <section id="buzzer-thing-template">
    <h3>Thing Template: Buzzer</h3>
    
    <pre class="example" title="MyLampThingTemplate serialized in JSON">
    {
        "@context": ["http://www.w3.org/ns/td"], 
        "@type" : "ThingTemplate",
        "id": "urn:dev:wot:com:example:servient:buzzer:template",
        "name": "Buzzer Thing Template",
        "description" : "Thing template of a buzzer that makes noise for 10 seconds",
         "actions": {
            "buzz": {
                "description" : "buzz for 10 seconds"
            }
         }
    }
    </pre>
    </section>
    
    <section id="combination-lamp-buzzer-thingl">
    <h3>Combined Thing: Lamp + Buzzer</h3>
    <p>
    The following example illustrates how a combined thing can be defined using two different thing templates.
    </p>
    <pre class="example" title="Combined Thing: Lamp + Buzzer (JSON-LD1.1 serialisation)">
    {
       "@context": ["http://www.w3.org/ns/td",
       		    { "thing-templates": "http://www.w3.org/ns/thing-templates"] }, 
       "@type" : [
            "Thing",
            "urn:dev:wot:com:example:servient:lamp:template",
            "urn:dev:wot:com:example:servient:buzzer:template"
        ],
        "id": "urn:dev:wot:com:example:servient:combinedBuzzerLamp1",
        "name": "My Buzzing Lamp Thing",
        "description" : "A lamp that can issue an alert",
        "securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
        "security": ["nosec_sc"],
        "thing-templates:components": [{
            "id": "urn:dev:wot:com:example:servient:lamp:template",
            "name": "Lamp Thing Template",
            "description" : "Thing Template for a lamp",
            "properties": {
                "status": {
                    "description" : "current status of the lamp (on|off)",
                    "type": "string",
                    "readOnly": true,
                    "forms": [{
                    "href": "coaps://buzzlamp.example.com/status",
                    "contentType": "application/json"
                    }]
                }
            },
            "actions": {
                "toggle": {
                    "description" : "Turn on or off the lamp",
                    "forms": [{
                        "href": "coaps://buzzlamp.example.com/toggle",
                        "contentType": "application/json"
                    }]
                }
            },
            "events": {
                "overheating": {
                    "@type" : "iot:TemperatureAlarm",
                    "description" : "Lamp reaches a critical temperature (overheating)",
                    "data": {"type": "string"},
                    "forms": [{
                        "href": "coaps://buzzlamp.example.com/oh",
                        "contentType": "application/json"
                    }]
                }
            }
        },
        {
            "id": "urn:dev:wot:com:example:servient:buzzer:template",
            "name": "Buzzer Thing Template",
            "description" : "Thing Template of a buzzer that makes noise for 10 seconds",
             "actions": {
                "buzz": {
                    "description" : "buzz for 10 seconds",
                    "forms": [{
                        "href": "coaps://buzzlamp.example.com/buzz",
                        "contentType": "application/json"
                    }]
                }
             }
        }]
    }
      </pre>
      </section>
     </section>   
     </section>  computer keyboard have this Scroll Lock key that seems to serve no purpose whatsoever? In 15 years I don't remember ever pushing that button. I'm almost scared to touch it 
    
  <section id="note-jsonld11-processing" class="algorithm">
        <h2>Transformation to RDF</h2>

        <p>
            To integrate a Thing Description instance with external knowledge and
            contextual information (like iot.schema.org annotations), the use of
            JSON-LD 1.1 and its processing API [[json-ld-api]], as well as RDF-based
            tools [[rdf11-concepts]] and libraries is highly recommended.
        </p>

        <p>
            TD classes and properties have RDF foundations, in the form of a Web
            ontology [[wot-td-ontology]]. On this basis, it is possible to represent
            a JSON TD document in RDF to then be uploaded to an RDF store for further
            analytics. In terms of implementation, the JSON-LD API specifies the procedure
            <a href="https://www.w3.org/TR/json-ld11-api/#deserialize-json-ld-to-rdf-algorithm">
                <code>toRDF</code>
            </a>
            to obtain an RDF representation of the JSON-serialized Thing Description instance.
        </p>

        <p class="ednote">
            To make the transformation reversible, <code>@index</code> must be kept in RDF.
            See Github issue <a href="https://github.com/w3c/json-ld-api/issues/65">w3c/json-ld-api#65</a>.
        </p>
    
        <p class="issue">
            An experimental JSON-LD 1.1 context for the TD model is provided in the
            repository: <code>td-context-1.1.jsonld</code>. Currently, it is not the
            context served at <code>http://www.w3.org/ns/td</code>, though.
        </p>

    </section>

  <section id="changes" class="appendix">
  <h1>Recent Specification Changes</h1>
  <h2 id="changes3">Changes from Third Public Working Draft</h2>
  <ul>
    <li>General</li>
    <ul>
    <li>The form of TD which does not depend on default value assumptions and can be passed directly to a JSON-LD 1.1 processor for semantic processing is now called <i>Full</i> Thing Description. A JSON Schema for validating TD instances in <i>Full</i> form is <a href="#json-schema-4-validation-full">available</a>.</li>
    <li><code>InteractionPattern</code> class was renamed as <a href="#interactionaffordance"><code>InteractionAffordance</code></a>.</li>
    <li>Security and Privacy Considerations section (Section <a href="#sec-security-consideration"></a>) was added.</li>    
    <li><a href="#Thing%20Templates">Thing Templates</a> were introduced for representing a class of devices or things.</li>
    <li>A new <a href="#behavior">section</a> was introduced to describe behavioral constraints of a WoT system.</li>
    <li>A new appendix <a href="#note-jsonld11-processing">section</a> was added to describe how RDF representation of Thing Description can be obtained. At the same time, the Implementation Notes subsection (used to be in Thing Description Serialization section in the previously published draft) was removed. </li>
    </ul>

    <li>Thing</li>
    <ul>
    <li>TD now supports <a href="#meta-interactions-of-thing">meta interactions</a> <code>readallproperties</code>, <code>writeallproperties</code>, <code>readmultipleproperties</code> and <code>writemultipleproperties</code>.</li>
    <li><a href="#thing">Thing</a> class now has optional <code>created</code> and <code>lastModified</code> members to provide information as to when the TD instance was created (in the case of <code>created</code>) or was last modified (in the case of <code>lastModified</code>).</li>
    <li><a href="#thing">Thing</a> class now has an optional <code>version</code> member for providing version information.</li>
    <li>Members <code>@context</code> and <code>@type</code> were added to <a href="#thing">Thing</a> class.</li>
    </ul>
    <li>InteractionAffordance</li>
    <ul>
    <li><a href="#action">Action</a> class now has optional <code>safe</code> and <code>idempotent</code> members to provide information as to the safeness and idempotency of the action.</li>
    <li>Property interactions are now both readable and writable by default. This can be overridden through <code>readOnly</code> and <code>writeOnly</code> member settings available in <a href="#dataschema">DataSchema</a> class.</li>

    <li><a href="#event">Event</a> class now has optional <code>subscription</code> and <code>cancellation</code> 
members that define data that needs to be passed upon subscription and cancellation, respectively.</li>


    <li><a href="#interactionaffordance">InteractionAffordance</a> class's <code>label</code> member was renamed as <code>title</code> to be consistent with JSON Schema.</li>
    <li><a href="#interactionaffordance">InteractionAffordance</a> class now has an optional <code>uriVariables</code> member where URI template variables can be defined.</li>
    <li><code>@type</code> member was added to <a href="#interactionaffordance">InteractionAffordance</a> class.</li>
    <li>Members <code>scopes</code> and <code>security</code> were removed from <a href="#interactionaffordance">InteractionAffordance</a> class.</li>
    </ul>
    <li>Form</li>
    <ul>
    <li><a href="#form">Form</a> class's now contains <code>response</code> member that can be used to describe metadata for response messages.</li>
    <li><a href="#form">Form</a> class's <code>mediaType</code> member was renamed to <code>contentType</code> to reflect that it can assign not only a media type but also its parameter settings.</li>
    <li><a href="#form">Form</a> class's <code>rel</code> member was renamed as <code>op</code>, and <code>unobserveproperty</code> was added as one of the enumerated values. The <code>op</code> member has default values depending on the context in which it is used.</li>
    </ul>
    <li>DataSchema</li>
    <ul>
    <li><a href="#dataschema">DataSchema</a> class now has an optional <code>unit</code> member to provide unit informat    <li><a href="#nullschema">NullSchema</a> class was added.</li>
    <li>Terms "oneOf" and "format" were added in <a href="#dataschema">DataSchema</a> class.</li>
    <li><code>@type</code> member was added to <a href="#dataschema">DataSchema</a> class.</li>
    </ul>
    <li>Security Scheme</li>
    <ul>
    <li>Make it clear that the top-level <a href="#security-serialization-json"><code>security</code></a> declaration is mandatory.</li>
    <li>Add <code>securityDefinitions</code>, update examples using <code>security</code> to use defined names, not SecurityScheme objects.</li>
    <li>Removed all "Url" postfixes in parameter names for security schemes.</li>
    <li><code>@type</code> member was added to <a href="#securityscheme">SecurityScheme</a> class.</li>
    <li><a href="#multilanguage">Multi-language</a> <code>descriptions</code> is allowed in <a href="#securityscheme">SecurityScheme</a>.
    </ul>
    <li>Miscellaneous</li>
    <ul>
    <li><a href="#multilanguage">Multi-language</a> is supported for human-readable text such as <code>descriptions</code> and <code>titles</code>.</li>
    <li><a href="#link">Link</a> class's <code>mediaType</code> member was renamed to <code>type</code>, and the member was given an improved description.</li>
    </ul>
  </ul>

  <h2 id="changes2">Changes from Second Public Working Draft</h2>
  <p>Changes from Second Public Working Draft are described in the 
  <a href="https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/#changes">Third Public Working Draft</a>
  </p>

  </section>

  <section id="acknowledgements" class="appendix normative">
  <h1>Acknowledgements</h1>
  <p>The editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster, Kawaguchi Toru, Michael Lagally, Kazuyuki Ashimura, Ege Korkan, María Poveda, Daniel Peintner, Ben Francis for their contributions, comments, and guidance.</p>
  </section>

</body>
</html>