index.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-Binding-Templates" : {
                  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;
	}

.with-default .with-default-control {
    margin-top: 1em;
    margin-bottom: 1em;
}

.with-default pre.selected {
    margin-top: 0;
    margin-bottom: 1em;
    height: auto;
}

.with-default pre {
    margin-top: 0;
    margin-bottom: 0;
    height: 0;
}
</style>

<script>
    document.addEventListener('DOMContentLoaded', () => {
        // let ReSpec do syntax highlighting first
        document.respecIsReady.then(() => {
            document.querySelectorAll('.with-default').forEach(n => {
                let wo = n.querySelector('pre:nth-of-type(1)');
                let w = n.querySelector('pre:nth-of-type(2)');
                let cbox = n.querySelector('.with-default-control input[type="checkbox"]');

                w.classList.add('selected');
                cbox.checked = true;

                cbox.addEventListener('change', e => {
                    if (e.target.checked) {
                        // with default
                        w.classList.add('selected');
                        wo.classList.remove('selected');
                    } else {
                        // without
                        w.classList.remove('selected');
                        wo.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)
}
#bindings-requirements-scheme {
  background-color: yellow;
}
#bindings-server-accept {
  background-color: yellow;
}
#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-data-schema-objects-arrays {
  background-color: yellow;
}
#td-datetime-type {
  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-http-method {
  background-color: yellow;
}
#td-default-http-method_get {
  background-color: yellow;
}
#td-default-http-method_put {
  background-color: yellow;
}
#td-default-http-method_post {
  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-json-open {
  background-color: yellow;
}
#td-json-open_utf-8 {
  background-color: yellow;
}
#td-json-open_no-byte-order {
  background-color: yellow;
}
#td-json-open_accept-byte-order {
  background-color: yellow;
}
#td-op-for-property-readonly {
  background-color: yellow;
}
#td-op-for-property-writeonly {
  background-color: yellow;
}
#td-processor-serialization {
  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-security-ns {
  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-contentCoding--Form {
  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-token--OAuth2SecurityScheme {
  background-color: yellow;
}
#td-vocab-type--DataSchema {
  background-color: yellow;
}
#td-vocabulary-defaults {
  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 <a href="#thing">Thing</a> itself, a collection of 
  <a href="#interactionaffordance">affordances</a> to interact with the Thing on the 
  basis of WoT's high-level interaction paradigm (involving the classes 
  <a href="#propertyaffordance"><code>PropertyAffordance</code></a>, 
  <a href="#actionaffordance"><code>ActionAffordance</code></a> and 
  <a href="#eventaffordance"><code>EventAffordance</code></a>), 
  <a href="#sec-data-schema-vocabulary-definition">schemas</a> for the information 
  exchanged with the Thing for machine-understandability, 
  and, finally, <a href="#sec-web-linking-vocabulary-definition">Web links</a> to 
  express any formal or informal relation to other Things. 
  </p>
  <p>
  Property affordances (<a href="#propertyaffordance"><code>PropertyAffordance</code></a> class) 
  can be used for sensing and controlling parameters, such as getting the current value or 
  setting an operation state.
  Action affordances (<a href="#actionaffordance"><code>ActionAffordance</code></a> class) model 
  invocation of physical (and hence time-consuming) processes, but can also be used to 
  abstract RPC-like calls of existing platforms. 
  Event affordances (<a href="#eventaffordance"><code>EventAffordance</code></a> class) 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., <code>application/json</code>, <code>application/xml</code>, <code>application/cbor</code>, <code>application/exi</code> 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>
  <a href="#simple-thing-description-sample">Example 1</a> shows a TD instance and
  illustrates the TD model's <a href="#propertyaffordance"><code>PropertyAffordance</code></a>, 
  <a href="#actionaffordance"><code>ActionAffordance</code></a> and 
  <a href="#eventaffordance"><code>EventAffordance</code></a>
  classes by describing a lamp Thing with the name <i>MyLampThing</i>. 
  </p>
<aside class="example" id="simple-thing-description-sample" title="Thing Description Sample">
    <pre>{
    "@context": "https://www.w3.org/2019/td/v1",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "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>
</aside>


  <p>
  From this TD example, 
  we know there exists one <a href="#propertyaffordance">property affordance</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-Binding-Templates]].
  </p>
  <p>
  In a similar manner, an <a href="#actionaffordance">action affordance</a> 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 <a href="#eventaffordance">event affordance</a> 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 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.
        <a href="#thing-description-full-serialization">Example 2</a> extends the TD sample from
        Example 1 by introducing a second defintion in the <code>@context</code> to declare the
        prefix <code>saref</code> as referring to the SAREF vocabulary namespace [[smartM2M]].
        The SAREF vocabulary includes terms to describe lighting devices and other home automation
        devices that one can embed in a TD as semantic labels as values for the <code>@type</code>
        property. In the present example, the Thing is labelled with <code>saref:LightingDevice</code>,
        the <code>status</code> property affordance is labelled with <code>saref:OnOffState</code>
        and the <code>toggle</code> action affordance with <code>saref:ToggleCommand</code>.
  </p>


 <aside class="example" id="thing-description-full-serialization" title="Thing Description with context extension">
              <pre>
    {
        "@context": [
            "https://www.w3.org/2019/td/v1",
            {
                "saref": "https://w3id.org/saref#"
            }
        ],
        "id": "urn:dev:ops:32473-WoTLamp-1234",
        "name": "MyLampThing",
        "@type": "saref:LightingDevice",
        "securityDefinitions": {"basic_sc": {
            "scheme": "basic",
            "in": "header"
        }},
        "security": ["basic_sc"],
        "properties": {
            "status": {
                "@type": "saref:OnOffState",
                "type": "string",
                "forms": [{
                    "href": "https://mylamp.example.com/status"
                }]
            }
        },
        "actions": {
            "toggle": {
                "@type": "saref:ToggleCommand",
                "forms": [{
                    "href": "https://mylamp.example.com/toggle"
                }]
            }
        },
        "events": {
            "overheating": {
                "@type": "saref:NotifyCommand",
                "data": {"type": "string"},
                "forms": [{
                    "href": "https://mylamp.example.com/oh"
                }]
            }
        }
    }</pre>
</aside>

<p>
        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>

  </section>

  <section id="terminology"> 
  <h2>Terminology</h2>
  <p>The 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>

  <p>
      In addition, this document introduces the following definitions:
  </p>

  <dl>
    <dt>
        <dfn id="dfn-inf-model">TD Information Model</dfn>
    </dt>
    <dd>
        Set of constraints and equivalence relations applying to pre-defined vocabularies 
        (i.e., a core vocabulary with extension like JSON Schema, Web Linking and WoT Security),
        thus defining the semantics of these vocabularies. Constraints and
        equivalence relations are typically expressed in terms of class signature,
        property value assignment and property type on arbitrary object-oriented data
        structures.
    </dd>
    <dt>
    <dfn id="dfn-td-processor">TD Processor</dfn>
    </dt>
    <dd>
        A system that can serialize some internal representation of a TD
        in a given format and deserialize it from that format. If two TDs have different
        serializations but are semantically equivalent, a TD processor must be able to
        construct a canonical (i.e., identical) representation when deserializing them.
        For instance, a TD in which default values were omitted is equivalent to a TD that
        would include default values. Moreover, a TD processor must also detect semantically
        inconsistent TDs, for which no representation should exist. A TD processor is
        typically a sub-system of a WoT runtime.
    </dd>
    <dt>
        <dfn id="dfn-td-serialization">TD Serialization</dfn>
        or
        <dfn id="dfn-td-document">TD document</dfn>
    </dt>
    <dd>
        Textual or binary representation of a TD that can be stored and exchanged between
        servients. A TD serialization follows a given format, provided as a content type
        when exchanging it. The reference serialization format for TDs is JSON.
    </dd>
    <dt>
        <dfn id="dfn-vocab">Vocabulary</dfn>
    </dt>
    <dd>
        A collection of vocabulary terms, identified by a namespace IRI.
    </dd>
    <dt>
        <dfn id="dfn-vocab-term">Vocabulary Term</dfn>
    </dt>
    <dd>
        A class name (like <code>Thing</code>), a property name (like
        <code>forms</code>) or a property value (like <code>readproperty</code>).
    </dd>
  </dl>
  </section>

  <section>
  <h1>Namespaces</h1>
  <p>
      The TD information model presented in this document has its foundations in
      RDF, with a mapping to JSON. This mapping is provided as a JSON-LD context
      file, available at the following URI:
  </p>

  <p>
    <code>https://www.w3.org/2019/td/v1</code>
  </p>

  <section>

    <h2>Reference Namespaces</h2>

    <p>
        All terms defined in the context are grouped by vocabulary, mirroring the
        structure of the present document (see
        <a href="#thing-description-json-ld-context"></a> for more details on the
        context). Each vocabulary is assigned a year-based namespace URI, as follows:
    </p>
  
    <table class="def">
    <thead>
        <tr>
            <th>Vocabulary</th>
            <th>Namespace URI</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Core</td>
            <td><code>https://www.w3.org/2019/td#</code></td>
        </tr>
        <tr>
            <td>Data Schema</td>
            <td><code>https://www.w3.org/2019/json-schema#</code></td>
        </tr>
        <tr>
            <td>Security</td>
            <td><code>https://www.w3.org/2019/wot-security#</code></td>
        </tr>
        <tr>
            <td>Web Linking</td>
            <td><code>https://www.w3.org/2019/web-linking#</code></td>
        </tr>
    </tbody>
    </table>
  
    <p>
        Vocabularies are independent from each other. They may be reused and
        extended in other W3C recommendations. For every breaking change in the
        design of a vocabulary, it will be assigned a new year-based namespace URI.
        Note that to maintain the general coherence of the TD information model,
        the JSON-LD context itself is versioned, such that every version has its own URI
        (<code>v1</code>, <code>v1.1</code>, <code>v2</code>, ...).
    </p>

    <p>
        Because a vocabulary under some namespace URI can only undergo non-breaking
        changes, its content can be safely cached or embedded in applications. One 
        advantage of exposing relatively static content under a namespace URI is to
        optimize payload sizes of messages exchanged between constrained devices. It
        also avoids any privacy leakage resulting from devices accessing publicly
        available vocabularies private networks (see also
        <a href="#sec-security-consideration-context"></a>).
    </p>

  </section>
  
  <section class="informative">

    <h2>Alternative Namespaces</h2>

    <p>
        For convenience, generic namespace URIs redirect to the latest year-based
        URI for each vocabulary. They are defined as follows:
    </p>
  
    <table class="def">
    <thead>
        <tr>
            <th>Vocabulary</th>
            <th>Namespace URI</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Core</td>
            <td><code>https://www.w3.org/ns/td#</code></td>
        </tr>
        <tr>
            <td>Data Schema</td>
            <td><code>https://www.w3.org/ns/json-schema#</code></td>
        </tr>
        <tr>
            <td>Security</td>
            <td><code>https://www.w3.org/ns/wot-security#</code></td>
        </tr>
        <tr>
            <td>Web Linking</td>
            <td><code>https://www.w3.org/ns/web-linking#</code></td>
        </tr>
    </tbody>
    </table>
  
    <p>
        Embedding generic namespace URIs in applications is however not encouraged,
        since newer versions of the vocabularies may break functionalities. Their
        usage should be reserved for applications with powerful infrastructures, like
        analytics on large production plants or buildings based on knowledge graphs
        that may include devices referencing different versions of these vocabularies.
    </p>

  </section>

  </section>

  <section id="conformance">
  <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 Appendix 
  <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" class="normative">
    <h1>Information Model</h1>
    <!-- h1>Vocabulary</h1 -->
    <p>This section introduces the TD information model. 
      The TD 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 TD information model is built upon the following, independent vocabularies: 
        <ul>
            <li>
                the <em>core</em> TD vocabulary, which reflects the
                <a href="https://www.w3.org/TR/wot-architecture/#sec-interaction-model">WoT interaction model</a> 
                including property, action and event affordances [[!WOT-ARCHITECTURE]]
            </li>
            <li>
                the <em>Data Schema</em> vocabulary, including (a subset of) the terms defined in 
                JSON Schema [[?JSON-SCHEMA-VALIDATION]]
            </li>
            <li>
                the <em>WoT Security</em> vocabulary, defining security mechanisms 
                and configuration requirements to implement them
            </li>
            <li>
                the <em>Web Linking</em> vocabulary, encoding the main principles of RESTful
                communication using Web links and forms
            </li>
        </ul>
      </p>

      <p>
          Each of these vocabularies is essentially a set of terms that can
          be used to build data structures, interpreted as objects in the
          traditional object-oriented sense. Formally, an object is either denoted
          by a term or a set of property-value pairs such that properties are terms
          and values denote other objects. Terms may also denote classes (or sets)
          of objects.
      </p>

      <p>
          In this context, the TD information model is to be understood as a
          set of constraints and equivalence relations between such data structures
          that specifically denote WoT Things, i.e. physical world objects.
          The constraints of the TD information model are threefolds:
          <ul>
              <li>
                  <em>class signature</em>: for all objects denoted by a set of
                  property-value pairs in the same class, there is a unique set of
                  terms such that all property names for an object are in this set
                  (the signature of the class).
              </li>
              <li>
                  <em>property value assignment</em>: for all objects denoted by
                  a set of property-value pairs in the same class, there is a set
                  of terms such that every term in this set is the property of
                  some property-value pair for each object (mandatory terms).
              </li>
              <li>
                  <em>property type</em>: for all objects denoted by a set of
                  property-value pairs in the same class, if two pairs for two
                  distinct objects have the same property, their respective values
                  must be in the same class (same type).
              </li>
          </ul>
          In turn, the equivalence relations of the TD information model express
          that two distinct data structures denote the same object. In practice,
          equivalences are defined between data structures that omit certain
          property-value pairs, assuming default values, and data structures that
          explicitly include these values.
      </p>

      <p>
          These abstract constraints can be intuitively represented as a UML
          class diagram, in which classes are shown as tables, each row
          giving a property name and a simple type, separated by a colon
          (<code>:</code>). A simple type is a class with no signature.
          Classes are connected with arrows if there is a property type constraint
          between them (associations) or if one denotes a subset of the other
          (inheritance).
      </p>

      <!-- TODO mention cardinalities -->

      <p>
          The diagram shown next represents all constraints on WoT Things included
          in the TD information model. For the sake of readability, the diagram was
          split in four parts, one for each of the four base vocabularies.
      </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>
          Details on the TD information model are given next as tables. First, equivalence relations
          are provided in the form of default values for properties for some class. Second, constraints
          on the vocabularies mentioned above are provided as class definitions where each table
          gives the signature of a class and each row of a table gives some value assignment and
          some type for each property, along with a description.
      </p>

    </section>

      <section id="sec-default-values">
        <h3>Default Values for Vocabulary Terms</h3>

        <p>
            <span class="rfc2119-assertion" id="td-vocabulary-defaults">
              All equivalence relations expressed in Tables in Section <a href="#sec-default-values"></a>
              MUST be followed by a TD processor.
            </span>
        </p>
        
        <p>
            The follow table gives default value assignments when a TD does not
            assign certain property to any value. 
        </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-contentType">
                    <td>
                        <code>contentType</code>
                    </td>
                    <td><code>application/json</code></td>
                    <td></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-safe">
                    <td>
                        <code>safe</code>
                    </td>
                    <td><code>false</code></td>
                    <td></td>
                </tr>
                <tr class="rfc2119-default-assertion" id="td-default-idempotent">
                    <td>
                        <code>idempotent</code>
                    </td>
                    <td><code>false</code></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>

        <h2>Class Definitions</h2>

        <p>
            <span class="rfc2119-assertion" id="td-vocabulary">
                All vocabulary constraints noted in tables in Section <a href="#sec-core-vocabulary-definition"></a>, <a href="#sec-data-schema-vocabulary-definition"></a>, <a href="#sec-security-vocabulary-definition"></a>, and <a href="#sec-zeb-linking-vocabulary-definition"></a> MUST be followed by a TD processor. 
            </span>
        </p>

      <section id="sec-core-vocabulary-definition">
      <h2>Core Vocabulary Definitions</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>An abstraction of a physical or a virtual entity whose metadata and interfaces are described by a WoT Thing Description, whereas a virtual entity is the composition of one or more Things.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-at-context--Thing"><td><code>@context</code></td><td>JSON-LD keyword to define short-hand names called terms that are used throughout a TD document.</td><td>mandatory</td><td>string or array</td></tr><tr class="rfc2119-table-assertion" id="td-vocab-at-type--Thing"><td><code>@type</code></td><td>JSON-LD keyword to label the object with semantic tags (or types).</td><td>optional</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>mandatory</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>mandatory</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>optional</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>optional</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>optional</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>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td></tr>
<tr class="rfc2119-table-assertion" id="td-vocab-modified--Thing"><td><code>modified</code></td><td>Provides information when the TD instance was last modified.</td><td>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</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>optional</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>optional</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>optional</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>optional</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>optional</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>optional</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>Set of one or more form hypermedia controls that describe how the affordance can be activated. 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="#propertyaffordance">property affordances</a> collectively at once.</td><td>optional</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.</td><td>mandatory</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>mandatory</td><td>map of <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>"https://www.w3.org/2019/wot/td/v1"</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, and/or a default language definition as an object.</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>
     <span class="rfc2119-assertion" id="td-context-default-language">
     In the <code>@context</code> array, the optional default language that is 
     used throughout a TD document is defined within an object as a member with 
     a key <code>@language</code> whose value MUST be a string representing a [[!BCP47]] 
     language code.</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 Thing instance.)
</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 <a href="#propertyaffordance">property affordances</a>.
    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 <a href="#propertyaffordance">property affordances</a>.
</p>
</section>
<section><h3><code>InteractionAffordance</code></h3><p>Metadata of a Thing that shows the possible choices to clients, thereby suggesting how clients may interact with the Thing. There are many types of potential affordances, but W3C WoT defines three types of Interaction Affordances: Properties, Actions, and Events.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-at-type--InteractionAffordance"><td><code>@type</code></td><td>JSON-LD keyword to label the object with semantic tags (or types).</td><td>optional</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>optional</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>optional</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>optional</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>optional</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>Set of one or more form hypermedia controls that describe how the affordance can be activated.</td><td>mandatory</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>optional</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="#propertyaffordance"><code>PropertyAffordance</code></a></li>
<li><a href="#eventaffordance"><code>EventAffordance</code></a></li></ul></section>
<section><h3><code>PropertyAffordance</code></h3><p>An Interaction Affordance that exposes state of the Thing. This state can then be retrieved (read) and optionally updated (write). Things can also choose to make Properties observable by pushing the new state after a change.</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</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>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#boolean"><code>boolean</code></a></td></tr></tbody></table>
<p><code>Property</code> 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><h3><code>ActionAffordance</code></h3><p>An Interaction Affordance that allows to invoke a function of the Thing, which manipulates state (e.g., toggling a lamp on or off) or triggers a process on the Thing (e.g., dimm a lamp over time).</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</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>optional</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>optional</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><a href="#sec-default-values">with default</a></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><a href="#sec-default-values">with default</a></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><h3><code>EventAffordance</code></h3><p>An Interaction Affordance that describes an event source, which asynchronously pushes event data to clients (e.g., overheating alerts).</p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</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>optional</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>optional</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>optional</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><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>Assignment</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>mandatory</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 Definitions</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. In 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>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-at-type--DataSchema"><td><code>@type</code></td><td>JSON-LD keyword to label the object with semantic tags (or types)</td><td>optional</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>optional</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>optional</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>optional</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>optional</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>optional</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>optional</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>optional</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>optional</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>optional</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><a href="#sec-default-values">with default</a></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><a href="#sec-default-values">with default</a></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><a href="#sec-default-values">with default</a></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="#objectschema"><code>ObjectSchema</code></a></li>
<li><a href="#booleanschema"><code>BooleanSchema</code></a></li>
<li><a href="#stringschema"><code>StringSchema</code></a></li>
<li><a href="#integerschema"><code>IntegerSchema</code></a></li>
<li><a href="#numberschema"><code>NumberSchema</code></a></li>
<li><a href="#nullschema"><code>NullSchema</code></a></li>
<li><a href="#arrayschema"><code>ArraySchema</code></a></li></ul>
</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>Assignment</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>optional</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>optional</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>optional</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>Assignment</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>optional</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>optional</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>Assignment</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>optional</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>optional</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>Assignment</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>optional</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>optional</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 Definitions</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]]). 
      However while the HTTP security schemes, 
      vocabulary and syntax given in this specification share many similarities 
      with OpenAPI they are not compatible.  
      </p>
    
        <section><h3><code>SecurityScheme</code></h3><p></p><table class="def"><thead><tr><th><a>Vocabulary term</a></th><th>Description</th><th>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-at-type--SecurityScheme"><td><code>@type</code></td><td>JSON-LD keyword to label the object with semantic tags (or types).</td><td>optional</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>mandatory</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (e.g. <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>optional</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>optional</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>optional</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="#nosecurityscheme"><code>NoSecurityScheme</code></a></li>
<li><a href="#apikeysecurityscheme"><code>APIKeySecurityScheme</code></a></li>
<li><a href="#popsecurityscheme"><code>PoPSecurityScheme</code></a></li>
<li><a href="#bearersecurityscheme"><code>BearerSecurityScheme</code></a></li>
<li><a href="#digestsecurityscheme"><code>DigestSecurityScheme</code></a></li>
<li><a href="#publicsecurityscheme"><code>PublicSecurityScheme</code></a></li>
<li><a href="#basicsecurityscheme"><code>BasicSecurityScheme</code></a></li>
<li><a href="#oauth2securityscheme"><code>OAuth2SecurityScheme</code></a></li>
<li><a href="#certsecurityscheme"><code>CertSecurityScheme</code></a></li></ul>
</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>Assignment</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><a href="#sec-default-values">with default</a></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>optional</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>Assignment</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><a href="#sec-default-values">with default</a></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><a href="#sec-default-values">with default</a></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>optional</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>Assignment</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><a href="#sec-default-values">with default</a></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>optional</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>Assignment</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>optional</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><a href="#sec-default-values">with default</a></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><a href="#sec-default-values">with default</a></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><a href="#sec-default-values">with default</a></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>optional</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>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-identity--CertSecurityScheme"><td><code>identity</code></td><td>Identifier validating access by providing information unique to the resource.</td><td>optional</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>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-identity--PSKSecurityScheme"><td><code>identity</code></td><td>Identifier validating access by providing information unique to the resource.</td><td>optional</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>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-identity--PublicSecurityScheme"><td><code>identity</code></td><td>Identifier validating access by providing information unique to the resource.</td><td>optional</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>Assignment</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>optional</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><a href="#sec-default-values">with default</a></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><a href="#sec-default-values">with default</a></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><a href="#sec-default-values">with default</a></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>optional</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>Assignment</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>optional</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>optional</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>optional</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.  The values associated with a form should be chosen from those defined in an OAuth2SecurityScheme active on that form.</td><td>optional</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><a href="#sec-default-values">with default</a></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 Definitions</h2>
      <p>
        The present model provides a representation for (typed) Web links exposed by
        a Thing. The web linking definition reflecting a very common subset of the terms defined in 
        Web Linking [[!RFC8288]]. The defined terms can be used, e.g., to describe the relation to another Thing such 
        as a <i>Lamp Thing</i> is controlled by a <i>Switch Thing</i>.
     </p>

        <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>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-href--Form"><td><code>href</code></td><td>target IRI of a link or submission target of a form.</td><td>mandatory</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><a href="#sec-default-values">with default</a></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-contentCoding--Form"><td><code>contentCoding</code></td><td>Content coding values indicate an encoding transformation that has been or can be applied to a representation. Content codings are primarily used to allow a representation to be compressed or otherwise usefully transformed without losing the identity of its underlying media type and without loss of information. Examples of content coding include "gzip", "deflate", etc. .</td><td>optional</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>optional</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>mandatory</td><td><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>optional</td><td><a href="http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a> (one of <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.</td><td>optional</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.  The values associated with a form should be chosen from those defined in an OAuth2SecurityScheme active on that form.</td><td>optional</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>
<p>The list of possible operation types of a form is fixed. It only includes the
well-known types necessary to implement the WoT interaction model described in
[[WOT-ARCHITECTURE]]. Future versions of the standard may extend this list but
<span class="rfc2119-assertion" id="well-known-operation-types-only">
operations types SHOULD NOT be arbitrarily set by servients
</span>.
</p>

<p>Possible values for the <code>contentCoding</code> property can be found e.g. in
the <a href="https://www.iana.org/assignments/http-parameters/http-parameters.xhtml#content-coding">
IANA HTTP content coding registry</a>.
</p>
</section>
<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>Assignment</th><th>Type</th></tr></thead><tbody><tr class="rfc2119-table-assertion" id="td-vocab-href--Link"><td><code>href</code></td><td>target IRI of a link or submission target of a form.</td><td>mandatory</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>optional</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>optional</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>optional</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><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>Assignment</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><a href="#sec-default-values">with default</a></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>

    </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>
    <span class="rfc2119-assertion" id="td-processor-serialization">
        A TD processor MUST be able to serialize TDs in the JSON format and
        deserialize TDs from that format, according to the rules noted
        in Sections <a href="#td-basic-types-mapping"></a> and
        <a href="#td-class-serialization"></a>.
    </span>
</p>

<p>
  The JSON serialization of TDs follows the syntax of JSON-LD 1.1 [[json-ld11]] in order to streamline semantic evaluation. Hence, TD serializations can be processed either as raw JSON or with a JSON-LD 1.1 processor,
  as later developed in <a href="#note-jsonld11-processing"></a>.
</p>


<p>
In order to support interoperable internationalization,
<span class="rfc2119-assertion" id="td-json-open">TDs MUST be serialized according to the 
requirements defined in Section 8.1 of RFC8259 [[RFC8259]] for open ecosystems.</span>
In summary, this requires the following:
<ul>
<li><span class="rfc2119-assertion" id="td-json-open_utf-8">TDs MUST be encoded using UTF-8 [[RFC3629]].</span</li>
<li><span class="rfc2119-assertion" id="td-json-open_no-byte-order">Implementations MUST NOT 
 add a byte order mark (U+FEFF) to the beginning of a networked-transmitted TD.</span></li>
<li><span class="rfc2119-assertion" id="td-json-open_accept-byte-order">Implementations that parse TDs MAY ignore
 the presence of a byte order mark rather than treating it as an error.</span></li>
</ul>
</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>

  <section id="td-basic-types-mapping">
      <h2>Mapping to JSON Types</h2>

  <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-datetime-type">
        Vocabulary terms that use simple type dateTime
        MUST be serialized as JSON string and have the lexical
        form <code><i>YYYY</i>-<i>MM</i>-<i>DD</i>T<i>hh</i>:<i>mm</i>:<i>ss</i>Z</code>,
        where <code><i>YYYY</i></code>, <code><i>MM</i></code> and <code><i>DD</i></code>
        respectively encode a year, a month and a day (i.e. a date) and where
        <code><i>hh</i></code>, <code><i>mm</i></code> and <code><i>ss</i></code>
        respectively encode hours, minutes and seconds (i.e. a time).
  </span> Other elements of the lexical form (<code>-</code>, <code>T</code>, <code>Z</code>)
  are verbatim. In particular, <code>Z</code> is mandatory and must be interpreted
  as the UTC+00 time zone. This lexical form represents a subset of the
  <a href="https://www.w3.org/TR/xmlschema11-2/#dateTime-lexical-mapping">
    XSD built-in dateTime datatype
  </a>, itself inspired by the ISO standard for dates and times [[ISO8601]].</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>
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 Section <a href="#td-class-serialization"></a>.
</p>

  </section>

  
<section id="omitting-default-values">
        <h2>Omitting Default Values</h2>

<p>
                A Thing Description instance serialization may omit one ore more vocabulary 
                terms (<a href="#sec-core-vocabulary-definition"></a>) that have default values assumed based on 
                the table in <a href="#sec-default-values"></a>.
      </p>

      <p>
          The following example shows the TD instance from <a href="#simple-thing-description-sample">Example 1</a>  with a checkbox to make the TD terms with the default values explicit present (=checkbox checked). 
          Alternatively, those terms can be omitted (=checkbox unchecked) to simplify the TD representation. 
          Note that a Thing Description processor interprets these omitted terms identically as if these terms were explicitly present with the default values.
        </p>
    
    <aside class="example with-default">
        <div class="with-default-control">
            <input type="checkbox"/>
            <span><i>with default values</i></span>
        </div>
        <pre>{
    "@context": "https://www.w3.org/2019/td/v1",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "name": "MyLampThing",
    "securityDefinitions": {
        "basic_sc": {
            "scheme": "basic"
        }
    },
    "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>{
    "@context": "https://www.w3.org/2019/td/v1",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "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": {
            "safe": false,
            "idempotent": 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>
    </aside>

    <p>
    Please note that, depending on the underlying protocol binding, additional protocol-specific terms 
    can be used that are associated with 
    default value assumptions and can be omitted similar as explained in this subsection. 
    Further information can be found in the section <a href="#protocol-bindings"></a>.
    </p>
    </section>

  </section> <!-- end of section "Basic assumptions" -->

<section id="td-class-serialization">
    <h2>Information Model Serialization</h2>

  <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 MUST include the
  <code>@context</code> name known from JSON-LD [[json-ld11]] with the value URI of 
  the Thing description context file <code>https://www.w3.org/2019/td/v1</code>.
  </span></p>

<pre class="example">
{  
    "@context": "https://www.w3.org/2019/td/v1",
    ...
}
</pre>

  <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": ["https://www.w3.org/2019/td/v1",
                {"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>

  <pre class="example">
{
    "@context": "https://www.w3.org/2019/wot/td/v1",
    "id": "urn:dev:ops:32473-Thing-1234",
    "name": "MyThing",
    "description": "Human readable information.",
    "descriptions": {...},
    "support": "mailto:support@example.com",
    "securityDefinitions": {...},
    "security": [...],
    "base": "https://servient.example.com/",
    "modified" : "2019-06-01T09:12:43.124Z",
    "created" : "2018-11-14T19:10:23.824Z",
    "version" : {...},
    "properties": {...},
    "actions": {...},
    "events": {...},
    "links": [...],
    "forms": [...]
}
  </pre>

  <!-- 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>

 </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="#propertyaffordance" class="sec-ref"><code>PropertyAffordance</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" id="property-serialization-sample" title="Sample of a property interaction serialization">
        <pre>{
        ...
        "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>
    </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="#actionaffordance" class="sec-ref"><code>ActionAffordance</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" id="action-serialization-sample" title="Sample of an action interaction serialization">
        <pre>{
    ...
    "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>
</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="#eventaffordance" class="sec-ref"><code>EventAffordance</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" id="event-serialization-sample" title="Sample of a event interaction serialization">
        <pre>{
        ...
        "events": {
            "overheated": {
                "data" : {
                    "type": "object"
                },
                "forms": [...]
            }
            ...
        }
        ...
</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-Binding-Templates]].
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="#protocol-bindings"></a>.
  </p>


  <p>A TD snippet based on the defined members is given below:</p>
<pre class="example">
{
  "@context": "https://www.w3.org/2019/td/v1",
    ...
  "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": ["https://www.w3.org/2019/td/v1",
            {"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:methodName": "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": "https://www.w3.org/2019/td/v1",
    ...
    "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, the operation types "readallproperties" and "writeallproperties" are for meta 
    interactions with the Thing by which Consumers can read and write all properties at once. In the example below, 
    <code>forms</code> is used at the top level, and the Consumer can use the submission target  
    <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": "https://www.w3.org/2019/td/v1",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    ...
    "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:ops:32473-Thing-1234",
    "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",
            ...
            "flow": "implicit",
            "authorization": "https://example.com/authorization",
            "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": ["https://www.w3.org/2019/td/v1",
                    {"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> 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><span class="rfc2119-assertion" id="td-data-schema-objects-arrays">
                    The type of the members <code>items</code> MUST be serialized as a JSON object or 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": ["https://www.w3.org/2019/td/v1",
                {"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>title(s)</code> and <code>description(s)</code></h2>

            <p>The vocabulary terms <code>title</code> and <code>description</code> are 
               used to provide human-readable texts for titles (e.g., a display 
               text for UI) and additional information useful for Consumers of TDs. 
               When an optional default language <code>@language</code> is specified 
               in the <code>@context</code> of a <a href="#thing">Thing instance</a>, 
               that default language is associated with the strings provided in the 
               value of <code>title</code> and <code>description</code>.</p>

            <p>A TD snippet using <code>title</code> and <code>description</code> is 
               shown below. Note that there is a default language specified 
               with a <code>@language</code> term member of value <code>"en"</code> 
               within <code>@context</code>. This default language is associated 
               with the string values of <code>description</code>, 
               <code>title</code> (as well as <code>name</code>).</p>

        <pre class="example">
            {
                "@context": [
                    "https://www.w3.org/2019/wot/td/v1",
                    {
                        "@language" : "en"
                    }
                ]
                "name": "MyThing",
                "description": "Human readable information.",
                ...
                "properties": {
                    "on": {
                        "title" : "On/Off",
                        "type": "boolean",
                        "forms": [...]
                    },
                    "status": {
                        "title" : "Status",
                        "type": "object",
                        ...
            }
        </pre>

            <p>On the other hand, 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>

 <section>

    <h4>Semantic Tagging</h4>

 <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": [
                "https://www.w3.org/2019/td/v1",
                {
                "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>

    </section>

    <section>

        <h4>Adding Protocol Bindings</h4>

    <p>
    With the context extension in the Thing Description, communication metadata can be supplemented or specified in the 
    declarations <code>forms</code> (also see <a href="#protocol-bindings"></a>). 
   </p>
    
    <p>The following TD example uses the CoAP protocol binding based on [[!WoT-Binding-Templates]] 
        and assumes that there is a CoAP RDF vocabulary set definition which is accessable 
        via the namespace <code>http://www.example.org/coap-binding#</code>. 
        The supplemented <code>cov:methodCode</code> guides the Consumer which CoAP method has to be applied, e.g., 
        methodCode=1 corresponds to a CoAP GET to read the brightness value or methodCode=2 corresponds to a CoAP POST to write/change the brightness value.
    </p>

    <aside class="example" id="context-extension-for-forms" title="Specialization of the form definition by context extension.">
<pre>{
        "@context": [
            "https://www.w3.org/2019/td/v1",
            {
                "cov": "http://www.example.org/coap-binding#"
            }
        ],
        ...
        "properties": {
            "brightness": {
                "description": "The current brightness setting",
                "type": "integer",
                "minimum": -64,
                "maximum": 64,
                    "forms": [
                    {
                        "href": "coap://example.org:9191/api/brightness",
                        "op": ["readproperty"],
                        "cov:methodCode": 1
                    },
                    {
                        "href": "coap://example.org:9191/api/brightness",
                        "op": ["writeproperty"],
                        "cov:methodCode": 2
                    }
                ]
            }
        }
    }</pre>
        </aside>

    </section>

    <section>

        <h4>Adding Security Schemes</h4>

        <p>Finally,
        new security schemes can be defined using the vocabulary extension
        mechanism.
      <!--
        <span class="rfc2119-assertion" id="td-security-ns">
        All security schemes defined in this document MAY
        also be used via extension vocabularies, using namespace
        URLs defined for them of the form 
        <code>http://www.w3.org/ns/td/sec/</code><em>scheme</em> where <em>scheme</em>
        is replaced by the scheme name.</span>
      -->
        For this example, we will use
        OAuth2 via the extension mechanism.  
        Note that vocabulary outside
        <code>SecurityScheme</code> objects, in this case <code>wotsec:scope</code>,
        can also be included as part of the definition.
        To use the extension mechanism an <code>@context</code> also needs to be 
        defined, including the default for TDs as well as a definition of
        the vocabulary and prefix to be used for the security scheme.
        </p>
      <pre class="example">
      {
          @context: ["https://www.w3.org/2019/td/v1",
                     {"wotsec:": "https://www.w3.org/2019/wot-security#"}],
          ...
          "securityDefinitions": {
              "oauth2_sc": {
                  "scheme": "wotsec:OAuth2SecurityScheme",
                  ...
                  "wotsec:flow": "implicit",
                  "wotsec:authorization": "https://example.com/authorization",
                  "wotsec:scopes": ["limited","special"]
              }
          },
          "security": ["oauth2_sc"],
          "properties": {
              "status": {
                  ...
                  "forms": [
                      {
                          "href": "https://scopes.example.com/status",
                          "contentType": "application/json",
                          "wotsec:scopes": ["limited"]
                      }
                  ]
              }
          },
          "action": {
              "configure": {
                  ...
                  "forms": [
                      {
                          "href": "https://scopes.example.com/configure",
                          "contentType": "application/json",
                          "wotsec:scopes": ["special"]
                      }
                  ]
              }
          },
          ...
      }
      </pre>

        <p>
            For convenience, the W3C vocabulary giving security schemes itself
            includes non-standards but widely used schemes like API key, public
            key, proof-of-possession (PoP), certificates, pre-shared key (PSK)
            or OAuth 2, as in the above example. For any other security scheme,
            a dedicated vocabulary must be designed and referenced by TDs.
        </p>

    </section>

 </section>

  <section>
  <h1>Identification</h1>

  <p>
  The JSON-based serialization of the TD is identified by 
  the media type <code>application/td+json</code> or the
  CoAP Content-Format ID <code>T.B.D.</code> (see <a href="#iana-section"></a>).
  </p>

  <p class="ednote" title="CoAP Content-Format">
  CoAP-based WoT implementations can use the experimental Content-Format
  <code>65100</code> until the final Content-Format ID has been assigned.
  </p>

  </section>

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

<section id="behavior">
<h2>Behavioral Assertions</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 may in particular 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 Configurations</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 Schemas</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, Consumers should
follow the data schemas strictly, not generating anything not given
in the WoT Thing Description, but should accept additional data from
the Thing not given explicitly in the WoT Thing Decription.  In general, Things are <em>described</em> by WoT Thing Descriptions,
but Consumers are <em>constrained</em> to follow WoT Thing Descriptions when
interacting with Things.
<ul>
<li>
<span class="rfc2119-assertion" 
      id="client-data-schema">
A WoT Thing acting as a Consumer 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 MUST accurately describe the 
data returned and accepted by each interaction.
</span>
</li>
<li>
<span class="rfc2119-assertion" 
      id="server-data-schema-extras">
A Thing MAY return additional data from an interaction  
even when such data is 
not described in the data schemas given in its WoT Thing Description.
</span>
</li>
<li>
<span class="rfc2119-assertion" 
      id="client-data-schema-accept-extras">
A WoT Thing acting as a Consumer 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 Consumer 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 Consumer when interacting with another Thing MUST generate URIs 
according to the URI templates, base URIs, 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 URIs, and href members 
in a WoT Thing Description MUST accurately describe the WoT Interace of the Thing.
</span>
</li>
</ul>
</p>
</section> <!-- end of id="behavior-data"-->

<section>
  <h3>Protocol Bindings</h3>

  <p>A Protocol Binding is the mapping from an Interaction Affordance to concrete messages of a 
      specific protocol such as HTTP [[!RFC7231]], CoAP [[!RFC7252]], or MQTT [[!MQTT]]. Protocol Bindings of 
      Interaction Affordances are serialized as <code>forms</code> as defined in <a href="#form-serialization-json"></a>.
    </p>

  <p>
    Every form in a WoT Thing Description must have a submission target,
    given by the <code>href</code> member. The URI scheme of this
    submission target indicates what Protocol Binding the Thing implements
    [[WoT-Architecture]].
    For instance, if the target starts with <code>http</code> or
    <code>https</code>, a Consumer can then infer the Thing implements the
    HTTP binding and it should expect HTTP-specific terms in the
    form instance (see next section, <a href="#http-binding-assertions"></a>).
    <ul>
        <li>
            <span class="rfc2119-assertion" id="bindings-requirements-scheme">
                Every form in a WoT Thing Description MUST follow the requirements
                of the Protocol Binding indicated by the URI scheme of its
                <code>href</code> member.
            </span>
        </li>
        <li>
            <span class="rfc2119-assertion" id="bindings-server-accept">
                Every form in a WoT Thing Description MUST accurately describe requests
                (including request headers, if present) accepted by the Thing in an
                interaction.
            </span>
        </li>
    </ul>
  </p>

  <section id="http-binding-assertions">
    <h4>HTTP Protocol Binding</h4>

    <p>
        Per default the Thing Description supports the HTTP protocol binding and 
        includes the HTTP RDF vocabulary set definitions from [[HTTP-in-RDF10]] and can be 
        directly used within TD instances by the usage of the prefix <code>htv</code>, which 
        points to <code>http://www.w3.org/2011/http#</code>. 
    </p>
    <p>
        To interact with a Thing that implements the HTTP Protocol Binding, a Consumer
        needs to know what HTTP method to use when submitting a form. In the general case,
        a Thing Description can explicitly include a term indicating the method, i.e.,
        <code>htv:methodName</code>. For the
        sake of conciseness, the HTTP Protocol Binding defines default values for each operation type, 
        which also aims at convergence of the methods expected by Things (e.g., GET to read, PUT to write).
        <span class="rfc2119-assertion" id="td-default-http-method">
            When no method is indicated in a form representing an HTTP
            Protocol Binding, a default value 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-http-method_get">
                <td>
                    <code>htv:methodName</code>
                </td>
                <td><code>GET</code></td>
                <td>
                    <code>Form</code> with operation type <code>readproperty</code>
                </td>
            </tr>
            <tr class="rfc2119-default-assertion" id="td-default-http-method_put">
                <td>
                    <code>htv:methodName</code>
                </td>
                <td><code>PUT</code></td>
                <td>
                    <code>Form</code> with operation type <code>writeproperty</code>
                </td>
            </tr>
            <tr class="rfc2119-default-assertion" id="td-default-http-method_post">
                <td>
                    <code>htv:methodName</code>
                </td>
                <td><code>POST</code></td>
                <td>
                    <code>Form</code> with operation type <code>invokeaction</code>
                </td>
            </tr>
        </tbody>
    </table>

    <p>
        For example, the following default values should be assumed for forms in the introductory TD example:
    </p>

    <aside class="example with-default">
            <div class="with-default-control">
                <input type="checkbox">
                <span><i>with default HTTP binding values</i></span>
            </div>
            <pre>{
    "@context": "https://www.w3.org/2019/td/v1",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "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>{
    "@context": "https://www.w3.org/2019/td/v1",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "name": "MyLampThing",
    "securityDefinitions": {
        "basic_sc": {
            "scheme": "basic",
            "in": "header"
        }
    },
    "security": [
        "basic_sc"
    ],
    "properties": {
        "status": {
            "type": "string",
            "forms": [
                {
                    "href": "https://mylamp.example.com/status",
                    "op": "readproperty",
                    "htv:methodName": "GET"
                },
                {
                    "href": "https://mylamp.example.com/status",
                    "op": "writeproperty",
                    "htv:methodName": "PUT"
                }
            ]
        }
    },
    "actions": {
        "toggle": {
            "forms": [
                {
                    "href": "https://mylamp.example.com/toggle",
                    "op": "invokeaction",
                    "htv:methodName": "POST"
                }
            ]
        }
    },
    "events": {
        "overheating": {
            "data": {
                "type": "string"
            },
            "forms": [
                {
                    "href": "https://mylamp.example.com/oh",
                    "subprotocol": "longpoll"
                }
            ]
        }
    }
}</pre>
    </aside>
  </section>

  <section>
      <h4>Other Protocol Bindings</h4>

      <p>

          The number of WoT Protocol Bindings a WoT Thing can implement
          is not restricted. Other bindings, e.g. for CoAP, MQTT or OPC UA
          will be standardized in separate documents such as a protocol vocabulary similar to HTTP in RDF [[HTTP-in-RDF10]]
          or specifications including default value definitions. Such protocols can be simply integrated into the TD by the 
          usage of the context extension mechanism (<a href="#content-extension-section"></a>). A general guideline for Protocol Bindings is given in
          [[WoT-Binding-Templates]].
      </p>
  </section>
</section>

</section> <!-- end of id="behavior"-->


  <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 Consumer 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="iana-section" class="normative">
  <h1>IANA Considerations</h1>
    <section id="media-type-section">
    <h2><code>application/td+json</code> Media Type Registration</h2>
    <dl>
      <dt>Type name:</dt>
      <dd>application</dd>
      <dt>Subtype name:</dt>
      <dd>td+json</dd>
      <dt>Required parameters:</dt>
      <dd>None</dd>
      <dt>Optional parameters:</dt>
      <dd>None</dd>
      <dt>Encoding considerations:</dt>
      <dd>See <a href="https://tools.ietf.org/html/rfc6839#section-3.1">RFC&nbsp;6839, section 3.1</a>.</dd>
      <dt>Security considerations:</dt>
      <dd>See <a href="https://tools.ietf.org/html/rfc8259">RFC&nbsp;8259</a>.
        <p>
          <span class="rfc2119-assertion" id="iana-security-execution">
            Since WoT Thing Description is intended to be a pure data exchange format for
            Thing metadata, the serialization SHOULD NOT be passed through a
            code execution mechanism such as JavaScript's <code>eval()</code>
            function to be parsed.
          </span>
          An (invalid) document may contain code that,
          when executed, could lead to unexpected side effects compromising
          the security of a system.
        </p>
        <p>
          WoT Thing Descriptions can be evaluated with a JSON-LD 1.1 processor,
          which typically follows links to remote contexts (i.e., TD context
          extensions, see <a href="#content-extension-section"></a>)
          automatically, resulting in the transfer of files
          without the explicit request of the Consumer for each one. If remote
          contexts are served by third parties, it may allow them to gather
          usage patterns or similar information leading to privacy concerns.
          <span class="rfc2119-assertion" id="iana-security-remote">
          While implementations on resource-constrained devices are expected
          to perform raw JSON processing (as opposed to JSON-LD processing),
          implementations in general SHOULD statically cache vetted
          versions of their supported context extensions and not to follow links
          to remote contexts.
          </span>
          Supported context extensions can be managed
          through a secure software update mechanism instead.
        </p>
        <p>
          Context Extensions (see <a href="#content-extension-section"></a>)
          that are loaded from the Web over non-secure connections,
          such as HTTP, run the risk of being altered by an attacker such that
          they may modify the TD Information Model in a way that could
          compromise security.
          <span class="rfc2119-assertion" id="iana-security-alter">
          For this reason, Consumer again
          SHOULD vet and cache remote contexts before allowing the system
          to use it.
          </span>
        </p>
        <p>
          Given that JSON-LD processing usually includes the substitution of
          long IRIs with short terms,
          WoT Thing Descriptions may expand considerably when processed using
          a JSON-LD 1.1 processor and, in the worst case, the resulting data
          might consume all of the recipient's resources.
          <span class="rfc2119-assertion" id="iana-security-expansion">
          Consumers SHOULD treat any TD metadata with due skepticism.
          </span>
        </p>
      </dd>
      <dt>Interoperability considerations:</dt>
      <dd>See <a href="https://tools.ietf.org/html/rfc8259">RFC&nbsp;8259</a>.
        <p>
        Rules for processing both conforming and non-conforming content are
        defined in this specification.
        </p>
      </dd>
      <dt>Published specification:</dt>
      <dd><a href="https://w3c.github.io/wot-thing-description">https://w3c.github.io/wot-thing-description</a></dd>
      <dt>Applications that use this media type:</dt>
      <dd>
        All participating entities in the W3C Web of Things, that is,
        Things, Consumers, and Intermediaries as defined in the
        <a href="https://w3c.github.io/wot-architecture">Web of Things (WoT) Architecture</a>.</dd>
      <dt>Fragment identifier considerations:</dt>
      <dd>See <a href="https://tools.ietf.org/html/rfc6839#section-3.1">RFC&nbsp;6839, section 3.1</a>.</dd>
      <dt>Additional information:</dt>
      <dd>
        <dl>
          <dt>Magic number(s):</dt>
          <dd>Not Applicable</dd>
          <dt>File extension(s):</dt>
          <dd>.jsontd</dd>
          <dt>Macintosh file type code(s):</dt>
          <dd>TEXT</dd>
        </dl>
      </dd>
      <dt>Person &amp; email address to contact for further information:</dt>
      <dd>Matthias Kovatsch &lt;w3c@kovatsch.net&gt;</dd>
      <dt>Intended usage:</dt>
      <dd>COMMON</dd>
      <dt>Restrictions on usage:</dt>
      <dd>None</dd>
      <dt>Author(s):</dt>
      <dd>The WoT Thing Description specification is a product of the Web of Things Working Group.</dd>
      <dt>Change controller:</dt>
      <dd><abbr title="World Wide Web Consortium">W3C</abbr></dd>
    </dl>

    </section>
    <section id="content-format-section">
    <h2>CoAP Content-Format Registration</h2>
    <p>
      IANA assigns compact CoAP Content-Format IDs for media types in the
      <a href="https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats">CoAP Content-Formats</a>
      subregistry within the
      <a href="https://www.iana.org/assignments/core-parameters/core-parameters.xhtml">Constrained RESTful Environments (CoRE) Parameters</a>
      registry [[RFC7252]].
      The Content-Format ID for WoT Thing Description is (t.b.d.) in the 256-9999 range (IETF Review or IESG Approval).
    </p>
    <dl>
      <dt>Media Type:</dt>
      <dd>application/td+json</dd>
      <dt>Encoding:</dt>
      <dd>-</dd>
      <dt>ID:</dt>
      <dd>T.B.D.</dd>
      <dt>Reference:</dt>
      <dd>[<a href="https://w3c.github.io/wot-thing-description">"Web of Things (WoT) Thing Description", May 2019</a>]</dd>
    </section>
  </section>

  <section id="example-serialization" class="appendix 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: Also see Section <a href="#adding-protocol-bindings">Adding Protocol Bindings</a>. </li>
  
    </ul>
  
  <pre class="example" title="MyLampThing represented as a compact JSON serialization">
  {
     "@context": [
        "https://www.w3.org/2019/td/v1",
        {
        "cov": "http://www.example.org/coap-binding#"
        }
      ],
      "id": "urn:dev:ops:32473-WoTLamp-1234",
      "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",
                  "cov:methodName" : "GET" 
              }]
          }
      },
      "actions": {
          "toggle": {
              "description" : "Turn on or off the lamp",
              "forms": [{
                  "href": "coaps://mylamp.example.com/toggle",
                  "cov:methodName" : "POST" 
              }]
          }
      },
      "events": {
          "overheating": {
              "description" : "Lamp reaches a critical temperature (overheating)",
              "data": {"type": "string"},
              "forms": [{
                  "href": "coaps://mylamp.example.com/oh",
                  "cov:methodName" : "GET",
                  "subprotocol" : "cov:observe" 
              }]
          }
      }
  }
  </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">
          {   
              "@context": "https://www.w3.org/2019/td/v1",
              "name": "MyLightSensor",
              "id": "urn:dev:ops:32473-WoTLightSensor-1234",
              "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 callback URI the temperature value (defined within the <code>data</code> container) 
              has to be sent. To subscibe a Consumer must submit a POST request to http://192.168.0.124:8080/events/TempForT2T/subscribe and 
              provide the callback URI in the payload as JSON object with the member <code>targetURL</code>.  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": "https://www.w3.org/2019/td/v1",
              "id": "urn:dev:ops:32473-Thing-1234",
              "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="json-schema-for-validation" class="appendix informative">
  <h1>JSON Schema for TD Instance Validation</h1>
    <p>
        Below is a JSON Schema [[?JSON-SCHEMA-VALIDATION]] document 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">Information Model</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>

    <p>
        The following JSON Schema for validating TD instances does not require the terms with default values to be present. Thus the terms with default values are optional. (see also <a href="#sec-default-values"></a>)

    <pre class="advisement">
    {
    "title": "WoT TD Schema - 29 March 2019",
    "description": "JSON Schema for validating TD instances against the TD model. TD instances can be with or without terms that have default values",
    "$schema ": "http://json-schema.org/draft-06/schema#",
    "definitions": {
        "thing-context": {
            "oneOf": [{
                    "type": "array",
                    "items": {
                        "anyOf": [{
                                "$ref": "#/definitions/url"
                            },
                            {
                                "type": "object"
                            }
                        ]
                    },
                    "contains": {
                        "type": "string",
                        "pattern": "^https?://(www\\.)?w3\\.org/2019/td/v1$"
                    }
                },
                {
                    "type": "string",
                    "pattern": "^https?://(www\\.)?w3\\.org/2019/td/v1$"
                }
            ]
        },
        "type_declaration": {
            "oneOf": [{
                    "type": "string"
                },
                {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            ]
        },
        "property_element": {
            "type": "object",
            "properties": {
                "@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": {
                        "@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": {
                        "@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": {
                        "@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": {
                        "@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": {
                        "@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": {
                        "@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": {
                        "@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": {
                        "@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": {
                        "@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": {
                        "@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"
        }
    },
    "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"
        },
        "modified": {
            "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
}
    </pre>

  </section>

  <section id="Thing Templates" class="appendix informative">
    <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 submission targets 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 some missing mandatory terms.
    </p>
    
      <section id="thing-template-examples">
     <h2>Thing Template Examples</h2>
    
    This section shows a Thing Template for a lamp and a Thing Template for a buzzer.
    
      <section id="lamp-thing-template">
      <h3>Thing Template: Lamp</h3>
    
    <pre class="example" title="MyLampThingTemplate serialized in JSON">
    {
        "@context": ["https://www.w3.org/2019/td/v1"], 
        "@type" : "ThingTemplate",
        "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="MyBuzzerThingTemplate serialized in JSON">
    {
        "@context": ["https://www.w3.org/2019/td/v1"], 
        "@type" : "ThingTemplate",
        "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>   
     </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="appendix informative">
        <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-ld11-api]], as well as RDF-based
            tools [[rdf11-concepts]] and libraries is highly recommended. This appendix
            introduces two non-normative elements of the Thing Description model that
            allow for a transformation to RDF: the default JSON-LD context for TD and
            the TD ontology.
        </p>

        <section>
            <h3>Thing Description JSON-LD Context</h3>

            <p>
                A JSON TD document can be transformed in RDF (to then be uploaded
                to an RDF store for further analytics) by a standard JSON-LD processor.
                The following procedure loads the context of the TD, given by the
                term <code>@context</code>, and generates RDF triples:
            </p>

            <p>
                <a href="https://www.w3.org/TR/json-ld11-api/#deserialize-json-ld-to-rdf-algorithm">
                    <code>JsonLdProcessor.toRdf</code>
                </a>
            </p>
            
            <p>
                When applying this procedure to the introductory TD example with all default values,
                the following triples are obtained:
            </p>
            
            <aside class="example with-default" id="simple-thing-description-rdf">
                <div class="with-default-control">
                    <input type="checkbox"/>
                    <span><i>after transformation to RDF</i></span>
                </div>
                <pre>{
    "@context": "https://www.w3.org/2019/td/v1",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "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",
                    "htv:methodName": "GET"
                },
                {
                    "href": "https://mylamp.example.com/status",
                    "contentType": "application/json",
                    "op": "writeproperty",
                    "htv:methodName": "PUT"
                }
            ]
        }
    },
    "actions": {
        "toggle": {
            "safe": false,
            "idempotent": false,
            "forms": [
                {
                    "href": "https://mylamp.example.com/toggle",
                    "contentType": "application/json",
                    "op": "invokeaction",
                    "htv:methodName": "POST"
                }
            ]
        }
    },
    "events": {
        "overheating": {
            "data": {
                "type": "string"
            },
            "forms": [
                {
                    "href": "https://mylamp.example.com/oh",
                    "contentType": "application/json",
                    "subprotocol": "longpoll",
                    "op": "subscribeevent"
                }
            ]
        }
    }
}</pre><pre>
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;https://www.w3.org/2019/td#name&gt; &quot;MyLampThing&quot; .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;https://www.w3.org/2019/td#security&gt; &lt;_:b8&gt; .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;https://www.w3.org/2019/td#properties&gt; _:b5 .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;https://www.w3.org/2019/td#actions&gt; _:b0 .
&lt;urn:dev:wot:com:example:servient:lamp&gt; &lt;https://www.w3.org/2019/td#events&gt; _:b2 .
_:b0 &lt;https://www.w3.org/2019/td#name&gt; &quot;toggle&quot; .
_:b0 &lt;https://www.w3.org/2019/td#forms&gt; _:b1 .
_:b0 &lt;https://www.w3.org/2019/td#idempotent&gt; &quot;false&quot;^^&lt;http://www.w3.org/2001/XMLSchema#boolean&gt; .
_:b0 &lt;https://www.w3.org/2019/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;https://www.w3.org/2019/td#contentType&gt; &quot;application/json&quot; .
_:b1 &lt;https://www.w3.org/2019/td#href&gt; &quot;https://mylamp.example.com/toggle&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b1 &lt;https://www.w3.org/2019/td#op&gt; &quot;invokeaction&quot; .
_:b2 &lt;https://www.w3.org/2019/td#name&gt; &quot;overheating&quot; .
_:b2 &lt;https://www.w3.org/2019/td#data&gt; _:b3 .
_:b2 &lt;https://www.w3.org/2019/td#forms&gt; _:b4 .
_:b3 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;https://www.w3.org/2019/json-schema#StringSchema&gt; .
_:b4 &lt;https://www.w3.org/2019/td#contentType&gt; &quot;application/json&quot; .
_:b4 &lt;https://www.w3.org/2019/td#href&gt; &quot;https://mylamp.example.com/oh&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b4 &lt;https://www.w3.org/2019/td#op&gt; &quot;subscribeevent&quot; .
_:b4 &lt;https://www.w3.org/2019/td#subprotocol&gt; &quot;longpoll&quot; .
_:b5 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;https://www.w3.org/2019/json-schema#StringSchema&gt; .
_:b2 &lt;https://www.w3.org/2019/td#name&gt; &quot;status&quot; .
_:b5 &lt;https://www.w3.org/2019/td#forms&gt; _:b6 .
_:b5 &lt;https://www.w3.org/2019/td#forms&gt; _:b7 .
_:b6 &lt;http://www.w3.org/2011/http#methodName&gt; &quot;GET&quot; .
_:b6 &lt;https://www.w3.org/2019/td#contentType&gt; &quot;application/json&quot; .
_:b6 &lt;https://www.w3.org/2019/td#href&gt; &quot;https://mylamp.example.com/status&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b6 &lt;https://www.w3.org/2019/td#op&gt; &quot;readproperty&quot; .
_:b7 &lt;http://www.w3.org/2011/http#methodName&gt; &quot;PUT&quot; .
_:b7 &lt;https://www.w3.org/2019/td#contentType&gt; &quot;application/json&quot; .
_:b7 &lt;https://www.w3.org/2019/td#href&gt; &quot;https://mylamp.example.com/status&quot;^^&lt;http://www.w3.org/2001/XMLSchema#anyURI&gt; .
_:b7 &lt;https://www.w3.org/2019/td#op&gt; &quot;writeproperty&quot; .
_:b8 &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;https://www.w3.org/2019/wot-security#BasicSecurityScheme&gt; .
_:b8 &lt;https://www.w3.org/2019/wot-security#schemeName&gt; &quot;basic_sc&quot; .
_:b8 &lt;https://www.w3.org/2019/wot-security#in&gt; &quot;header&quot; .</pre>
            </aside>

            <p>
                Most importantly, the JSON-LD context maps JSON strings to RDF IRIs (hence, the notion
                of <em>context</em>: in two different contexts, the same string can have different
                meanings). The mapping here is rather straightforward: every vocabulary of the TD
                information model is defined its own namespace and every vocabulary term maps to some
                name, appended to the corresponding namespace. Strings that are not part of any
                vocabulary map to RDF literals (strings with an optional datatype). For instance,
                <code>name</code> maps to <code>https://www.w3.org/2019/td#name</code> and
                <code>MyLampThing</code> remains unchanged. Applying this mapping is called
                <a href="https://www.w3.org/TR/json-ld11/#expanded-document-form">context expansion</a>.
            </p>

            <p>
                Then, after expanding JSON strings to full IRIs, all map structures of the JSON
                TD document must be turned into RDF triples. In a simple case, a
                triple is produced for every key/value pair in the map. For instance, the
                very first triple of the example above was produced from <code>"name": "myLampThing"</code>.
            </p>

            <p>
                Other cases rely on specific JSON-LD features. Most of these features were
                introduced in the 1.1 version of the standard and thus require an appropriate
                JSON-LD 1.1 implementation. They are listed below:
            </p>

            <ul>
                <li>
                    <a href="https://www.w3.org/TR/json-ld11/#aliasing-keywords"><em>Aliasing keywords</em></a>:
                    JSON-LD reserved keywords always start with <code>@</code> but in certain cases, it is
                    more convenient to define aliases for these keywords, e.g. to more easily process JSON-LD
                    document in a specific programming environment. In the TD core vocabulary, <code>id</code>
                    is an alias for <code>@id</code>, which must be an IRI used as the subject of triples when
                    producing RDF. For this reason, the first triples in the example have
                    <code>urn:dev:wot:com:example:servient:lamp</code> as a subject instead of an arbitrary
                    blank node.
                </li>
                <li>
                    <a href="https://www.w3.org/TR/json-ld11/#scoped-contexts"><em>Scoped contexts</em></a>:
                    The term <code>properties</code> is used both in the core vocabulary and in the data schema
                    vocabulary. Yet, a JSON string cannot map to two IRIs simultaneously in the same context
                    definition. The mapping from <code>properties</code> to
                    <code>https://www.w3.org/2019/json-schema#properties</code> must therefore be <em>scoped</em>
                    to instances of <code>DataSchema</code> only.
                </li>
                <li>
                    <a href="https://github.com/w3c/json-ld-api/issues/65"><em>Property-based data indexing</em></a>:
                    in the example above, <code>status</code>, <code>toggle</code> and <code>overheating</code>
                    appear as keys in a map but they do not produce triples in which they become predicates. This special
                    structure is called an <a href="https://www.w3.org/TR/json-ld11/#data-indexing">index map</a>.
                    Without any indication in the context, the index key is lost when an index map is turned into RDF.
                    To make the transformation to RDF reversible, it is possible to indicate that index keys should
                    produce triples with a given predicate. Each vocabulary can include an RDF term for this purpose.
                    In the core vocabulary, the property <code>https://www.w3.org/2019/td#name</code> is used.
                </li>
                <li>
                    <a href="https://github.com/w3c/json-ld-syntax/issues/19"><em>Indexing without a predicate</em></a>:
                    in a TD, the security definitions container is mostly syntactic sugar to avoid redundancy
                    in the <code>security</code> definitions. JSON-LD 1.1 includes another indexing mechanism for
                    that purpose. In the above example, <code>securityDefinitions</code> does not produce any
                    triple.
                </li>
            </ul>

            <p class="ednote">
                The last two JSON-LD features (property-based data indexing and indexing without a
                predicate) are still experimental; they have not been published in any Editor's
                Draft yet.
            </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>https://www.w3.org/2019/td/v1</code>, though.
            </p>
        </section>

        <section>
            <h3>Thing Description Ontology</h3>

            <p>
                TD classes and properties have RDF foundations, in the form of a Web
                ontology in the Web Ontology Language [[owl2-overview]]. Some assertions of
                this document are also expressed as OWL axioms.
            </p>

            <p>
                Default values require special care when translating the TD information model
                into OWL.
            </p>

            <p class="issue">
                Currently, the ontology documentation is available
                <a href="https://w3c.github.io/wot-thing-description/ontology/td.html">on w3c.github.io</a>
                but it should eventually be put under the TD namespace, on w3.org.
            </p>
        </section>

    </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>modified</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>modified</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>