index.html

<!DOCTYPE html>
<html lang="en-US">
<head>
<!-- link rel="stylesheet" href="testing/atrisk.css" -->
<meta charset="utf-8" />
<title>Web of Things (WoT) Discovery</title>
<script 
    src="https://www.w3.org/Tools/respec/respec-w3c"
    class="remove"
    defer
></script>
<script class="remove">
        var respecConfig = {
        lint: {
            "check-punctuation": true,
            "local-refs-exist": true,
            "no-http-props": true,
            "no-headingless-sections": true,
            "no-unused-dfns": false
        },
        doJsonLd : true,
        noLegacyStyle: true,
        inlineCSS: true,
        noIDLIn: true,
        specStatus : "ED",
        // crEnd: "2022-08-30",
        implementationReportURI: "https://w3c.github.io/wot-discovery/testing/report.html",
        shortName : "wot-discovery",
        copyrightStart : 2017,
        group: "wg/wot",
        wgPublicList : "public-wot-wg",
        github: {
            repoURL: "https://github.com/w3c/wot-discovery",
            branch: "main"
        },
        previousPublishDate: "2022-08-10",
        previousMaturity: "FPWD",
        editors : [ {
            name : "Andrea Cimmino",
            w3cid : "115672",
            company : "Universidad Politécnica de Madrid",
            companyURL : "https://www.upm.es/"
        }, {
            name : "Michael McCool",
            w3cid : "93137",
            company : "Intel Corp.",
            companyURL : "https://www.intel.com/"
        }, {
            name : "Farshid Tavakolizadeh",
            w3cid : "122520",
            company : "Invited Expert"
        }, {
            name : "Kunihiko Toumura",
            w3cid : "83488",
            company : "Hitachi, Ltd.",
            companyURL : "https://www.hitachi.com/"
        } ],
        formerEditors: [ {
            name : "Farshid Tavakolizadeh",
            w3cid : "122520",
            company : "Fraunhofer-Gesellschaft",
            companyURL : "https://www.fraunhofer.de/",
            retiredDate: "2021-09-30"
        } ],
        otherLinks : [ {
            key : "Contributors",
            data : [ {
              value : "In the GitHub repository",
              href : "https://github.com/w3c/wot-discovery/graphs/contributors"
            } ]
        }, {
          key: "Repository",
          data: [ {
            value: "We are on GitHub",
            href: "https://github.com/w3c/wot-discovery/"
          }, {
            value: "File a bug",
            href: "https://github.com/w3c/wot-discovery/issues"
          } ]
        } ],
        localBiblio : {
            "Discovery-Categorization-IoT" : {
                  title: "A Categorization of Discovery Technologies for the Internet of Things"
                , href: "https://dl.acm.org/doi/10.1145/2991561.2991570"
                , authors: [
                    "Arne Broering", 
                    "Soumya Kanti Datta", 
                    "Christian Bonnet"
                  ]
                , date: "7-9 November 2016"
                , publisher: "Association of Computing Machinery (ACM): IoT'16 Proceedings"
            },
            "GDPR-Defs" : {
                  title: "General Data Protection Regulation (GDPR) Article 4 - Definitions"
                , href: "https://gdpr-info.eu/art-4-gdpr/"
                , publisher: "European Union (EU) and the European Economic Area (EEA)"
            },
            "OWASP-Top-10" : {
                  title: "OWASP Top Ten"
                , href: "https://owasp.org/www-project-top-ten/"
                , publisher: "OWASP"
            },
	    "REST-IOT" : {
                  title: "RESTful Design for Internet of Things Systems"
                , href: "https://datatracker.ietf.org/doc/html/draft-irtf-t2trg-rest-iot-06"
                , authors:  [
                    "Ari Keranen"
                  , "Matthias Kovatsch"
                  , "Klaus Hartke"
                  ]
                , publisher: "IETF"
                , date: "11 May 2020"
            },
            "wot-usecases" : {
                  title: "Web of Things (WoT): Use Cases"
                , href: "https://w3c.github.io/wot-usecases/"
                , authors: [
                    "Michael Lagally"
                  , "Michael McCool"
                  , "Ryuichi Matsukura"
                  , "Tomoaki Mizushima"
                  ]
                , publisher: "W3C"
                , date: "15 October 2020"
                , status: "Editor's Draft",
            },
            "AMPLIFICATION-ATTACKS": {
                title: "Amplification Attacks Using the Constrained Application Protocol (CoAP)",
                href: "https://datatracker.ietf.org/doc/html/draft-irtf-t2trg-amplification-attacks",
                authors: [
                    "John Preuß Mattsson",
                    "Göran Selander",
                    "Christian Amsüss",
                ],
                publisher: "IETF",
                status: "DRAFT",
            },
        }
    };
</script>
<style>
a[href].internalDFN {
        color: inherit;
        border-bottom: 1px solid #99c;
        text-decoration: none;
}
img.wot-diagram {
    max-width: 90%;
    height: auto;
}
.rfc2119-assertion {
  background-color: rgb(230,230,230)
}
</style>
</head>
<body>
    <section id="abstract">
        <p>The W3C Web of Things (WoT) is intended to enable
           interoperability across IoT platforms and application
           domains.  One key mechanism for accomplishing this goal
           is the definition and use of metadata describing the
           interactions an IoT device or service makes available
           over the network at a suitable level of abstraction.  
           The WoT Thing Description specification satisfies this objective.
        </p>
        <p>However, in order to use a Thing its Thing Description
           first has to be obtained.  The <em>WoT Discovery</em> process described 
           in this document addresses this problem.
           WoT Discovery needs to support the distribution of WoT Thing Descriptions
           in a variety of use cases.  This includes ad-hoc and engineered systems;
           during development and at runtime; and on both local and global networks.
           The process also needs to work with existing discovery mechanisms,
           be secure, protect private information, and be able to efficiently
           handle updates to WoT Thing Descriptions and the 
           dynamic and diverse nature of the IoT ecosystem.
        </p>
        <p>The WoT Discovery process is divided into two phases,
           Introduction, and Exploration.  The Introduction phase 
           leverages existing discovery mechanisms but does not directly
           expose metadata; they are simply used to discover Exploration
           services, which provide metadata but only after secure authentication
           and authorization.  This document normatively defines two Exploration
           services: for distributing a single WoT Thing Description from a regular
           web service, including as a special case self-description; 
           and a searchable WoT Thing Description Directory
           service for collections of Thing Descriptions.
           A variety of Introduction services are also described and where
           necessary normative definitions are given to support them.
        </p>
    </section>
    <!-- The following will be filled in by ReSpec -->
    <section id="sotd"></section>
    <section id="introduction">
        <h1>Introduction</h1>
        <p>The Web of Things (WoT) defines an architecture that supports the integration
           and use of web technologies with IoT devices.
           The WoT Architecture [[wot-architecture11]] document defines the basic
           concepts and patterns of usage supported.
           However, the WoT Thing Description [[wot-thing-description11]] is a key
           specification for WoT Discovery since it is the purpose of WoT Discovery
           to make WoT Thing Descriptions available.
           Specifically, WoT Discovery has to allow authenticated and authorized entities
           (and only those entities) to find WoT Thing Descriptions satisfying a set of
           criteria, such as 
          <!-- being near a certain location, or -->
           having certain semantics,
           or containing certain interactions.  Conversely, in order to support
           security and privacy objectives, the WoT Discovery process must not
           leak information to unauthorized entities.  This includes leaking information
           that a given entity is requesting certain information, not just the information
           distributed in the Thing Descriptions themselves.
	    </p>
        <p>There are already a number of discovery mechanisms defined [[Discovery-Categorization-IoT]], 
           so we have to establish why we are proposing a new one.  First, many existing 
           discovery mechanisms have relatively weak security and privacy protections.
           One of our objectives is to establish a mechanism that not only uses best
           practices to protect metadata, but that can be upgraded to support future
           best practices as needed.
           Second, we are using discovery in a broad sense to include both local and
           non-local mechanisms.  While a local mechanism might use a broadcast protocol,
           non-local mechanisms might go beyond the current network segment where broadcast
           is not scalable, and so a different approach, such as a search service, is needed. 
           Our approach is to use existing mechanisms as needed to bootstrap into a more 
           general and secure metadata distribution system.
           Third, the metadata we are distributing, the WoT Thing Description, is highly
           structured and includes rich data such as data schemas and semantic annotations.
           Existing discovery mechanisms based on a list of simple key-value pairs are 
           not appropriate.  
           At the same time, 
           use of existing standards for semantic data query, 
           such as SPARQL [[SPARQL11-OVERVIEW]], 
           while potentially suitable for some advanced use cases, 
           might require too much effort for many anticipated IoT applications.
           Therefore in order to address more basic applications,
           we also define some simpler query mechanisms. 
        </p>
        <p>After defining some basic terminology, we will summarize the basic use cases and
           requirements for WoT Discovery.  These are a subset of the more detailed and
           exhaustive use cases and requirements presented in the WoT Use Cases [[wot-usecases]] and 
           WoT Architecture [[wot-architecture11]] documents.
           Then we will describe the basic architecture of the WoT Discovery process,
           which uses a two-phase Introduction/Exploration approach.  The basic goal of this
           architecture is to be able to use existing discovery standards to bootstrap
           access to protected discovery services, but to distribute detailed metadata only to 
           authorized users, and to also protect those making queries from eavesdroppers 
           as much as possible.
           We then describe details of specific Introduction and Exploration mechanisms.
           In particular, we define in detail a normative API for a 
           WoT Thing Description Directory (WoT TDD) service that provides a search mechanism for
           collections of WoT Thing Descriptions that can be dynamically registered by Things or
           entities acting on their behalf.  The WoT Discovery mechanism however also supports
           distribution of single TDs from regular web services, with a special case of this 
           being self-description.
           Finally, we discuss some security and privacy considerations, including a set of 
           potential risks and mitigations.
        </p>
    </section>
    <!-- The following will be filled in by ReSpec -->
    <section id="conformance"></section>
    <section id="terminology" class="informative">
        <h1>Terminology</h1>

        <p>
            The fundamental WoT terminology such as
            <dfn>Thing</dfn>,
            <dfn>Thing Description</dfn> (<dfn>TD</dfn>),
            <dfn>Thing Model</dfn> (<dfn>TM</dfn>),
            <dfn>Property</dfn>,
            <dfn>Action</dfn>,
            <dfn>Event</dfn>,
            <dfn data-lt="WoT Anonymous Thing Description">Anonymous TD</dfn>,
            <dfn data-lt="WoT Discoverer">Discoverer</dfn>,
            <dfn data-lt="WoT Discovery">Discovery</dfn>,
            <dfn data-lt="WoT Exploration">Exploration</dfn>,
            <dfn data-lt="WoT Introduction">Introduction</dfn>,
            <dfn data-lt="WoT Thing Description Server">Thing Description Server</dfn>
            (<dfn data-lt="WoT TD Server">TD Server</dfn>),
            <dfn data-lt="WoT Thing Description Directory">Thing Description Directory</dfn>
            (<dfn data-lt="WoT TDD">TDD</dfn>),
            <dfn data-lt="WoT Partial Thing Description">Partial TD</dfn>,
            <dfn data-lt="WoT Enriched Thing Description">Enriched TD</dfn>
            are defined in <a href="https://www.w3.org/TR/wot-architecture11/#terminology">Section 3</a>
            of the WoT Architecture 1.1 specification [[?wot-architecture11]].
        </p>
    </section>
    <section id="architecture" class="informative">
        <h1>Architecture</h1>
        <p>
        <a href="#discovery-overview"></a> shows an overview of the WoT Discovery process.
	      Discovery uses a two-phase architecture to resolve the competing requirements to be
        both open and to restrict access to metadata to authorized entities.
	      In the first phase, one or more of a set of relatively open
        "Introduction" mechanisms may be used to generate a set of candidate URLs.  
        These URLs do not themselves contain metadata,
	      but are used in the second stage to reference "Exploration"
        services that can actually provide metadata, after authentication,
        in the form of <a>Thing Descriptions</a>.
       </p>
        <figure id="discovery-overview">
            <img src="images/overview.png"
                srcset="images/overview.svg"
                class="wot-diagram"
                alt="Discovery process overview" />
            <figcaption>Discovery architecture overview.  
              A set of open Introduction mechanisms provides a set of URLs, which
              point at Exploration services that only provide metadata (TDs) after suitable
              authentication.  Thing Links and Thing Description Directories provide
              additional flexibility but retrieving further results from these is
              at the discretion of the application.
            </figcaption>
        </figure>
        <p>
	       The intention is that Introduction mechanisms are relatively open "first contact"
         mechanisms to provide a starting point for the rest of the Discovery process.
         In this document we specify details on several Introduction
         mechanisms, suitable for different use cases, including both local and non-local
         scenarios, but Introductions can in fact be provided by any mechanism that can return a URL.
	       Introductions, however, do not include any security or privacy controls and
	       so should not provide metadata directly. 
         Instead, the URLs provided by Introduction mechanisms reference
	       "Exploration" services.  Exploration services actually do provide metadata,
         but only after suitable authentication and access controls have been applied.
        </p>
	      <p>
	       The Discovery process can produce a <em>set</em> of URLs as output from
	       its Introduction phase, even if only one Introduction mechanism is used
         (some Introduction mechanisms can themselves return multiple URLs).
	       The final output after the Exploration phase
	       can also be a <em>set</em> of Thing Descriptions.
        </p>
        <p>
	       Each URL provided by the Introduction phase always points at an 
         Exploration service endpoint that will return a single Thing Description.
	       In the simplest case this URL references an ordinary resource
         provided by a web server which provides the Thing Description of a Thing 
	       describing an IoT endpoint device.  
         As a special case of this, for self-describing Things an Introduction URL might
	       point directly at an endpoint provided by a 
         Thing serving its own Thing Description.
        </p>
        <p>
	       In general Thing Descriptions might be provided in various ways and
         in particular may not be self-describing.
         For example, 
        </p>
         <ul>
         <li>brownfield devices not designed with the WoT 
             specification in mind will not be capable of serving their
             own Thing Descriptions; 
         </li>
         <li>battery-powered devices may not be online
             most of the time; and 
         </li>
         <li>some devices may not be powerful enough to manage and 
             serve TDs directly.  
         </li>
         </ul>
        <p>
         The Thing Description for such Things should be provided
         by separate services.
        </p>
        <p>
	       This document specifies two special cases that allow for more flexibility:
	      </p>
	      <ul>
	        <li>A Thing Description referenced by an Introduction URL 
            may describe a <a href="#exploration-td-type-thingdirectory">Thing Description Directory</a> service.  
	          A Thing Description Directory service (which is still a Thing) 
            maintains a (possibly dynamic) database of Thing Descriptions.
            Thing Description Directories that maintain large numbers of 
            Thing Descriptions may also support queries that can be used to 
            selectively retrieve Thing Descriptions.
	        </li>
	        <li>
            The second special case is a 
            <a href="#exploration-td-type-thinglink">Thing Link</a>.  
            A Thing Link is also a Thing Description,
            but rather than describing a Thing directly, it holds a link to
            a Thing Description hosted elsewhere.
	          A Thing Description Directory can also store Thing Links
	          which can redirect to other Thing Description Directories, 
            allowing for a linked directory structure.
	        </li>
	      </ul>
        <p>
         It is <em>not</em> mandatory for the Discovery process to retrieve
         the contents of Thing Description Directories and return them as 
         part of the results, 
         because in general this might result in a huge set of results.  
         Instead the application
         should scan the results for Thing Description Directory TDs and
         decide whether to retrieve TDs from them, possibly selectively.
         Likewise, it is not required to follow Thing Links automatically;
         instead the application may choose to follow them selectively.
        </p>
    </section>
    <section id="discoverer-process" class="normative">
        <h1>Discoverer Process</h1>
	<p>In this section we will describe the WoT Discovery process from the point of view of a client,
	and what it means to say that a client supports WoT Discovery.
	We will use the term <a>Discoverer</a> for an entity that is a client of the WoT Discovery
	process.  
	A Discoverer may or may not be a full Consumer.
	A Discoverer does however need to read and extract information from special TDs for Directories 
	and Thing Links and use specific affordances and links provided in them.  
	Conversely, a Consumer may not support Discovery, although it is recommended
	[[wot-architecture11]].
</p>
<p>
	The WoT Discovery process is designed so that nearly any client that can fetch a single TD 
	given a single URI can be said to support WoT Discovery. 
	Of course, Discoverers may support more powerful Discovery mechanisms, but some of these 
	have additional requirements.  
<!--
	For example, using WoT Thing Description Directories (TDDs) requires the use of HTTP, and so
	are only available to Discoverers that support this protocol.  
	However, use of HTTP (and Directories)
	is not in fact a requirement of the WoT Discovery process. 
-->
	Some Introduction mechanisms can return multiple URLs, 
	each of which can in turn be used to fetch at least one TD.
	So even without a TDD, it is possible to discover multiple TDs.
<!--
	For example, a Discoverer supporting only CoAP may want to use
	CoRE-RD as one of its Introduction mechanisms, and a single CoRE-RD instance can provide 
	multiple links to individual TDs. 
	Such a Discoverer could also support multiple Introduction mechanisms whose results are
	merged, such as DNS-SD and CoRE-RD.
-->
	</p>
	<p>
	The following assertions describe the specific responsibilities of a Discoverer:
	</p>
	<ul>
		<li><span class="rfc2119-assertion" id="discoverer-must-support-intros">
			A Discoverer MUST support at least one Introduction mechanism.</span>
			The simplest Introduction mechanism, Direct, simply provides a single URL of a target TD.  
			This assertion results in different minimal requirements depending on
			which Introduction mechanism is selected out of the several available.
			For example, when Direct is used as the sole Introduction mechanism,
			at a minimum a Discoverer must be able to accept a single URL pointing at a TD.
			Note, however, that this TD could still be describing a Directory.
			Another option would be for a Discoverer to implement, as its sole 
			Introduction mechanism, an "automatic" Introduction mechanism such as 
			DNS-SD, possibly in combination with mDNS. 
			In this case the application 
			code running in the Discoverer
			would not have to supply any additional information to invoke Discovery.
		</li>
		<li><span class="rfc2119-assertion" id="discoverer-must-support-fetching">
			A Discoverer MUST support fetching a TD from at least one URL provided as part of the Introduction process.</span>
			In other words, not only must a Discoverer accept URLs pointing at TDs, it must be
			able to fetch that TD, for example by using a GET for an HTTP URL.
			It is permissible to split the implementation of a Discoverer into two components, one that
			fetches/reads a TD and sets up a configuration during installation to be used by a
			run-time component that cannot itself read TDs.
			In this case, however, the latter component is not by itself a Discoverer.
		</li>
		<li><span class="rfc2119-assertion" id="discoverer-may-multiple-intro">
			A Discoverer MAY support multiple invocations of the same Introduction mechanism.</span>
			If multiple invocations of a single Introduction mechanism is supported, 
			or if multiple Introduction mechanisms are used, then the Discoverer needs to
			manage a set of Introduction results.  
			Some Introduction mechanisms themselves return a set of results, e.g. CoRE-RD, DID, or DNS-SD. 
			Some mechanisms, such as scanning Bluetooth beacons, may intrinsically result in separate multiple "invocations".
			However, this Discoverer requirement is optional to support an important special case: 
			it is permissible to have a simple
			Discoverer that only supports a single invocation of a Direct Introduction, 
			directly specifying a single TD via a URL.
                </li>
		<li><span class="rfc2119-assertion" id="discoverer-merge-intros">
			A Discoverer MUST be able to merge URLs resulting from 
			multiple Introduction mechanisms, multiple results from a single Introduction mechanism,
			and multiple Introduction invocations into a single set.</span>
			Note that even if only one Introduction mechanism is supported multiple results might be 
			produced.  
			This assertion states that the overall output of the Introduction phase is
			a single set of URLs.  
			The word "set" is used here in the mathematical sense: the results are unordered and unique.
                        Uniqueness means that if multiple Introductions have the same result, they are merged into
			a single result.
			If the Discoverer only supports one Introduction mechanism and that mechanism
			can only produce one URL, then the "merge" is trivial.
		</li>
		<li><span class="rfc2119-assertion" id="discoverer-td-identify">
			A Discoverer MUST be able to identify whether a TD fetched from an 
			Introduction URL has <a href="#exploration-td-type-thingdirectory">Thing Directory</a>
            or <a href="#exploration-td-type-thingdirectory">Thing Link</a> type.</span>
			This implies that the Discoverer needs to be able
			to check the <code>@type</code> field and make this distinction.

                        A Discoverer can decide whether or not to follow links or fetch TDD contents.
	                There are some use cases where a Consumer may not expand certain URLs, for example links pointing
	                at external resources, or when a TDD contains many TDs and fetching them all
	                would exceed the Consumer's memory processing capabilities.
		</li>
		<li><span class="rfc2119-assertion" id="discoverer-fetch-tdd">
			A Discoverer MAY fetch additional TDs from any Exploration mechanism
			described in its initial set of TDs (including, in particular, Thing Description Directories) 
			and add them into the set of TD results.</span>
			This only adds the results of fetching TDs from an Exploration mechanism to the set of
			results. These new results do not delete the original TD describing the Exploration mechanism. 
                        A Discoverer implementation can decide whether or not to fetch TDD contents.
                        Implementers should consider the fact that TDDs may be large and fetching the contents of an entire TDD
			might be prohibitively expensive.  
		</li>
		<li><span class="rfc2119-assertion" id="discoverer-fetch-links">
			A Discoverer MAY fetch source TDs from the targets of the links in a <a href="#exploration-td-type-thingdirectory">Thing Link</a>
			described in its initial set of TDs and add them into the set of TD results.</span>
			This only adds the results of fetching TDs from a Thing Link to the set of
			results. These new results do not delete the original TD describing the Thing Link. 
			A Discoverer implementation can decide whether or not to fetch the targets of Thing Links.
		</li>
		<li><span class="rfc2119-assertion" id="discoverer-fetch-iteration">
			A Discoverer MAY fetch additional TDs iteratively from any <a href="#exploration-td-type-thingdirectory">Thing Link</a> or
			Exploration mechanism described in its set of TDs and add them into the set of TD results.</span>
			This only adds the results of fetching TDs from an Exploration mechanism to the set of
			results. These new results do not delete the original TD describing the Exploration mechanism. 
		</li>
		<li><span class="rfc2119-assertion" id="discoverer-termination">
			A Discoverer MAY terminate fetching additional TDs at any point or for
			any reason.</span>
	        </li>
		<li><span class="rfc2119-assertion" id="discoverer-any-order">
			A Discoverer MAY fetch additional TDs by following links or fetching
			additional TDs from Exploration mechanisms (e.g. TDDs) in any order.</span>
			The Discoverer can fetch additional TDs in any order from any Exploration mechanism and is not
			required to use all of them.
	        </li>
		<li><span class="rfc2119-assertion" id="discoverer-track">
			A Discoverer MUST track which TDs describing links or Exploration mechanisms
			have already been fetched and avoid fetching duplicate results.</span>
			This is to avoid infinite loops.  Note that Thing Description Directories can easily refer to each other,
			for example, so fetching the TDs from a TDD, then fetching all those TDs will give another copy of the
			original TDD's TD.  This second copy should NOT trigger further fetches. 
			Note that tracking cannot depend only on the value of "id" fields in TDs since this
			field is optional. 
		</li>
        </ul>
	<p>
	The above process supports a way to let Directories reference other Directories without duplicating their TDs: 
	a Directory wanting to reference other Directories should include a <a href="#exploration-td-type-thingdirectory">Thing Link</a> with a "describedby" relation to the
	TD of the other Directory service.  Then the above process would expand the Thing Link to obtain the actual TD of the Directory, 
	and then (optionally) use the appropriate Directory affordance to access the contents of the linked Directory.
	Note that such a Thing Link points at the TD of the Directory, not at the Directory itself.  These
	may or may not be hosted in the same location.
	</p><p>
        Recursively fetching the contents of such linked directories, especially without a specific
	query or filter, could easily result in downloading a large amount of data.  Such recursive expansion should be limited to use
	cases that require it, such as inventory, auditing, or indexing.  
        </p><p>
	URLs for Directory services can also be
	used with the federation capabilities of SPARQL queries, noted below, which in most cases will be a more efficient way
	to collect specific information from a set of distributed directory services.
	However, SPARQL requires the URL of a SPARQL endpoint for such federation, which can be found in the TDs
	of Directories supporting SPARQL queries.  This is not the same as the URL pointing at the TD of a Directory.
	</p>
    </p>
    </section>
    <section id="introduction-mech" class="normative">
        <h1>Introduction Mechanisms</h1>
        <p>This chapter describes mechanisms for initial contact with
           Things or <a>Thing Description Directories</a>.
           Any of the following mechanisms may 
           be provided by the Thing or the <a>Thing Description Directory</a> to Consumers.
           The result of an introduction mechanism is always a URL (address) of an exploration service
           which can be used to obtain detailed metadata (TDs) after suitable authentication.
           It is also possible for multiple introduction mechanisms to be used and the results merged.
           No particular introduction mechanism is mandatory, as long as the URL of at least one
           exploration service is somehow obtained.
        </p>

        <section id="introduction-direct" class="normative">
            <h2>Direct</h2>
            <p><span class="rfc2119-assertion" id="introduction-direct-url">To obtain an URL of an exploration service, any mechanism that results in a single URL MAY be used.</span>
               This includes Bluetooth beacons, QR codes, and written URLs to be 
               typed by a user.
                <span class="rfc2119-assertion" id="introduction-direct-thing-description">
                    A request on all such URLs MUST result in a TD as prescribed in
                    [[[#exploration-mech]]].</span>
                For self-describing Things, this can be the TD of the Thing itself.
                <span class="rfc2119-assertion" id="introduction-direct-directory-description">
                   If the URL references a <a>Thing Description Directory</a>, this MUST be the Thing Description of the
                    <a>Thing Description Directory</a>.</span>
            </p>
        </section>
        <section id="introduction-well-known" class="normative">
            <h2>Well-Known URIs</h2>
            <p>
                <span class="rfc2119-assertion" id="introduction-well-known-uri">A Thing or <a>Thing Description Directory</a> MAY use the Well-Known Uniform Resource Identifier [[RFC8615]]
                to advertise its presence.</span>
                <span class="rfc2119-assertion" id="introduction-well-known-path">If a Thing or <a>Thing Description Directory</a> use the Well-Known Uniform Resource Identifier [[RFC8615]] to advertise its presence, it MUST register its own Thing Description
                into the following path:
                <code>/.well-known/wot</code>.</span>
            <p>
                <span class="rfc2119-assertion" id="introduction-well-known-thing-description">
                    When a request is made at the above Well-Known URI, the server MUST return
                    a Thing Description as prescribed in [[[#exploration-mech]]].</span>
            </p>

        </section>
        <section id="introduction-dns-sd-sec" class="normative">
            <h2>DNS-Based Service Discovery</h2>
            <p><span class="rfc2119-assertion" id="introduction-dns-sd">A Thing or <a>Thing Description Directory</a> MAY use DNS-Based Service Discovery (DNS-SD)[[RFC6763]].</span>
                This can be also be used on the same local network in combination with Multicast DNS (mDNS)[[RFC6762]].
            </p>
            <p>
                The following table lists the service names and protocols for advertising their presense.
                These are normative since each has a valid use with existing exploration mechanisms:
                <table class="def">
                    <thead>
                        <tr>
                            <th>Service name</th>
                            <th>Thing or TDD</th>
                            <th>Protocol</th>
                        </tr>
                    </thead>
                    <tbody>
                        <tr class="rfc2119-table-assertion" id="introduction-dns-sd-service-name">
                            <td><code>_wot._tcp</code></td>
                            <td>Thing</td>
                            <td>HTTP over TCP, HTTP over TLS/TCP, CoAP over TCP, or CoAP over TLS/TCP</td>
                        </tr>
                        <tr class="rfc2119-table-assertion" id="introduction-dns-sd-service-name-directory">
                            <td><code>_directory._sub._wot._tcp</code></td>
                            <td>TDD</td>
                            <td>HTTP over TCP, HTTP over TLS/TCP, CoAP over TCP, or CoAP over TLS/TCP</td>
                        </tr>
                        <tr class="rfc2119-table-assertion" id="introduction-dns-sd-service-name-udp">
                            <td><code>_wot._udp</code></td>
                            <td>Thing</td>
                            <td>CoAP over UDP or CoAP over DTLS/UDP</td>
                        </tr>
                </table>
            </p>
            <p>The following additional service name has been defined for future use.
               This definition is however informative
               since there is currently no defined directory service using CoAP over UDP:
                <table class="def">
                    <thead>
                        <tr>
                            <th>Service name</th>
                            <th>Thing or TDD</th>
                            <th>Protocol</th>
                        </tr>
                    </thead>
                    <tbody>
                        <tr>
                            <td><code>_directory._sub._wot._udp</code></td>
                            <td>TDD</td>
                            <td>CoAP over UDP or CoAP over DTLS/UDP</td>
                        </tr>
                    </tbody>
                </table>
            </p>
                <div class="rfc2119-assertion" id="introduction-dns-sd-txt-record">
                    <p>
                    For TCP-based services,
                    the following information MUST be included in the <code>TXT</code>
                    record that is pointed to by the Service Instance Name:
                    </p>
                    <dl>
                        <dt><code>td</code></dt>
                        <dd>Absolute pathname of the Thing Description of the Thing or Thing Description of the <a>Thing Description Directory</a>.</dd>
                        <dt><code>type</code></dt>
                        <dd>Type of the Thing Description, i.e. <code>Thing</code> or <code>Directory</code>.
                        If omitted, the type is assumed to be <code>Thing</code>.</dd>
                        <dt><code>scheme</code></dt>
                        <dd>Scheme part of URL.  One of the following values can be specified, with the standard registered URI interpretations [[RFC7595]]: <code>http</code> (HTTP over TCP), <code>https</code> (HTTP over TLS/TCP), <code>coap+tcp</code> (CoAP over TCP), or <code>coaps+tcp</code> (CoAP over TLS/TCP).
                        If omitted, the scheme is assumed to be <code>http</code>.</dd>
                    </dl>
                </div>
                <div class="rfc2119-assertion" id="introduction-dns-sd-txt-record-udp">
                    <p>
                    For UDP-based services,
                    the following information MUST be included in the <code>TXT</code>
                    record that is pointed to by the Service Instance Name:
                    </p>
                    <dl>
                        <dt><code>td</code></dt>
                        <dd>Absolute pathname of the Thing Description of the Thing or Thing Description of the <a>Thing Description Directory</a>.</dd>
                        <dt><code>type</code></dt>
                        <dd>Type of the Thing Description, i.e. <code>Thing</code> or <code>Directory</code>.
                        If omitted, the type is assumed to be <code>Thing</code>.</dd>
                        <dt><code>scheme</code></dt>
                        <dd>Scheme part of URL.  One of the following values can be specified, with the standard registered URI interpretations [[RFC7595]]: <code>coap</code> (CoAP over UDP) or <code>coaps</code> (CoAP over DTLS/UDP).
                        If omitted, the scheme is assumed to be <code>coap</code>.</dd>
                    </dl>
                </div>
            <p>
                <a href="#sequence-dnssd-thing"></a> and <a href="#sequence-dnssd-directory"></a> shows example sequences
                supporting discovery of a Thing or a <a>Thing Description Directory</a> using DNS-SD and mDNS. 
            </p>
            <figure id="sequence-dnssd-thing">
                <img src="images/sequence-dnssd-thing.png"
                    srcset="images/sequence-dnssd-thing.svg"
                    class="wot-diagram"
                    alt="An example sequence of discovery of Thing using DNS-SD and mDNS" />
                <figcaption>Using mDNS for discovery of the Thing Description of a Thing</figcaption>
            </figure>
            <figure id="sequence-dnssd-directory">
                <img src="images/sequence-dnssd-directory.png"
                    srcset="images/sequence-dnssd-directory.svg"
                    class="wot-diagram"
                    alt="An example sequence of discovery of directory service using DNS-SD and mDNS" />
                <figcaption>Using mDNS for discovery of the Thing Description of a Thing Description Directory (TDD)</figcaption>
            </figure>

        </section>
        <section id="introduction-core-rd-sec" class="normative">
            <h2>CoRE Link Format and CoRE Resource Directory</h2>
            <p>
                <span class="rfc2119-assertion" id="introduction-core-rd">A Thing or <a>Thing Description Directory</a> MAY advertise its presence using the
                Constrained RESTful Environment (CoRE) Link Format [[RFC6690]].</span>
                <span class="rfc2119-assertion" id="introduction-core-rd-directory">
                A <a>Thing</a> or <a>Thing Description Directory</a> MAY use the CoRE Resource Directory [[RFC9176]]
                to register a link to its corresponding Thing Description.</span>
            </p>
            <p>
                <span class="rfc2119-assertion" id="introduction-core-rd-resource-type-thing">
                    The resource type (<code>rt</code>) of the Link that targets the Thing Description of the Thing
                    MUST be <code>wot.thing</code>.</span>
                <span class="rfc2119-assertion" id="introduction-core-rd-resource-type-directory">
                    The resource type of the Link that targets the Thing Description of the <a>Thing Description Directory</a>
                    MUST be <code>wot.directory</code>.</span>
            </p>
        </section>
        <section id="introduction-did-sec" class="normative">
            <h2>DID Documents</h2>
            <p><span class="rfc2119-assertion" id="introduction-did">A <a>Thing</a> or <a>Thing Description Directory</a> 
                using a Decentralized Identifier (DID) [[DID-CORE]] MAY advertise the location of its <a>TD</a>
                by including a DID Service Endpoint of type 
                <code>WotThing</code> or <code>WotDirectory</code>, respectively, in the DID Document that 
                the TD's identifier resolves to.</span>
            </p>
            <p><span class="rfc2119-assertion" id="introduction-did-service-context">In order to define Service Endpoints
                for WoT Discovery, the DID Document obtained by resolving the DID of a <a>Thing</a> or <a>Thing Description Directory</a>
                MUST include the URL <code>https://www.w3.org/2022/wot/discovery-did</code> in its <code>@context</code> 
                [[did-spec-registries]].
            </span>
            </p>
            <p><span class="rfc2119-assertion" id="introduction-did-service-endpoint">
                If the DID Document obtained by resolving the DID of a <a>Thing</a> or <a>Thing Description Directory</a> 
                contains a Service Endpoint of type <code>WotThing</code> or <code>WotDirectory</code>, respectively,
                then this Service Endpoint MUST refer to the <a>TD</a> describing that Thing 
                (when using the <code>WotThing</code> service name) 
		            or the <a>TD</a> describing that <a>Thing Description Directory</a> (when using the <code>WotDirectory</code> service name),
                respectively
                [[did-spec-registries]].</span>
            </p>
            <aside class="example" title="A Example Service Endpoint in a DID Document - WotThing">
                <pre>
                    {
                        "@context":[
                            "https://www.w3.org/ns/did/v1",
                            "https://www.w3.org/2022/wot/discovery-did"
                        ],
                        ...
                        "service": [{
                            "id": "did:example:wotdiscoveryexample#td",
                            "type": "WotThing",
                            "serviceEndpoint":
                                "https://wot.example.com/.well-known/wot"
                        }]
                        ...
                    }
                </pre>
            </aside>
            <aside class="example" title="A Example Service Endpoint in a DID Document - WotDirectory">
                <pre>
                    {
                        "@context":[
                            "https://www.w3.org/ns/did/v1",
                            "https://www.w3.org/2022/wot/discovery-did"
                        ],
                        ...
                        "service": [{
                            "id": "did:example:wotdiscoveryexample#tdd",
                            "type": "WotDirectory",
                            "serviceEndpoint":
                                "https://wot.example.com/tdd"
                        }]
                        ...
                    }
                </pre>
            </aside>
        </section>
    </section>
    <section id="exploration-mech" class="normative">
        <h1>Exploration Mechanisms</h1>
<!--
        <p class="ednote" title="Exploration Mechanism Overview">
        To do: Description of supported explorations, and requirements for 
        new exploration mechanisms.
        </p>
        <div class="issue" data-number="202"></div>
-->
        This section defines the supported exploration mechanisms
        after providing some common background material.

        <section id="exploration-overview" class="normative">
            <h2>Overview</h2>
            <figure id="exploration-class-diagram">
                <img src="images/exploration-class-diagram.svg"
                    class="wot-diagram"
                    alt="Exploration mechanisms high-level class diagram" />
                <figcaption>
                    The high-level class diagram of the exploration mechanisms,
                    depicting how Thing Description Servers and Thing Description Directories provide <a>TDs</a>.
                    A Self-describing Thing is a special case of a Thing Description Server that is also a Thing.
                    A Thing Description Directory acts as a Thing Description Server for each 
                    Thing Description it contains.
                </figcaption>
            </figure>

            <p>
            [[[#exploration-class-diagram]]] depicts the high-level information 
            model for <a>TD Servers</a> (serving single TDs, including those for self-description) 
            and <a>Thing Description Directory</a> services.
            A <a>Thing Description Directory</a> may contain <a>TDs</a> 
            and at the same time is also a Thing, which means it has its own TD.  
            A directory also hosts web service endpoints 
            for retrieving individual TDs for other Things
            and each of these can be used as a TD Server.
            A Thing may in general host its own TD in which case it
            is a Self-Describing Thing.
            Self-description is not mandatory for directories,
            but Self-Describing Thing Description Directories are possible
            that are both Thing Description Directories and Self-Describing Things.
            </p>
            <p>
            The two basic exploration mechanisms are described in
            [[[#exploration-server]]] and [[[#exploration-directory]]].
            </p>

            <section id="exploration-ontology" class="normative">
                <h3>Ontology</h3>
                <figure id="discovery-class-diagram-ontology">
                    <img src="images/discovery-class-diagram-ontology.svg"
                        class="wot-diagram"
                        alt="Ontology of TD in discovery context" />
                    <figcaption>The ontology of Thing Descriptions in the Discovery context.</figcaption>
                </figure>

                <p>
                    [[[#discovery-class-diagram-ontology]]] illustrates the Discovery ontology
                    as an extension of the Thing ontology.
                </p>
                <p>
                    The ontology includes a class for metadata that are associated with
                    TDs stored in a directory.
                    This class is called `RegistrationInformation` and described as part
                    of the directory specification in [[[#exploration-directory-registration-info]]].
                </p>

                <p>
                    The Discovery ontology also defines two new Thing Description classes,
                    described in the following sections,
                    that may be used to model special exploratory metadata: 
                    <a href="#exploration-td-type-thingdirectory">ThingDirectory</a> and 
                    <a href="#exploration-td-type-thinglink">ThingLink</a>.
                </p>

                <section id="exploration-td-type-thingdirectory" class="normative">
                    <h4>`ThingDirectory`</h4>

                    <span class="rfc2119-assertion" id="exploration-directory-description-type"> 
                        A TD which describes a Thing Description Directory instance MUST use type `ThingDirectory` from the
                        discovery context or URI `https://www.w3.org/2022/wot/discovery#ThingDirectory`.</span>
                    <p>
                        A TD of this class can be derived from Directory's Thing Model; see [[[#directory-api-spec]]].
                    </p>
                
                </section>
                <section id="exploration-td-type-thinglink" class="normative">
                    <h4>`ThingLink`</h4>  

                    <span class="rfc2119-assertion" id="exploration-link-description-type"> 
                        A TD which describes a reference to another TD MUST use type `ThingLink` from the
                        discovery context or URI `https://www.w3.org/2022/wot/discovery#ThingLink`.</span>
                    <span class="rfc2119-assertion" id="exploration-link-description-link"> 
                        A Thing Link MUST define the referenced TD as a Link with
                        `describedby` link relation type, `application/td+json` media type
                        and `href` set to the target URL.</span>

                    <p>
                        [[[#example-td-link-type]]] is an example Thing Link.
                    </p>

                    <!-- Using https://datatracker.ietf.org/doc/html/rfc6963 for ID of examples -->
                    <aside class="example" id="example-td-link-type" title="Example of a Thing Link, referencing a remote TD">
                        <pre>
                            {
                                "@context": [
                                    "https://www.w3.org/2022/wot/td/v1.1",
                                    "https://www.w3.org/2022/wot/discovery"
                                ],
                                "@type": "ThingLink",
                                "id": "urn:example:link",
                                "links": [{
                                    "rel": "describedby",
                                    "href": "https://example.com/td.jsonld",
                                    "type": "application/td+json"
                                }],
                                "security": "nosec_sc",
                                "securityDefinitions": {
                                    "nosec_sc": {
                                        "scheme": "nosec"
                                    }
                                },
                                "title": "Example TD referencing another"
                            }
                        </pre>                   
                    </aside>
                    <p>
                        A Thing Link can be used in various scenarios. For example:
                    </p>
                        <ul>
                            <li>
                                A self-describing Thing with limited computational resources intends
                                to describe itself: host a minimal <a>TD</a> (Thing Link) locally
                                and references a larger one with the full details hosted at a
                                different URL, perhaps in a directory.
                            </li>
                            <li>
                                A self-describing Thing or proxy has a very large or dynamic description:
                                registers a small or static <a>TD</a> (Thing Link) in a 
                                directory which references the actual <a>TD</a> hosted at the edge.
                            </li>
                    <!-- We decided to remove this use case, since it is probably best
                            handled with access controls.  However, this use case AND the ones
                    above imply a mix of link and other metadata and affordances, not
                    "pure" Thing Links.  So we can't in general assume Thing Links
                    don't have other information.  
                            <li>
                                A device intends to publish an entire <a>TD</a> which contains private and
                                public parts: publish one <a>TD</a> (Thing Link) with only the public
                                information referencing another <a>TD</a> which contains the full description.
                            </li>
                    -->
                        </ul>
                </section>
            </section>
            <section id="exploration-secboot" class="normative">
                <h3>Security Bootstrapping</h3>
                <p>The purpose of an exploration service is to serve TDs, but only after suitable
                authentication, and only to authorized parties.  
                However, in some cases a Discoverer may not know what security credentials are
                needed to access a TD via an exploration service, particularly in ad-hoc scenarios.
                Since upon first access to an exploration service a Discoverer will not yet
                have access to the TD if suitable authentication credentials are not provided, 
                the Discoverer can't depend on the security metadata
                held in TDs to know what kind of authentication and authorization information is needed.
                If the Discoverer has no prior knowledge,
                it will have to depend on existing security negotation support to
                bootstrap access, at least to the TD itself.
                </p>
                <p>
                We define the following for the HTTP protocol, for which security negotiation
                processes already exist.
                However, most of the HTTP negotiation processes assume there is a human user in the loop,
                but this is also appropriate for WoT Discovery, since this problem will
                typically occur when a user is trying to access a public WoT service or perform
                integration of a new device. In this case the purpose of negotiation is to
                provide guidance on what credentials are needed to access the system.
                </p>
                <p>
                In cases when exploration services are being used to
                automate system management it would be best to pre-establish what credentials (and
                authentication mechanisms) are needed to access the relevant exploration services
                and security bootstrapping would not be required.  
                For this reason security bootstrapping is not a mandatory feature, and can
                be omitted or disabled on devices that are to be used with pre-established
                security mechanisms.
                </p>
                <p>Security bootstrapping may also only be necessary on the <em>first</em> access to
                a TD. Once a Discoverer has determined what credentials and authentication mechanism
                are required to access a particular exploration service, they can retain this information
                and attempt to use them for future accesses.
                Note however that depending on the security scheme used, credentials themselves
                may expire and may need to be re-established periodically.
                </p>
                <p>
                <span class="rfc2119-assertion" id="security-bootstrapping-endpoints">Security
                bootstrapping MAY be provided on any HTTP endpoint that serves a TD.</span>
<!--
                This applies not only to endpoints serving TDs from self-describing Things,
                but also to endpoints that retrieve single TDs, 
                including those in a <a>WoT Thing Description Directory</a>.  
-->
                As mentioned above, disabling or omitting security bootstrapping is permissible if 
                security mechanisms have been previously established.  For example, if an installation 
                wants to use the OAuth2 <code>client</code> flow and provide potential clients with
                an address of an authentication server to use in advance, then security bootstrapping
                can be disabled, since the alternative would be to include other (and potentially
                weaker) forms of authentication. 
                </p>
                <p>In the HTTP protocol, the authentication and authorization mechanisms to be used can generally be negotiated by
                the HTTP server returning a "401 (Unauthorized)" response code in conjunction with
                a `WWW-Authenticate` header that specifies the information required.
                To gain access, the client then needs to make another request 
                with the necessary information.
                <a href="https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml">There 
                are several authentication schemes registered with IANA.</a>
                However, not all of these are in wide use, some are experimental, and there is only
                partial overlap with the schemes supported by TDs.
                Also, note that the <code>oauth</code> scheme in the IANA registration refers
                to OAuth1, which is deprecated, so it should not be used.
                The relevant OAuth2 flow, the <code>code</code> flow, instead of a 401 response
                begins with a redirection to an authentication
                server, eventually resulting in credentials (bearer tokens in the case of WoT)
                that can be used for access.
                </p>
                <p>
                Given these considerations,
                to enable security bootstrapping on a wide variety of devices as well
                as on browsers, the following constraints should be observed:
                </p>
                <ul>
                <li><span class="rfc2119-assertion" id="exploration-secboot-401">
                If security bootstrapping is enabled on an exploration service,
                after initial contact using the URL provided
                by an introduction mechanism, the exploration service
                MUST reply with an HTTP response code 
                appropriate for one of the Basic, Bearer, Digest, or OAuth2 security schemes if
                authentication information has not been provided but access can be granted
                when it is.</span>
                Note that if the exploration service does not want to provide access for
                some reason, or if security bootstrapping is disabled,
                it can ignore the request or reply with another code such as 404 or 403.
                Also, if no authentication is required, then the 
                system can reply immediately with the requested TD as if authentication information
                were provided.  
                Bypassing authentication however is only
                appropriate if the TD served as a response does not contain and cannot be used to infer 
                Personally Identifiable Information; see <a href="#privacy-considerations"></a>.
                </li>
                <li><!-- <span class="rfc2119-assertion" id="exploration-secboot-auth"> -->
                If security bootstrapping is enabled on an exploration service
                using one of the following IANA-registered
                HTTP Authentication Schemes: Basic, Bearer, or Digest, 
                then (following the standards for these authentication schemes) a 401 HTTP response 
                at an API endpoint intended to serve a TD
                must include a <code>WWW-Authenticate</code> header
                and any other headers
                describing the required authorizations.<!-- </span> -->
                For details of the requirements, the IANA registry should be consulted for
                each of the above authentication schemes.  
                <!-- <span class="rfc2119-assertion" id="exploration-secboot-oauth2-flows"> -->
                Likewise, following the OAuth2 specifications,
                if the OAuth2 <code>code</code> flow is used during security bootstrapping, the
                "302 (Found)" or "303 (See Other)" response code must be used for redirection
                to the authentication server,
                with access credentials eventually being represented with bearer tokens.<!-- </span> -->
                Note that the other OAuth2 flow supported in WoT Thing Description 1.1,
                <code>client</code>, expects the initial access
                to be to the authentication server, not the final endpoint, and so cannot be
                used via security bootstrapping.
                These requirements also apply only to endpoints of exploration services that might need
                to support security bootstrapping, that is those that serve TDs,
                not to other endpoints that might be
                provided by the same exploration service.  
                In particular, these requirements apply
                only to URLs that can be referenced by introduction mechanisms, not to (for example)
                event subscription endpoints.
                </li>
                </ul>
                <p>
                There are relevant Security and Privacy Considerations in [[wot-architecture11]] 
                and [[wot-thing-description11]] 
                regarding when authentication is required for access
                to TDs and the use of secure transport.  
                See also [[[#privacy-considerations]]].
                In summary, secure transport (e.g. TLS) is required for public services and strongly recommended
                even on private networks (even if there is no authentication requirement, to
                protect the confidentiality of queries), and serving requests without authentication and authorization should only be considered 
                in limited circumstances when no Personally Identifiable Information is 
                present or can be inferred.
                </p>
            </section>
        </section>

        <section id="exploration-server" class="normative">
            <h2>Thing Description Server</h2>
            <p>
             Any web service that can be referenced by a URL and return a TD with
             appropriate authentication and access controls can be used as an
             exploration mechanism.  
             We will refer to this as a Thing Description Server or TD Server.
             A TD Server does not need to be a Thing.
             In particular, a TD can be hosted on an ordinary web server
             and referenced by its URL.  
            </p>
            <p>
            A TD Server can be used to support self-description.
            For self-description, a <a>Thing</a>
            hosts its own <a>TD</a> and makes it available via a web resource
            identified with a URL.  Such a web resource however is not included
            as an affordance in the TD itself.  This web resource may or may not
            be the same as the well-known URL used as an Introduction mechanism
            defined in <a href="#introduction-well-known"></a>.
            </p> 
            <p>Use of secure transport is subject to assertions given in the 
            Security Considerations and Privacy Considerations sections of the 
            [[wot-architecture11]] and [[wot-thing-description11]] specifications, 
            which define scenarios where secure transport is recommended or mandatory and mutual 
            authentication is recommended.
            </p>
            <p>
             A TD Server distributing a TD 
             using the following protocols 
             is subject to the following constraints:
            </p> 
            <dl>
                <dt>HTTP</dt>
                <dd>
                    <p>
                        <span class="rfc2119-assertion" id="exploration-server-http-method"> 
                            An HTTP-based TD Server providing a <a>TD</a> 
                            MUST serve that resource with a `GET` method.</span>
                        <span class="rfc2119-assertion" id="exploration-server-http-resp">
                            A successful response from an HTTP-based TD Server providing a <a>TD</a>
                            MUST have 200 (OK) status and the <a>TD</a> in the body.</span>
                        <span class="rfc2119-assertion" id="exploration-server-http-resp-content-type">
                            A successful response with JSON serialization MUST contain either `application/json`
                            or `application/td+json` in the Content-Type header.</span>
                            Here `application/td+json` is preferred as it is 
                            more specific and implies `application/json`.
                        <span class="rfc2119-assertion" id="exploration-server-http-resp-json">
                            The default serialization format for successful response bodies MUST be
                            JSON, with JSON-LD 1.1 [[JSON-LD11]] syntax.</span>
                        The JSON-LD syntax allows semantic extensions and processing.
                        <span class="rfc2119-assertion" id="exploration-server-http-alternate-content">
                            An HTTP-based TD Server providing a <a>TD</a> 
                            MAY provide alternative representations through
                            server-driven content negotiation, that is by honoring the 
                            request's Accept and Accept-Encoding headers and responding with the supported
                            TD serialization and equivalent Content-Type and Content-Encoding headers.</span>
                        <!-- <span class="rfc2119-assertion" id="exploration-server-http-alternate-language"> -->
                        <!-- See also tdd-http-alternate-language -->
                            In addition, following the process normatively defined in the WoT Thing Description 1.1 specification
                            [[wot-thing-description11]],
                            an HTTP-based TD Server providing a <a>TD</a> 
                            may provide modified TDs or error responses 
                            using a different default language after server-driven content negotiation, 
                            that is by honoring the request's Accept-Language header.<!-- </span> -->
                    </p>
                    <p>
                        <span class="rfc2119-assertion" id="exploration-server-http-head">
                            An HTTP-based TD Server providing a <a>TD</a> 
                            MUST respond to `HEAD` requests by returning only the headers
                            equivalent to those returned by a `GET` request to the same endpoint.</span>
                        This enables clients to retrieve HTTP headers such as the Content-Length in advance 
                        to know the size of the <a>TD</a> (in bytes) and decide on an efficient query strategy.
                    </p>
                    <p>
                        In constrained environments, a single <a>TD</a> may be too large to process
                        for the server or clients. 
                        See [[[#perf-incremental-transfer]]] for protocol-specific recommendations on 
                        incremental transfer of the requested payload. 
                    </p>
                    
                    <p>
                        Error responses:  
                    </p>
                        <ul>
                            <li>
                                401 (Unauthorized): No authentication.
                            </li>
                            <li>
                                403 (Forbidden): Insufficient rights to the resource.
                            </li>
                        </ul>
                </dd>
            </dl>
            <dl>
                <dt>CoAP</dt>
                <dd>
                <p>
                    <span class="rfc2119-assertion" id="exploration-server-coap-method">
                        A CoAP-based TD Server providing a <a>TD</a>
                        MUST serve that resource with a `GET` method.</span>
                    <span class="rfc2119-assertion" id="exploration-server-coap-resp">
                        A successful response from a CoAP-based TD Server providing a <a>TD</a>
                        MUST have a 2.05 (Content) status, contain a Content-Format option
                        with value 50 (`application/json`) or 432 (`application/td+json`), 
                        and the <a>TD</a> in the payload.</span>
                    Content-Format 432 is preferred as it is more specific and implies Content-Format 50.
                    Note that the payload might be split over multiple message exchanges using
                    block-wise transfer [[RFC7959]].
                    <span class="rfc2119-assertion" id="exploration-server-coap-alternate-content">
                        A CoAP-based TD Server providing a <a>TD</a>
                        MAY provide alternative representations through
                        server-driven content negotiation, that is by honouring the
                        request's Accept option and responding with the supported
                        <a>TD</a> serialization and equivalent Content-Format option.</span>
                </p>
                <p>
                    <span class="rfc2119-assertion" id="exploration-server-coap-size2">
                        A CoAP-based <a>TD</a> Server providing a <a>TD</a>
                        SHOULD respond to requests containing a Size2 option by including
                        the size estimate of the <a>TD</a> in its next response.</span>
                    This is relevant when obtaining a <a>TD</a> using block-wise transfer and
                    enables clients to abort the retrieval if the total payload size should be too
                    large for them to process.
                </p>
                <p>
                    In constrained environments, a single <a>TD</a> may be too large to process
                    for the server or clients.
                    See [[[#perf-incremental-transfer]]] for protocol-specific recommendations on
                    incremental transfer of the requested payload.
                </p>

                <p>
                    Error responses:
                </p>
                    <ul>
                        <li>
                            4.01 (Unauthorized): No authentication.
                        </li>
                        <li>
                            4.03 (Forbidden): Insufficient rights to the resource.
                        </li>
                    </ul>
            </dd>
            </dl>
        </section>
        
        <section id="exploration-directory" class="normative">
            <h2>Thing Description Directory</h2>
            <p>
             A <a>Thing Description Directory</a> (TDD or Directory for short) is a 
             <a>Thing</a> that provides a service to manage a set of TDs describing other Things.
            </p>

            <section id="exploration-directory-info" class="normative">
                <h3>Information Model</h3>
                <p>
                As shown in [[[#exploration-class-diagram]]], 
                the <a>Thing Description Directory</a> can contain zero or more <a>TDs</a>.
                For every TD, the directory maintains additional metadata
                for bookkeeping and search purposes.
                These are described in
                [[[#exploration-directory-registration-info]]] and
                [[[#exploration-directory-anonymous-td]]].
                A <a>TD</a> that embeds such additional metadata as part of the
                interaction with the directory is called an <a>Enriched TD</a>.
                </p>

                <section id="exploration-directory-registration-info" class="normative">
                    <h4>Registration Information</h4>
                    <p>
                    The ontology of a <a>TD</a> in the Discovery context was
                    introduced in [[[#discovery-class-diagram-ontology]]].
                    The `RegistrationInformation` class is associated with <a>TDs</a> that are
                    stored in a directory. 
                    The following table lists the registration information attributes for
                    use within <a>TDs</a> that embed or reference the Discovery context. 
                    Note that only an <a>Enriched TD</a> embeds the registration information. 
		            <span class="rfc2119-assertion" id="tdd-context-injection">An <a>Enriched TD</a>
                        MUST contain in its @context the URI <code>https://www.w3.org/2022/wot/discovery</code>.</span>
                    In this table,
                    client refers to the producer or consumer of a <a>TD</a> and server refers to
                    the <a>Thing Description Directory</a>.
                    </p>
                    <p>
                    <span class="rfc2119-assertion" id="tdd-absolute-time">Whenever an absolute time is expressed
                    using <a href="https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime">dateTime</a> 
                    it MUST be interpreted as date-time as specified in [[RFC3339]].</span>
                    Specifically, the timezone offset is not optional.
                    </p>
                    <p class="ednote" title="dateTime vs. date-time">We should update the ontology to 
                    only use date-time and RFC3339 and
                    not this odd combination of dateTime and date-time, 
                    but this should also be resolved in the TD specification.
                    However, we would need a new SHACL shape with this additional restriction.
                    </p>
                    
                    <table class="def">
                        <thead>
                            <tr>
                                <th>Vocabulary term</th>
                                <th>Description</th>
                                <th>Client Assignment</th>
                                <th>Server Assignment</th>
                                <th>Type</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-created">
                                <td><code>created</code></td>
                                <td>
                                    Provides the absolute time when the TD instance was
                                    created inside the directory.
                                    <p>
                                        This MAY be set by the directory and returned to consumers.
                                    </p>
                                </td>
                                <td>read-only</td>
                                <td>optional</td>
                                <td><a href="https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td>
                            </tr>
                            <tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-modified">
                                <td><code>modified</code></td>
                                <td>
                                    Provides the absolute time when the TD instance was
                                    last modified inside the directory.
                                    <p>
                                        This MAY be set by the directory and returned to consumers.
                                    </p>
                                </td>
                                <td>read-only</td>
                                <td>optional</td>
                                <td><a href="https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td>
                            </tr>
                            <tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-expires">
                                <td><code>expires</code></td>
                                <td>
                                    Provides the absolute time when the TD instance registration expires.
                                    <p>
                                        The producer MAY set this to indicate the absolute expiry time
                                        during the registration.
                                    </p>
                                    <p>
                                        For servers that support expirable TDs:
                                        If `ttl` (relative expiry) is present, the server MUST ignore
                                        client assignments to `expires` and instead compute and set it internally.
                                    </p>
                                </td>
                                <td>optional</td>
                                <td>optional</td>
                                <td><a href="https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td>
                            </tr>
                            <tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-ttl">
                                <td><code>ttl</code></td>
                                <td>
                                    Time-to-live: relative amount of time in seconds from the registration time 
                                    until when the TD instance registration expires. 
                                    <p>
                                        The producer MAY set this to indicate the relative expiry time
                                        during the registration.
                                    </p>
                                    <p>
                                        For servers that support expirable TDs:
                                        The server MUST use `ttl` to calculate the `expires` (absolute expiry) value.
                                    </p>
                                </td>
                                <td>optional</td>
                                <td>read-only</td>
                                <td><code>number</code></a></td>
                            </tr>
                            <tr class="rfc2119-table-assertion" id="tdd-registrationinfo-vocab-retrieved">
                                <td><code>retrieved</code></td>
                                <td>
                                    The absolute time at which the TD was retrieved from the server.
                                    <p>
                                        This is useful for clients that intend to process other absolute timestamps but
                                        do not have an internal clock or other means of acquiring the current time.
                                    </p>
                                </td>
                                <td>read-only</td>
                                <td>optional</td>
                                <td><a href="https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#dateTime"><code>dateTime</code></a></td>
                            </tr>
                        </tbody>
                    </table>
                </section>
                <section id="exploration-directory-registration-expiry" class="normative">
                    <h4>Registration Expiry</h4>
                    Section [[[#exploration-directory-registration-info]]] introduces some attributes to
                    specify and discover the expiry time of registered <a>TDs</a>. 

                    <p>
                        Producers can set the expiry time to inform the directory and other consumers
                        about the validity of the TD registrations. 
                        The expiry is also a useful indicator to inform the consumers about
                        expiry of dynamic <a>TDs</a>, e.g. when changes to metadata such as
                        geolocation or properties are expected to be valid for a limited period.
                        Consumers may rely on the expiry time to know how long a retrieved <a>TD</a>
                        will be valid and when they need to request a more recent one.
                        Consumers who retrieve an expired TD may consider it as metadata of an
                        inactive client.
                    </p>
                    <p>
                        For the servers, the expiry time is useful for implementing automatic
                        removal of obsolete or accidental registrations.
                        <span class="rfc2119-assertion" id="tdd-registrationinfo-expiry-purge">
                            Servers SHOULD periodically purge TDs that are past 
                            their expiry times.</span>
                        Prescribing a global mandate or upper limit for the expiry time is
                        application-specific and beyond the scope of this specification.
                        <!-- span class="not-a-rfc2119-assertion" id="tdd-registrationinfo-expiry-config" -->
                            Servers may mandate or set a configurable upper limit to expiry times
                            and refuse incompliant requests.
                        <!-- /span -->
                        
                        The purging by servers is particularly beneficial when interacting with
                        clients (e.g. IoT devices) that are unable to explicitly deregister
                        their <a>TDs</a>. This could be due to protocol-specific limitations,
                        failure, destruction, or ungraceful decommissioning.
                        Such clients should set a reasonably short expiry time and periodically
                        extend it during the normal operation. The expiry can be extended by
                        updating the registration either fully or partially, including an update that makes no
                        changes to the TD; see [[[#exploration-directory-api-things-update]]].
                       
                        If a client ceases to operate, a directory with purging capability will
                        automatically remove its registration.
                    </p>
                        
                </section>
                <section id="exploration-directory-anonymous-td" class="normative">
                    <h4>Anonymous TD Identifiers</h4>
                    The directory assigns local identifiers to <a>Anonymous TDs</a>
                    to enable management and retrieval of such TDs from the directory.
                    <span class="rfc2119-assertion" id="tdd-anonymous-td-identifier">
                        In situations where the server exposes an Anonymous TD (e.g. retrieval, listing, search),
                        it MUST add the local identifier as `id` of the TD to allow local referencing.</span>

                    <span class="rfc2119-assertion" id="tdd-anonymous-td-local-uuid">
                        The local identifier SHOULD be a UUID Version 4, presented as a URN [[RFC4122]].</span>
                    UUID Version 4 is a random or pseudo-random number which does not carry unintended information
                    about the host or the resource.
                </section>
            </section>
            <section id="exploration-directory-api" class="normative">
                <h3>Directory Service API</h3>
                <p>
                Directory services provide access to
                <a href="https://www.w3.org/TR/wot-security/#dfn-system-user-data">System User Data</a> 
                and need to provide appropriate security and privacy protections.
                The use of secure transport protocols and access controls for
                authenticity and confidentiality in implementations of the WoT Directory Service API are governed by
                the Security Considerations and Privacy Considerations given in [[wot-architecture11]].
                </p> 
                <p>
                    The HTTP API responses must use appropriate status codes described in 
                    this section for success and error responses.
                    <span class="rfc2119-assertion" id="tdd-http-error-response"> 
                        The HTTP API MUST use the Problem Details [[RFC7807]] format to carry
                        error details in HTTP client error (4xx) and server error (5xx) responses.</span>
                    This enables both machines and humans to know the high-level error class
                    and fine-grained details.
                    <span class="rfc2119-assertion" id="tdd-http-error-response-utf-8">
                        All HTTP API error responses described using Problem Details MUST be encoded using UTF-8.</span>
                    <span class="rfc2119-assertion" id="tdd-http-error-response-lang">
                        HTTP API error responses MAY report details in different languages using
                        proactive negotiation, if the <code>Accept-Language</code> header field has been
                        set in the HTTP request [[RFC7231]].</span>
                </p>

<!-- Deferred
                <p class="issue" data-number="150">
                    There are currently no WoT-specific error classes. In the meantime,
                    the Problem Details error responses may omit the `type` field which defaults
                    to "about:blank" and set `title` to the HTTP status text.
                </p>
-->

                <p>
                    The APIs set the HTTP status codes as defined in 
                    Section 6 of [[RFC7231]].
                    The list of used error codes include (but are not limited to) the following:
                </p>
                    <ul>
                        <li>
                            400 (Bad Request): Invalid client input in body, query, or headers.
                            This is accompanied by an appropriate response message.
                        </li>
                        <li>
                            401 (Unauthorized): The request lacks valid authentication credentials.
                            As noted in [[[#exploration-secboot]]], this is the first
                            step in authentication negotiation, needed to bootstrap secure access to TDs.
                            Information on what credentials are required will be included 
                            in a <code>WWW-Authenticate</code> header.
                        </li>
                        <li>
                            403 (Forbidden): Insufficient rights to access the resource.
                        </li>
                        <li>
                            404 (Not Found): TD or endpoint does not exist.
                            This is accompanied by an appropriate response message.
                        </li>
                    </ul>
                
                <p>
                    <span class="rfc2119-assertion" id="tdd-http-head"> 
                        For each HTTP endpoint that responds to the `GET` method, the server MUST accept `HEAD` 
                        requests and return only the headers.</span>
                    This allows clients to retrieve headers such as the Content-Length without receiving the body
                    and decide on a suitable strategy to query the information. For example, a constrained client can
                    request only the necessary parts of an object (using an appropriate search query) or 
                    retrieve a list of items in small subsets.
                </p>

                <p>
                    In constrained environments, a single TD may be too large to process for the server or clients.
                    This affects both read (i.e. retrieving one or more TDs or TD fragments) 
                    and write (i.e. submitting a TD or Partial TD) operations.
                    See [[[#perf-incremental-transfer]]] for protocol-specific recommendations on
                    incremental transfer of the payloads.
                </p>

                <p>
                    To ensure the safe transmission of data over the URL, it is expected that
                    both client and server percent encode/decode characters that conflict with
                    delimiters in the rest of the URL.
                    These characters are defined as <i>unsafe</i> in
                    Section 2.2 of [[RFC1738]].
                    Unsafe characters can result in unexpected behavior if they appear in the URL, for example,
                    when the resource ID included in the path is a URL by itself, or
                    in the search query string.
                </p>

                <p>
                    The directory APIs include mandatory, recommended, and optional
                    features. 
                    <span class="rfc2119-assertion" id="tdd-http-unsupported-feature">
                        When a directory is unable to answer a request because of unsupported
                        recommended or optional features, it SHOULD inform the client about the
                        absence of those features by returning appropriate HTTP errors.</span>
                    The following examples can be used as guideline for implementations:
                    <ul>
                        <li>
                            If the missing feature is to customize functionality of an
                            existing API
                            use 400 (Bad Request) or 501 (Not Implemented).
                        </li>
                        <li>
                            If an API endpoint is not provided (e.g. `/search/sparql` endpoint),
                            use 404 (Not Found).
                        </li>
                        <li>
                            If a method is not supported on an existing API endpoint
                            (e.g. `PATCH` for `/things` endpoint), use 405 (Method Not Allowed).
                        </li>
                    </ul>

                <p>
                    The process of modifying the default language of a TD using translations already
                    provided in a TD is normatively described in the WoT Thing Description 1.1 specification
                    [[wot-thing-description11]].
                    <!-- span class="not-a-rfc2119-assertion" id="tdd-http-alternate-language" -->
                    <!-- This assertion was removed but technically the process of transforming TDs to
                         use a different default language is covered, normatively, by the TD 1.1 spec,
                         and by the interpretation of a TDD as a TD Processor. 
                         See also the related exploration-server-http-alternate-language for TD Servers. -->
                        Using this process,
                        a Directory server may provide modified TDs, or its own TD, using a different
                        default language after server-driven content negotiation, 
                        that is by honouring the request's Accept-Language header.
                    <!-- /span -->

                <section id="exploration-directory-api-things" class="normative">
                    <h4>Things API</h4>
                    <p>
                        The Things API is a RESTful HTTP API served at the `/things` endpoint
                        providing interfaces to 
                        create, retrieve, update, delete, and list (CRUDL) <a>TDs</a>.
                        The design of this API is in accordance with [[RFC7231]] and [[?REST-IOT]].
                    </p>

                    <p>
                        The HTTP API follows these general rules:
                    </p>
                        <ul>
                            <li>
                                <span class="rfc2119-assertion" id="tdd-things-list-only">
                                    The API MUST provide the interface to list TDs.</span>
                                The Search API allows filtering and selection from this list; see
                                [[[#exploration-directory-api-search]]].
                            </li>
                            <li>
                                <span class="rfc2119-assertion" id="tdd-things-crud">
                                    The API MAY provide the interfaces to
                                    create, read, update, and delete (CRUD) individual TDs.</span>
                            </li>
                            <li>
                                A directory that provides both read and write over HTTP is considered
                                a full HTTP directory.
                                <span class="rfc2119-assertion" id="tdd-things-crudl">
                                    Full HTTP directories SHOULD implement all of
                                    CRUDL (create, read, update, delete, and list) interfaces.</span>
                                It is practical to implement only the interfaces to read and list
                                if the directory serves a static collection of <a>TDs</a>.
                                This is also useful for directories that intend to expose only
                                retrieval operations over HTTP, and perform other operations via out-of-band mechanisms.
                                <span class="rfc2119-assertion" id="tdd-things-read-only-auth">
                                    To expose read-only access, the directory MUST enforce access control
                                    on create, update, and delete interfaces.</span>
                            </li>
                            <li>
                                <span class="rfc2119-assertion" id="tdd-things-default-representation">
                                    The default serialization format for all request and success response bodies MUST be
                                    JSON, with JSON-LD 1.1 [[JSON-LD11]] syntax to support extensions and semantic
                                    processing.</span>
                            </li>
                            <li>
                                <span class="rfc2119-assertion" id="tdd-things-representation-alternate-input">
                                    Directories MAY accept alternative representations based on request's indicated
                                    Content-Type or Content-Encoding headers.</span>
                                This is useful for applications that need to provide representations other than
                                raw JSON as input to a directory.
                            </li>
                            <li>                       
                                <span class="rfc2119-assertion" id="tdd-http-representation-alternate-output">
                                    Directories MAY provide alternative representations through
                                    server-driven content negotiation, that is by honouring the 
                                    request's Accept and Accept-Encoding headers and responding with the supported
                                    TD representation and equivalent Content-Type and Content-Encoding headers.</span>
                                This is useful for applications that need to retrieve representations other than
                                raw JSON from a directory, such as Gzip-compressed JSON.
                            </li>
                        </ul>
                    
                    <p>
                        The CRUDL operations are described in the following sections:
                    </p>

                    <section id="exploration-directory-api-things-creation" class="normative">
                        <h4>Creation</h4>
                        <p>
                            Creation refers to the registration of a new <a>TD</a> inside the directory.
                        </p>
                        <p> 
                            The TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
                            Note that a TD may or may not be generated by the <a>Thing</a> it describes.
                            For brownfield devices in particular a separate <a>Discoverer</a> process
                            or service may be required that generates and registers a TD for a <a>Thing</a>
                            on its behalf.
                        </p>
                        <p>
                            <span class="rfc2119-assertion" id="tdd-things-create-known-vs-anonymous"> 
                                A TD which is identified with an `id` attribute MUST be handled 
                                differently with one that has no identifier (<a>Anonymous TD</a>).</span>
                            The create operations are elaborated below:
                        </p>
                        <ul>
                            <li>
                                <span class="rfc2119-assertion" id="tdd-things-create-known-td">
                                    A TD that has an `id` MUST be submitted to the directory in the body of an HTTP `PUT` request
                                    at `/things/{id}` endpoint, where `id` is the unique TD identifier,
                                    present inside the TD object.</span>
                                An <a>Anonymous TD</a> is handled differently; see below.
                                <span class="rfc2119-assertion" id="tdd-things-create-known-contenttype">
                                    The request SHOULD contain `application/td+json` Content-Type header for 
                                    JSON serialization of TD.</span>
                                The TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
                                <span class="rfc2119-assertion" id="tdd-things-create-known-td-resp">  
                                    Upon successful processing, the server MUST respond with
                                    201 (Created) status.</span>

                                <p>
                                    Note: If the target location corresponds to an existing TD,
                                    the request shall instead proceed as an Update operation and respond
                                    the appropriate status code (see Update section).
                                </p>
                                <p>
                                    The create operation for <a>TDs</a> that have identifiers is specified
                                    as `createThing` action in [[[#directory-api-spec]]].
                                </p>
                            </li>
                            <li>
                                <span class="rfc2119-assertion" id="tdd-things-create-anonymous-td">
                                    An <a>Anonymous TD</a> MUST be submitted to the directory in the body of
                                    an HTTP `POST` request at `/things` endpoint.</span>
                                <span class="rfc2119-assertion" id="tdd-things-create-anonymous-contenttype">
                                    The request SHOULD contain `application/td+json` Content-Type header for 
                                    JSON serialization of TD.</span>
                                The TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
                                <span class="rfc2119-assertion" id="tdd-things-create-anonymous-id">
                                    The directory MUST assign a local identifier to any <a>Anonymous TD</a>
                                    to enable local management and retrieval from the directory.</span>
                                The scheme of the system-generated ID is described in [[[#exploration-directory-anonymous-td]]].

                                <span class="rfc2119-assertion" id="tdd-things-create-anonymous-td-resp">
                                    Upon successful processing, the server MUST respond with 201 (Created) status
                                    and a Location header containing the system-generated URI of created TD resource.</span>
                                The system-generated URI includes the system-generated identifier of the TD and
                                can be used subsequently to query the TD from the directory.

                                <p>
                                    The create operation for <a>Anonymous TDs</a> is specified as `createAnonymousThing` action in
                                    [[[#directory-api-spec]]].
                                </p>
                            </li>
                        </ul>

                        <p>
                            A server that supports expirable TDs will realize such functionality
                            as described in [[[#exploration-directory-registration-expiry]]].
                            In particular, if `ttl` (relative expiry) is given during the creation,
                            such servers will calculate and store the `expires` value.
                        </p>
                    </section>

                    <section id="exploration-directory-api-things-retrieval" class="normative">
                        <h4>Retrieval</h4>
                        <p>
                            <span class="rfc2119-assertion" id="tdd-things-retrieve">
                                The retrieval of an existing TD MUST be done using an HTTP `GET` request
                                at `/things/{id}` endpoint, where `id` is the unique TD identifier.</span>
                            <span class="rfc2119-assertion" id="tdd-things-retrieve-resp">
                                A successful response MUST have 200 (OK) status and the requested TD in the body.</span>
                            <span class="rfc2119-assertion" id="tdd-things-retrieve-resp-content-type">
                                A successful response with JSON serialization MUST contain either `application/json`
                                or `application/td+json` in the Content-Type header.</span>
                            Here `application/td+json` is preferred as it is 
                            more specific and implies `application/json`.
                            Note that the default serialization is JSON with JSON-LD syntax,
                            and alternative serializations can be negotiated; see [[[#exploration-directory-api-things]]].
                            <p>
                                The retrieve operation is specified as `retrieveThing` action in 
                                [[[#directory-api-spec]]].
                            </p>
                        </p>

                        <p>
                            The following is an example of a retrieved TD:
                        </p>
                            <aside class="example" id="example-enriched-td" title="Example Enriched TD">
                                <pre>
                                    {
                                        "@context": [
                                            "https://www.w3.org/2022/wot/td/v1.1",
                                            "https://www.w3.org/2022/wot/discovery"
                                        ],
                                        "id": "urn:example:simple-td",
                                        "security": "basic_sc",
                                        "securityDefinitions": {
                                            "basic_sc": {
                                                "scheme": "basic"
                                            }
                                        },
                                        "registration": {
                                            "created": "2021-01-19T17:02:00Z",
                                            "modified": "2021-01-19T17:02:00Z"
                                        },
                                        "title": "Simple TD"
                                    }
                                </pre>                   
                            </aside>
                            <p>
                            This is an <a>Enriched TD</a> which includes the registration information
                            such as the creation and modification time of the TD within the directory.
                        </p>
                        
                        <p>
                            The example below shows a retrieved <a>Anonymous TD</a> that is in
                            <a>Enriched TD</a> form and has local identifier `urn:uuid:48951ff3-4019-4e67-b217-dbbf011873dc`.
                        </p>
                            <aside class="example" id="example-anonymous-enriched-td" title="Example Enriched Anonymous TD">
                                <pre>
                                    {
                                        "@context": [
                                            "https://www.w3.org/2022/wot/td/v1.1",
                                            "https://www.w3.org/2022/wot/discovery"
                                        ],
                                        "id": "urn:uuid:48951ff3-4019-4e67-b217-dbbf011873dc",
                                        "security": "basic_sc",
                                        "securityDefinitions": {
                                            "basic_sc": {
                                                "scheme": "basic"
                                            }
                                        },
                                        "registration": {
                                            "created": "2021-01-19T17:02:00Z",
                                            "modified": "2021-01-19T17:02:00Z"
                                        },
                                        "title": "Anonymous TD"
                                    }
                                </pre>                   
                            </aside>

                        <p>

                            The following is an example of a retrieved TD that was registered with a relative
                            expiry time of 3600 seconds (one hour). The server has calculated the absolute expiry time as 
                            one hour after the modification time.
                            </p>
                            <aside class="example" id="example-expirable-enriched-td" title="Example Expirable Enriched TD">
                                <pre>
                                    {
                                        "@context": [
                                            "https://www.w3.org/2022/wot/td/v1.1",
                                            "https://www.w3.org/2022/wot/discovery"
                                        ],
                                        "id": "urn:example:expirable-td",
                                        "security": "basic_sc",
                                        "securityDefinitions": {
                                            "basic_sc": {
                                                "scheme": "basic"
                                            }
                                        },
                                        "registration": {
                                            "created": "2021-05-10T16:00:00Z",
                                            "modified": "2021-05-10T17:00:00Z",
                                            "expires": "2021-05-10T18:00:00Z",
                                            "ttl": 3600,
                                            "retrieved": "2021-05-10T17:35:00Z"
                                        },
                                        "title": "Expirable TD"
                                    }
                                </pre>                   
                            </aside>
                            <p>
                            For the sake of readability, the time values in this example are set to exact numbers.
                            In realistic settings, time values may include fractions.
                        </p>

                    </section>

                    <section id="exploration-directory-api-things-update" class="normative">
                        <h4>Update</h4>
                        <p>
                            The update operations are to replace or partially modify an existing TD.
                        </p>
                        <p>
                            The update operations are described below:
                        </p>

                        <ul>
                            <li>
                                <span class="rfc2119-assertion" id="tdd-things-update">
                                    A modified TD MUST replace an existing one when submitted using an HTTP `PUT` request
                                    at `/things/{id}` endpoint, where `id` is the identifier of the existing TD.</span>
                                <span class="rfc2119-assertion" id="tdd-things-update-contenttype">
                                    The request SHOULD contain `application/td+json` Content-Type header for JSON
                                    serialization of TD.</span>
                                The TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
                                <span class="rfc2119-assertion" id="tdd-things-update-resp">
                                    Upon success, the server MUST respond with 204 (No Content) status.</span>

                                <p>
                                    This operation is specified as `updateThing` property in 
                                    [[[#directory-api-spec]]].
                                </p>

                                <p>
                                    A server that supports expirable TDs will realize such functionality
                                    as described in [[[#exploration-directory-registration-expiry]]].
                                    If `ttl` (relative expiry) is set during the update operation,
                                    the server will calculate and set the `expires` (absolute expiry) value.
                                </p>

                                <p>
                                    Note: If the target location does not correspond to an existing TD,
                                    the request shall instead proceed as a Create operation and respond
                                    the appropriate status code (see Create section). In other words, an HTTP `PUT`
                                    request acts as a create or update operation.
                                </p>
                            </li>
                            <li>
                                <span class="rfc2119-assertion" id="tdd-things-update-partial">
                                    An existing TD MUST be partially modified when the modified parts are submitted using an 
                                    HTTP `PATCH` request
                                    at `/things/{id}` endpoint, where `id` is the identifier of the existing TD.</span>
                                <span class="rfc2119-assertion" id="tdd-things-update-partial-mergepatch">
                                    The partial update MUST be processed using the JSON merge patch
                                    format described in [[RFC7396]].</span>
                                <span class="rfc2119-assertion" id="tdd-things-update-partial-contenttype">
                                    The request MUST contain `application/merge-patch+json` Content-Type header for JSON
                                    serialization of the merge patch document.</span>
                                <span class="rfc2119-assertion" id="tdd-things-update-partial-partialtd">
                                    The input MUST be in <a>Partial TD</a> form and conform to the
                                    original TD structure.</span>
                                
                                If the input contains members that appear in the original TD, 
                                their values are replaced. If a member does not appear in the 
                                original TD, that member is added. If the member is set to `null` 
                                but appear in the original TD, that member is removed. 
                                Members with object values are processed recursively.
                                
                                After applying the modifications, the TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
                                <span class="rfc2119-assertion" id="tdd-things-update-partial-resp">
                                    Upon success, the server MUST respond with a 204 (No Content) status.</span>

                                <p>
                                    This operation is specified as `partiallyUpdateThing` property in 
                                    [[[#directory-api-spec]]].
                                </p>

                                <p>
                                    A server that supports expirable TDs will realize such functionality
                                    as described in [[[#exploration-directory-registration-expiry]]].
                                    During the partial update operation, if the resulting <a>TD</a> has 
                                    `ttl` (relative expiry), the server will calculate and set a new
                                    `expires` (absolute expiry) value.
                                </p>
                                
                                <p>
                                    A patch operation is particularly useful to efficiently extend the expiry of
                                    a registration that uses a `ttl` (relative expiry) value.
                                    This is typically done by submitting an empty merge patch document,
                                    i.e. an empty JSON object.
                                    This effectively translates to performing a partial update operation that
                                    updates nothing, but triggers the recalculation of `expires` (absolute expiry) value.
                                    This expiry functionality only works if the server supports it as defined in
                                    [[[#exploration-directory-registration-expiry]]].
                                </p>

                                <p>
                                    The following example is a merge patch document to update only the
                                    `base` and registration `expires` fields of a TD:
                                </p>
                                    <aside class="example" id="example-patch-enriched-td" title="Example merge patch document">
                                        <pre>
                                            {
                                                "base": "http://192.168.0.2/",
                                                "registration": {
                                                    "expires": "2021-01-20T17:02:00Z"
                                                }
                                            }
                                        </pre> 
                                        This is a valid way of extending the absolute expiry only if the stored
                                        TD has no `ttl` (relative expiry).
                                        For more details, refer to [[[#exploration-directory-registration-expiry]]].                   
                                    </aside>
                            </li>
                        </ul>

                    </section>

                    <section id="exploration-directory-api-things-deletion" class="normative">
                        <h4>Deletion</h4>
                        <p>
                            <span class="rfc2119-assertion" id="tdd-things-delete">
                                A delete operation MUST be done using an HTTP `DELETE` request
                                at `/things/{id}`, where `id` is the identifier of the existing TD.</span>
                            <span class="rfc2119-assertion" id="tdd-things-delete-resp">
                                A successful response MUST have 204 (No Content) status.</span>
                            The retrieve operation is specified as `deleteThing` property in
                            [[[#directory-api-spec]]].
                        </p>

                    </section>

                    <section id="exploration-directory-api-things-listing" class="normative">
                        <h4>Listing</h4>
                        <p>
                            The listing endpoint provides different ways to query the collection of full TD objects
                            from the directory.
                        </p>
                        <p>
                            In many scenarios, retrieving parts instead of full TD objects is preferred because
                            only a subset of elements are needed (e.g. `id` and `href` of a property for all TDs)
                            and to save networking resources. The Search API allows querying parts of TD objects;
                            see [[[#exploration-directory-api-search]]].
                        </p>
                        
                            
                        <p>
                            <span class="rfc2119-assertion" id="tdd-things-list-method">
                                The directory MUST allow retrieval of existing TDs using HTTP `GET` requests
                                at the `/things` endpoint.</span>
                        
                            <span class="rfc2119-assertion" id="tdd-things-list-resp">
                                A successful response MUST have 200 (OK) status and an array of TDs in the body.</span>
                            <span class="rfc2119-assertion" id="tdd-things-list-resp-content-type">
                                A successful response with JSON serialization MUST contain either `application/json`
                                or `application/ld+json` in the Content-Type header.</span>
                            Here `application/ld+json` is preferred as it is 
                            more specific and implies `application/json`.
                            Note that the default serialization is JSON with JSON-LD syntax,
                            and alternative serializations can be negotiated; see [[[#exploration-directory-api-things]]].
                        </p>

                        <p>
                            There may be scenarios in which clients need to retrieve the collection
                            in small subsets of TDs. 
                            While the Search API ([[[#exploration-directory-api-search]]])
                            does offer the ability to query a specific range, it may not be optimal,
                            nor developer-friendly.
                            
                            <span class="rfc2119-assertion" id="tdd-things-list-pagination">
                                The server MAY support pagination to return the collection
                                in small subsets.</span>
                            The pagination must be based on the following rules:
                            </p>
                            <ul>
                                <li>
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-limit">
                                        When the `limit` query parameter is set to a positive integer,
                                        the server MAY respond with a subset of TDs totalling
                                        to less than or equal to the requested number.</span>
                                </li>
                                <li>
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-header-nextlink">
                                        When there are more TDs after a returned subset of the collection,
                                        the response MUST contain a `next` Link header [[RFC8288]]
                                        with the URL of the next subset.</span>
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-header-nextlink-attr">
                                        The `next` link MUST include all arguments needed to produce the same set of
                                        data and its ordering, in particular the same `limit` argument
                                        given on the initial request as well as a zero-based `offset` argument anchored
                                        at the beginning of the next subset.</span>
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-header-nextlink-base">
                                        The link MUST be absolute or relative to directory API's base URL.</span>
                                    Moreover, it may include additional arguments that are necessary for
                                    ordering or session management.
                                </li>
                                <li>
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-header-canonicallink">
                                        All paged responses MUST contain a `canonical` Link header [[RFC8288]]
                                        pointing to the collection and include an `etag` parameter to represent
                                        the current state of the collection.</span>
                                    The link may be absolute or relative to directory API's base URL.
                                    The `etag` value could be a revision number, timestamp, or UUID Version 4,
                                    set whenever the TD collection changes in a way that affects the
                                    ordering of the TDs. 
                                    The clients may rely on the `etag` value to know whether the collection
                                    remains consistent across paginated retrieval of the collection.
                                    For example, creation or deletion of TDs or update of TD fields used for
                                    ordering may shift the calculated paging window.
                                </li>
                                <li>
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-order-default">
                                        The collection MUST be sorted in ascending order using Unicode code point order
                                        by the unique identifier of TDs.</span>
                            <!-- Made informative since underspecified in the original, e.g. how a field should be selected was
                                 not clearly stated.  This revision says JSON pointer to be clear, but that version only had one
                                 implementation (that I know of).  However, taking out the selection of custom fields makes all the
                                 other assertions here not-so-useful.  Sort order might be useful even on id but it's mixed in
                                 with another assertion, so we don't have separate test data for it.

                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-order">
                                        The server MAY support sorting by other TD attributes using
                                        query arguments: `sort_by` to select a field 
                                          [!-- older example, assumes plain field syntax, top-level fields only? --] (e.g. `created`)
                                          [!-- proposed --] using a JSON Pointer [[RFC6901] (e.g. `/title`) [!-- to be discussed; + "plain field" syntax? --]
                                        and `sort_order` to choose the order
                                        (i.e. `asc` or `desc` for ascending and descending ordering).</span> 
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-orderable">
                                        A server MUST reject requests to sort on fields that do not have 
                                        values that are orderable basic types.</span>
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-order-unsupported">
                                        If the server does not support custom sorting,
                                        it MUST reject the request.</span>
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-order-nextlink">
                                        If sorting attributes are accepted, they MUST be added consistently to all `next` links.</span>
                                    <span class="rfc2119-assertion" id="tdd-things-list-pagination-order-utf-8">
                                        Sorting order MUST always be defined based on Unicode code points on
                                        the relevant fields.</span>
			    -->
                                </li>
                            </ul>
                            <p>
                                This above specification follows a subset of Linked Data Paging [[?LDP-Paging]]
                                to allow optional pagination of the JSON-LD array.
                                Additional parts of Linked Data Paging may be implemented for examples
                                to honour client's query preference or to add other link relations for semantic
                                annotation and alternative navigation links.
                            </p>
                            <p>                            
                            The following example provides a walk-through of the paginated
                            retrieval of TDs:
                            </p>
                            <aside class="example" id="example-pagination"
                                title="Query all TDs with page size 10.">
                                The client requests the list with a `limit` of 10:
                                <pre>
                                    GET /things?limit=10 HTTP/1.1   
                                    Host: tdd.example.com
                                </pre>
                                Response:
                                <pre>
                                    HTTP/1.1 200 OK
                                    Content-Type: application/ld+json
                                    Link: &#x3C;/things?offset=10&#x26;limit=10&#x3E;; rel=&#x22;next&#x22;
                                    Link: &#x3C;/things&#x3E;; rel=&#x22;canonical&#x22;; etag=&#x22;v1&#x22;

                                    [{ TD }, ...9 other TDs... ]
                                </pre>
                                The response includes two Link headers with relative URLs:
                                `next` link to query the remaining TDs,
                                `canonical` link referencing the full collection with `etag` value indicating
                                the state of that collection.
                                <br>
                                The response body is an array of 10 TDs.
                                
                                <br><br>
                                The presence of the `next` link implies that subsequent pages should be
                                queried for the remaining TDs.
                                The client requests the next page via the `next` link:
                                <pre>
                                    GET /things?offset=10&limit=10 HTTP/1.1   
                                    Host: tdd.example.com
                                </pre>

                                Response:
                                <pre>
                                    HTTP/1.1 200 OK
                                    Content-Type: application/ld+json
                                    Link: &#x3C;/things&#x3E;; rel=&#x22;canonical&#x22;; etag=&#x22;v1&#x22;
    
                                    [{ TD }, { TD }]
                                </pre>
                                The server response has the remaining two TDs. There is no `next` link,
                                because this is the last page. The `etag` value has not changed implying
                                that the collection has remained consistent between the two requests.
                                <br><br>
                                The client has retrieved the whole collection, containing 12 TDs.
                            </aside>

			<p>
				<span class="rfc2119-assertion" id="tdd-things-list-pagination-collection">
					As an alternative to an array of TDs as the body of the response, the server MAY
					send a more verbose payload allowing server-side information, such as pagination
					information, to be included in addition to the actual data.</span>
			</p>

			<p>
				The alternative pagination format is inspired by
				<a href="https://www.hydra-cg.com/spec/latest/core/#advanced-concepts">
				Hydra Advanced Concepts</a>, more concretely the
				<a href="https://www.hydra-cg.com/spec/latest/core/#example-20-a-hydra-partialcollectionview-splits-a-collection-into-multiple-views">
				Partial Collection View</a>. Adapted to our purposes and using the <i>members</i> field to accomodate the array
				of TDs, it looks as follows for the listing endpoint:
			</p>
				<aside class="example" id="example-alternative-payload"
					title="Alternative payload format including pagination information">
					<pre>
						{
							"@context": "https://www.w3.org/2022/wot/discovery",
							"@type": "ThingCollection",
							"total": 12,
							"members": [
								{ TD },
								9 other TDs...
							],
							"@id": "/things?offset=0&limit=10&format=collection",
							"next": "/things?offset=10&limit=10&format=collection"
						}
					</pre>                    
				</aside>

			<p>
				To tell the server which format to send, the additional query parameter <code>?format=array|collection</code>
				can be added to the request. <code>?format=array</code> is the default parameter, does not have to be provided
				explicitly, and yields to a server response of the pure array of TDs. <code>?format=collection</code>
				should yield to a server response with the format as described in [[[#example-alternative-payload]]].
			</p>

                        <p>    
                            The listing operation is specified as `things` property in 
                            [[[#directory-api-spec]]].
                        </p>
                        
                    </section>

                    <section id="exploration-directory-api-things-validation" class="normative">
                        <h4>Validation</h4>
                        <p>
                           <span class="rfc2119-assertion" id="tdd-validation-syntactic">
                                The syntactic validation of TD objects before storage is RECOMMENDED to
                                prevent common erroneous submissions.</span>
    
                            <span class="rfc2119-assertion" id="tdd-validation-jsonschema">
				The server SHOULD use at least 
				<a href="https://www.w3.org/TR/wot-thing-description11/#minimal-validation-serialization-json">Minimal Validation</a> 
				as defined in [[wot-thing-description11]]
                                to validate TDs, including use of the
				<a href="https://www.w3.org/TR/wot-thing-description/#json-schema-for-validation">WoT Thing Description (1.0) JSON Schema</a> or
                                <a href="https://www.w3.org/TR/wot-thing-description11/#json-schema-for-validation">WoT Thing Description 1.1 JSON Schema</a>,
				and the JSON schema defined in [[[#tdd-extensions-jsonschema]]] for <a>Enriched TDs</a>,
				as appropriate based on the value of the <code>@context</code>.</span>
                        </p>
                        <p>
                            Additional forms of validation can be added to support various use cases.
                            For example, a use case may require stateful validation of the input TDs to ensure that
                            the `version` value is initialized and updated according to pre-defined rules.
                        </p>
                        <p>
                            <span class="rfc2119-assertion" id="tdd-validation-result">
                                If the server fails to validate the TD object, it MUST inform the client
                                with necessary details to identify and resolve the errors.</span>
    
                            <span class="rfc2119-assertion" id="tdd-validation-response">
                                The validation error MUST be described as Problem Details [[RFC7807]]
                                with an extension field called `validationErrors`, set to an array of objects
                                with `field` and `description` fields.</span>
                            This is necessary to represent the error in a machine-readable way. 
                            <span class="rfc2119-assertion" id="tdd-validation-response-utf-8">
                                All validation error responses described using Problem Details MUST be encoded using UTF-8.</span>
                            <!-- span class="not-a-rfc2119-assertion" id="tdd-validation-response-lang" -->
                            <!-- Technically we don't need this assertion, as it is covered by more general assertions
                                 about supporting language negotiation for error messages; see in
                                 particular tdd-http-error-response-lang -->
                            As already stated in general for error reporting,
                                validation error responses may report details in different languages using
                                proactive negotiation, if the <code>Accept-Language</code> header field has been
                                set in the HTTP request [[RFC7231]].
                            <!-- /span -->
                        </p>
                        <p>
                        [[[#example-validation-error]]] is an example error response with two validation errors.
                        </p>
                        <aside class="example" id="example-validation-error" title="Example validation error response">
                            <pre>
                                {
                                    "title": "Bad Request",
                                    "status": 400,
                                    "detail": "The input did not pass the JSON Schema validation",
                                    "instance": "/errors/30585584-cce2-4d04-8079-67b33ffdafbc",
                                    "validationErrors": [
                                        {
                                            "field": "(root)",
                                            "description": "security is required"
                                        },
                                        {
                                            "field": "properties.status.forms.0.href",
                                            "description": "Invalid type. Expected: string, given: integer"
                                        }
                                    ]
                                }                      
                            </pre>
<!-- Deferred
                            <p class="issue" data-number="150">
                                This example skips the `type` field 
                                due to the current lack of WoT-specific error types.
                            </p>
-->
                        </aside>
                    </section>

                </section>
                <section id="exploration-directory-api-notification" class="normative">
                    <h4>Events API</h4>
                    <p>
                        The Notification API is to notify clients about the changes
                        to <a>TDs</a> maintained within the directory.
                        <span class="rfc2119-assertion" id="tdd-notification">
                            Directories MAY implement the Notification API.</span>
                    </p>
                    <p>
                        
                        <span class="rfc2119-assertion" id="tdd-notification-sse">
                            The Notification API MUST follow the Server-Sent Events (SSE) [[HTML]]
                            specifications to serve events to clients
                            at `/events` endpoint.</span>
                        In particular, the server responds to successful requests with 200 (OK) status
                        and `text/event-stream` Content Type.
                        Re-connecting clients may continue from
                        the last event by providing the last event ID as `Last-Event-ID` header value.
                        <span class="rfc2119-assertion" id="tdd-notification-event-id">
                            The server SHOULD provide an event ID as the `id` field in each event
                            and respond to re-connecting clients by delivering all missed events.</span>
                    </p>
                    <p>
                        The rest of this section describes the implementation details on top of the SSE protocol.
                        Realizing the notification functionality using other protocols such as
                        MQTT are possible and may be formalized in future versions of this specification.
                    </p>

                    <dl>
                        <dt>Event Types</dt>
                        <dd>
                            <span class="rfc2119-assertion" id="tdd-notification-event-types">
                                The server MUST produce events attributed to the lifecycle of 
                                the Thing Descriptions within the directory using 
                                `thing_created`, `thing_updated`, and `thing_deleted` event types.</span>
                        </dd>

                        <dt>Event Filtering</dt>
                        <dd>
                            The API enables server-side filtering of events to reduce resource consumption
                            by delivering only the events required by clients.
                            Client libraries may offer additional filtering capabilities on
                            the client-side.

                            <p>
                                <span class="rfc2119-assertion" id="tdd-notification-filter-type">
                                    The server MUST support event filtering based on the 
                                    event type given by the client upon subscription.</span>
                            </p>
                            <p>
                                For example, given the URI Template `/events{/type}`:
                            </p>
                                <ul>
                                    <li>
                                        `/events/thing_created` instructs the server to only deliver events of
                                        type `thing_created`
                                    </li>
                                    <li>
                                        `/events` instructs the server to deliver all events
                                    </li>
                                </ul>
                           <p>
                                The clients need to subscribe separately to receive a subset of
                                the events (e.g. only `thing_created` and `thing_deleted`) from the server. 
                                When using HTTP/2, multiple subscriptions on the same domain (HTTP streams) 
                                get multiplexed on a single connection.
                            </p>

<!-- Defer
                            <div class="issue" data-number="176">
                                Event filtering based on the payload is work in progress. 
                            </div>
-->
                        </dd>
                        <dt>Event Data</dt>
                        <dd><p>
                            <span class="rfc2119-assertion" id="tdd-notification-data">
                                The event data MUST contain the JSON serialization of the event object.</span>
                            The event data object is a <a>Partial TD</a> or the whole <a>TD</a> object
                            depending on the request:
                            </p>
                            <ul>
                                <li>
                                    <span class="rfc2119-assertion" id="tdd-notification-data-td-id">
                                        The event data object MUST at least include the identifier of the
                                        TD created, updated, or deleted at that event in <a>Partial TD</a> form.</span>

                                    <aside class="example" title="Creation and deletion SSE events for a TD">
                                        <pre>
                                            event: thing_created
                                            data: {"id": "urn:example:simple-td"}
                                            id: event_1

                                            event: thing_deleted
                                            data: {"id": "urn:example:simple-td"}
                                            id: event_2
                                        </pre>
                                    </aside>
                                </li>
                                <li>
                                    <span class="rfc2119-assertion" id="tdd-notification-data-create-full">
                                        When `diff` query parameter is set to `true` and the event has `thing_created` type,
                                        the server MAY return the whole TD object as event data.</span>
                                    
                                    <aside class="example" id="example-create-event-full" title="Full creation SSE event for a TD">
                                        <pre>
                                            event: thing_created
                                            data: {
                                            data:     "@context": [
                                            data:         "https://www.w3.org/2022/wot/td/v1.1",
                                            data:         "https://www.w3.org/2022/wot/discovery"
                                            data:     ],
                                            data:     "description": "This is a new TD",
                                            data:     "id": "urn:example:simple-td",
                                            data:     "security": "basic_sc",
                                            data:     "securityDefinitions": {
                                            data:         "basic_sc": {
                                            data:             "scheme": "basic"
                                            data:         }
                                            data:     },
                                            data:     "registration": {
                                            data:         "created": "2021-01-19T17:02:00Z",
                                            data:         "modified": "2021-01-19T17:02:00Z"
                                            data:     },
                                            data:     "title": "Simple TD"
                                            data: }
                                            id: event_1
                                        </pre>
                                    </aside>
                                </li>
                                <li>
                                    <span class="rfc2119-assertion" id="tdd-notification-data-update-diff">
                                        When `diff` query parameter is set to `true` and the event has `thing_updated` type,
                                        the server MAY inform the client about the updated parts following the
                                        JSON Merge Patch [[RFC7396]] format.</span>
                                    <span class="rfc2119-assertion" id="tdd-notification-data-update-id">
                                        A `thing_updated` event data that is based on JSON Merge Patch [[RFC7396]]
                                        MUST always include the identifier of the TD regardless of whether it
                                        is changed.</span>

                                    <p>
                                        The following example shows the event triggered on update of the TD from [[[#example-create-event-full]]]:
                                        <aside class="example" id="example-update-event-full" 
                                            title="Full update SSE event for a TD with removed description and changed title">
                                            <pre>
                                                event: thing_updated
                                                data: {
                                                data:     "description": null,
                                                data:     "id": "urn:example:simple-td",
                                                data:     "title": "Updated TD"
                                                data: }
                                                id: event_3
                                            </pre>
                                        </aside>
                                    </p>
                                </li>
                                <li>
                                    <span class="rfc2119-assertion" id="tdd-notification-data-delete-diff">
                                        The `diff` query parameter MUST be ignored for `thing_deleted` events.</span>
                                    In other words, the server shall not include additional properties in
                                    the payload of `thing_deleted` events when `diff` is set to `true`. 
                                </li>
                                <li>
                                    <!-- span class="not-a-rfc2119-assertion" id="tdd-notification-data-diff-unsupported" -->
                                        When a server which does not support the `diff` query parameter 
                                        is requested with such query parameter, it should reject the request.
                                    <!-- span -->
                                    This is to inform clients about the lack of such functionality at 
                                    connection time and avoid runtime exceptions caused by missing
                                    event data attributes.
                                </li>
                            </ul>
                        </dd>
                    </dl>
                    <p>
                        The Notification API is specified as three event affordances in
                        [[[#directory-api-spec]]], namely:
                        `thingCreated`, `thingUpdated`, and `thingDeleted`.
                    </p>

                    <p class="note" title="SSE Authorization Header">
                        Some early SSE implementations (including HTML5 EventSource) do not allow
                        setting custom headers in the initial HTTP request. Authorization header 
                        is required in few OAuth2 flows and passing it as a query parameter is
                        <a href="https://datatracker.ietf.org/doc/html/rfc6750#section-2.3">not advised</a>.

                        There are polyfills for browsers and modern libraries which allow 
                        setting Authorization header.
                    </p>
                    

                </section>
                <section id="exploration-directory-api-search" class="normative">
                    <h4>Search API</h4>
                    
                    <p class="ednote" title="Search API Overview">
                        Sub-API to search a directory, e.g. issue a query.
                        There are different forms and levels of query possible, for example,
                        syntactic (JSONPath, XPath) vs. semantic (SPARQL), 
                        and the more advanced query types may not be 
                        supported by all directories.   
                        So this API will have further subsections,
                        some of which will be optional.
                        Search also includes a sub-API for managing listing the contents (e.g. returned by
                        a query) including handling pagination, etc.
                        Note that one special form of query will be able to return everything.
                        Results may be subject to the requestor's authorization.
                        <br>
                        To discuss further:
                        Federated queries to other TDDs, Spatial and network-limited queries, Links
                    </p>
                    This specification describes three search APIs: syntactic search with JSONPath [[?RFC9535]],
                    syntactic search with XPath [[xpath-31]], and semantic search with SPARQL [[sparql11-overview]].
                    <span class="rfc2119-assertion" id="tdd-search-sparql">
                        The Directory MAY implement semantic search with SPARQL.</span>
                    JSONPath and XPath are informative and subject to change.
                    <p>
                        <span class="rfc2119-assertion" id="tdd-search-large-tdds">
                            It is RECOMMENDED that directories implement a search API
                            to efficiently serve <a>TDs</a> based on client-specific queries.</span>
                    </p>

                    <section id="jsonpath-semantic" class="informative">
                        <h4>Syntactic search: JSONPath</h4>
<!-- Defer
                        <div class="issue" data-number="234">
                            The standardization of JSONPath expressions is in progress by an independent working group.
                            This section remains non-normative until the release of final
                            JSONPath specification by IETF.
                            In the meantime, clients should consider the JSONPath API
                            as unstable and expect deviations across
                            <a>Thing Description Directory</a> implementations.
                        </div>
-->
                        Support for JSONPath Search API is optional.
                        If implemented, the JSONPath API must allow searching TDs using an HTTP <code>GET</code> request
                        at `/search/jsonpath?query={query}` endpoint, where `query` is the JSONPath expression.
                        The request must contain a valid JSONPath [[?RFC9535]] as searching parameter.
                        A successful response must have 200 (OK) status, contain
                        <code>application/json</code> in the Content-Type header, and
                        a set of complete TDs or a set of TD fragments in the body.
                        The syntactic search with JSONPath is specified as `searchJSONPath` action in
                        [[[#directory-api-spec]]].

                    </section>
                    <section id="xpath-semantic" class="informative">
                        <h4>Syntactic search: XPath</h4>
                        Support for XPath Search API is optional.
                        If implemented, the XPath query API must allow searching TDs using an
                        HTTP <code>GET</code> request
                        at `/search/xpath?query={query}` endpoint, where `query` is the XPath expression.
                        The request must contain a valid XPath 3.1 [[xpath-31]] as search parameter.
                        A successful response must have 200 (OK) status, contain
                        <code>application/json</code> in the Content-Type header, and
                        the query response in JSON serialization in the body.  The data schema for the response is defined implicitly by the query and the XPath specification.
                        
                        The syntactic search with XPath is specified as `searchXPath` action in
                        [[[#directory-api-spec]]].
                    
                    </section>
                    <section id="search-semantic" class="normative">
                        <h4>Semantic search: SPARQL</h4>
                        Support for SPARQL Search API is optional.
                        <span class="rfc2119-assertion" id="tdd-search-sparql-version">
                            If implemented, the SPARQL search API MUST allow searching TDs using
                            the SPARQL 1.1 protocol [[sparql11-overview]].</span>
                        <span class="rfc2119-assertion" id="tdd-search-sparql-method-get">
                            The SPARQL API MUST accept queries using HTTP <code>GET</code> requests
                            at `/search/sparql?query={query}` endpoint, where `query` is the SPARQL expression.</span>
                        <span class="rfc2119-assertion" id="tdd-search-sparql-method-post">
                            The support for SPARQL search using HTTP <code>POST</code> method
                            at `/search/sparql` endpoint is OPTIONAL.</span>
                        <span class="rfc2119-assertion" id="tdd-search-sparql-resp-select-ask">
                            A successful request with a query <code>SELECT</code> or <code>ASK</code> MUST return a response 200 (OK) status, and contain <code>application/json</code> by default in the Content-Type header.</span>
			            <span class="rfc2119-assertion" id="tdd-search-sparql-resp-describe-construct">
                            A successful request with a query <code>CONSTRUCT</code> and <code>DESCRIBE</code> MUST return a response 200 (OK) status, and contain <code>application/ld+json</code> by default in the Content-Type header.</span>
                        <span class="rfc2119-assertion" id="tdd-search-sparql-error">
                            A request with any query different from <code>SELECT</code>, <code>ASK</code>, <code>CONSTRUCT</code> or <code>DESCRIBE</code> MUST return a response 400 (Bad Request).</span>
                        The semantic search with SPARQL is specified as `searchSPARQL` action in
                        [[[#directory-api-spec]]].
                        
                        <span class="rfc2119-assertion" id="tdd-search-sparql-federation">
                            A WoT Thing Description Directory MAY implement federation in its SPARQL query API.</span>
                        <span class="rfc2119-assertion" id="tdd-search-sparql-federation-version">
                            If implemented, the SPARQL API MUST implement the
                            SPARQL 1.1 Federated Query standard [[sparql11-overview]].</span>
                    </section>
                </section>

                <section id="directory-api-spec">
                    <h4>API Specification (Thing Model)</h1>
                    <p>
                    A template for the API of Thing Description Directories is given here
                    as a <a>Thing Model</a>.
                    The Thing Model is normative (except where noted) but should not be considered 
                    as the sole reference to implement or interact with a Thing Description Directory.
                    Please refer also to the specifications given 
                    in [[[#exploration-directory-api]]].
                    </p>
                    <p>
                    The <code>searchJSONPath</code> and <code>searchXPath</code> affordances 
                    given in this Thing Model
                    are not normative and are provided for information only.
                    </p>
                    <p>
                        Note that a <code>contentType</code> is required by the WoT TD 1.1
                        specification [[wot-thing-description11]] for instances of the
                        <code>ExpectedResponse</code> class (i.e., the JSON object
                        corresponding to the key <code>response</code> in a form),
                        even when the body of the HTTP response is supposed to be empty.
                        In this case, <code>application/x-empty</code> can be used to
                        ensure that the TD generated from the TM below is valid.
                    </p>
                    <pre class="advisement json"
                         data-include='directory.tm.json'></pre>

<!-- Defer
                    <p class="issue" data-number="82">
                        Need to confirm if equivalent OpenAPI spec can be easily created out of the TM.
                        If yes, a sentence may be added indicating this possibility.
                    </p>
-->
                </section>
            </section>
	    <!--
            <section id="exploration-directory-security" class="normative">
                <h3>Security and Privacy</h3>
                <p class="ednote" title="Security Considerations Overview">
                    Minimum security and privacy requirements for confidentiality, authentication, access control, etc.
                </p>
            </section>
	    -->
        </section>
    </section>

    <section id="security-considerations">
        <h1>Security Considerations</h1>
	<p>
            Security is a cross-cutting issue that needs to be considered
            in all WoT building blocks and WoT implementations. 
	    This chapter summarizes some general issues and guidelines to help
            preserve the security of concrete WoT discovery implementations.
            For a more detailed and complete analysis of both security and
            privacy issues, see the <em>WoT Security and Privacy Guidelines</em>
            specification [[?WOT-SECURITY]].
	    WoT Thing and WoT TDDs are also web services and should be
	    implemented using best practices for web services.
	    In addition to the specific security considerations below,
	    the security risks and mitigations discussed in
	    guides such as the OWASP Top 10 [[OWASP-Top-10]] should be
	    evaluated, and if applicable, addressed.
        </p>
        <section id="security-consideration-dos">
            <h2>Denial of Service</h2>
            <p>
                Certain functions of the directory service,
                in particular search queries,
                may require significant resources to execute and this fact
                can be used to launch denial of service (DoS) attacks against
                WoT Thing Description Directory services.
		In such an attack a WoT Directory would be overloaded
		by requests from the attacker and unable to service other
		requests.
	    </p>
                <dl>
                    <dt>Mitigations:</dt><dd>
                    <ul>
                    <li>
	            <!-- span class="not-a-rfc2119-assertion" id="sec-tdd-throttle-queries" -->
                    A WoT Thing Description Directory implementation should
                    limit the number of queries per unit time from the same requestor.
              <!-- /span -->
		    </li>
                    <li>
	            <!-- span class="not-a-rfc2119-assertion" id="sec-tdd-limit-query-complexity" -->
                    A WoT Thing Description Directory implementation should
		            limit the complexity of queries (for example, the total length of the query 
                    expression or its depth).
              <!-- /span -->
		    </li>
                    <li>
	            <!-- span class="not-a-rfc2119-assertion" id="sec-tdd-query-watchdog" -->
                    A WoT Thing Description Directory implementation should
	                use a watchdog timer to abort queries that take more than
                    a certain maximum (implementation-configurable) amount of time.
              <!-- /span -->
		    </li> 
                    </ul>
                    </dd>
                </dl>
	</section>
        <section id="security-consideration-amp-ddos">
            <h2>Amplification and Distributed Denial of Service</h2>
            <p>
	    It may also be possible to use elements of WoT Discovery
	    mechanisms to launch distributed denial of service (DDoS) attacks
	    against other targets.  In such an attack the WoT Discovery
	    service itself is not the target.  Instead, an aspect of
	    the WoT Discovery service would be
	    exploited to generate amplified network traffic that overloads a third
	    party, the actual target.
	    Such an attack has two requirements: first, the ability
	    to redirect traffic to a third party, and second, 
	    an intermediary service
	    that can be exploited to amplify network traffic
	    from the attacker.
	    Redirection
	    of network traffic is possible in some protocols, such as 
	    unsecured CoAP, by modifying source information in headers.
	    Amplification is possible by taking advantage of three 
	    multiplicative factors: the ratio of request to response payload
	    sizes, use of "observe" in protocols like CoAP  
	    (which can give multiple results for one request), and use of
	    multicast (which can allow multiple servers to respond to one 
	    request). 
	    Services which do not support authentication
	    are ideal intermediaries for such an indirect attack.
	    Unfortunately, the Introduction mechanisms for WoT Discovery
	    are meant to provide open access mechanisms to initiate discovery
	    and might be exploited for this purpose.
            </p>
            <dl>
                <dt>Mitigations:</dt>
                <dd>
		<ul>
		<li>
	        <span class="rfc2119-assertion" id="sec-tdd-intro-no-observe">
                Open implementations of Introduction mechanisms SHOULD NOT
		support observe or similar extended result subprotocols.</span>
		</li>
		<li>
	  <!-- span class="not-a-rfc2119-assertion" id="sec-tdd-intro-no-multicast" -->
		Open implementations of Introduction mechanisms should not respond to multicast
		requests unless this is absolutely required by the protocol.<!-- /span -->
		If support for multicast is required,
		in the case of CoAP, the observations made in [[AMPLIFICATION-ATTACKS]] are relevant,
		since the number of servers that might respond to a multicast request during
		discovery will generally not be known in advance.
		</li>
		<li>
		Limit the size of responses to the minimum.  
	  <!-- span class="not-a-rfc2119-assertion" id="sec-tdd-intro-limit-response-size" -->
		The total size of responses to an Introduction on the public internet (outside
    of a protected local network) should
		be less than 3x the size of the total size of request, and this should 
		include any error responses.<!-- /span -->
		This is consistent with DDOS mitigations in [[RFC9000]] (QUIC) and HTTP/3.
		Here "total size" includes any headers required by the protocol itself,
    as well as padding in the request to allow for a larger response.
		</li>
		<li>
	  <!-- span class="not-a-rfc2119-assertion" id="sec-tdd-intro-throttling" -->
		Introductions should rate-limit responses to any particular
		request source.<!-- /span -->
		</li>
		<li>
	        <span class="rfc2119-assertion" id="sec-tdd-intro-no-ext">
		Introduction mechanisms on a segmented network behind a firewall
		(e.g. a LAN) SHOULD NOT respond to requests that are (apparently) from outside that LAN.</span>
		</li>
	        </ul>
		Of particular concern are Introduction mechanisms that can
		return multiple results, such as CoRE-RD and DID.
		It may be necessary to use authentication/authorization on such
		Introduction mechanisms
		as well if the other mitigations above are not sufficient.
		A recommended alternative is to move multiple results from such
		Introductions into a WoT TDD, which can then be protected
		by appropriate authentication and authorization measures.
		Then the open Introduction mechanism only has to return one
		result, the URL of the TDD.
		Introduction mechanisms that are visible on the open internet
		should be especially careful to implement the above mitigations,
		and perhaps avoid Introduction
		mechanisms that can return multiple URLs completely.
                </dd>
            </dl>
        </section>
        <section id="security-consideration-lan-self-discovery">
        <h2>Self-Discovery on LANs</h2>
            <p>
            On a LAN, 
	    certificates and browsers may not be able to property set up TLS for 
	    HTTPS because browsers expect
            certificates pointing to a publicly-visible URL.
            Using HTTP is common practice inside LANs but in combination with 
	    self-description it means that WoT Things
            would be essentially be making TDs visible to everyone
	    with access to the private LAN.  Even if security mechanisms
	    such as HTTP passwords were used, these are not effective (they
	    can be easily discovered by a traffic analyser) without
	    transport security.
            </p>
            <dl>
                <dt>Mitigations:</dt>
                <dd>
		<p>
	        <span class="rfc2119-assertion" id="sec-self-psk">
                PSK (pre-shared keys) SHOULD be used if possible on LANs, 
		meaning one of the ciphersuites in [[RFC4279]].</span>
                This does require that Things are assigned PSKs in a common security domain, 
		which is typically done by following an onboarding process.  
		Unfortunately, specific onboarding processes 
		are currently out of scope of the WoT specifications.
		</p>
		<p>
		An alternative is to depend on local network security (i.e. WEP).
		This is not the best solution from a security or privacy point of
		view but may be acceptable in some contexts.  Note however that
		all users with access to the network would in turn have access to 
		all TDs via self-description.  
	        <span class="rfc2119-assertion" id="sec-self-segment">
		If Things cannot be individually secured with transport security and 
		authentication and authorization,
		a separate network SHOULD be set up, i.e. with an alternative SSID, and used only
		for IoT devices.</span>
		Using a segmented network reduces the need for distributing the password
                to this network to those who need access to the set of IoT devices connected to it.
		</p>
		<p>
		Another alternative is to use a reverse proxy service based in the cloud.
		Secure setup can
		be accomplished if the IoT device has access to the cloud, since
		the proxy server can have a public URL and the initial connection
		can use HTTPS, then open a secure tunnel over a websocket.  The proxy can in turn
		re-expose a secure endpoint, and possible add authentication.
		The disadvantages of this approach including depending on an external
		cloud service and the need to expose an external access point (which is
		itself a security risk).  The first disadvantage can be addressed by hosting
		the proxy service locally 
		and exposing a public URL using e.g. dynamic DNS if the
		local server is connected through an ISP.
	  <!-- span class="not-a-rfc2119-assertion" id="sec-self-proxy" -->
		If Things cannot be individually secured with transport security and 
		authentication and authorization,
                then they may be made available for general access via a proxy
		that can provide suitable access controls.<!-- /span -->
                </dd>
            </dl>
        </section>
    </section>
    <section id="privacy-considerations">
        <h1>Privacy Considerations</h1>
        <p>
            Privacy is a cross-cutting issue that needs to be considered
            in all WoT building blocks and WoT implementations. 
	    This chapter summarizes some general issues and guidelines to help
            preserve the privacy of concrete WoT discovery implementations.
            For a more detailed and complete analysis of both security and
            privacy issues, see the <em>WoT Security and Privacy Guidelines</em>
            specification [[?WOT-SECURITY]].
        </p>
        <p>
            The WoT discovery architecture is designed to avoid a dependence on the 
            privacy of existing discovery schemes by using a two-phase approach and
            allowing for the enforcement of authorization before metadata release.  
	    However several privacy risks still exist.  
	    These are listed below along with possible mitigations.
            The level of risk to privacy in particular depends on the use case and whether
            there is a risk that information related to a person might be distributed in
            a fashion inconsistent with the privacy desires of that person. 
            For privacy we distinguish the following broad classes of use case scenarios:
        </p>
        <dl>
            <dt>Institutional</dt>
            <dd>Both the Things producing metadata and 
            the Consumers of that metadata are owned and controlled by an institution or 
            representatives of an institution.  Example: Automation in a factory where
            a control system is accessing the state of an assembly line in order to
            evaluate quality.
            </dd>
            <dt>Service</dt><dd>The Things producing metadata  
            are owned and controlled by an institution or representatives of an institution
            while the consumers are individuals.  Example: driver of an electric vehicle 
            accessing the TD for a charge station in order to check status of a charge.
            </dd>
            <dt>Personal</dt><dd>Both the Things producing metadata and 
            the Consumers of that metadata are owned and controlled by the same individual.
            Example: A smart home control system for charging an electric car from
            home-attached solar panels, both home and car owned by the same person.
            </dd>
            <dt>Personal Peer-to-Peer</dt><dd>The Things producing metadata and 
            the Consumers of that metadata are owned and controlled by different individuals.
            Example: A smart home control system for charging a guest's electric car from
            home-attached solar panels.
            </dd>
            <dt>Institutional Peer-to-Peer</dt><dd>The Things producing metadata and 
            the Consumers of that metadata are owned and controlled by different institutions.
            Example: A utility provides and manages power delivered to a factory, and
            the factory provides an interface for the utility to negotiate on-demand power
            usage reductions.
            </dd>
            <dt>Client</dt><dd>The Things producing metadata  
            are owned and controlled by an individual
            while the consumers are an institution or representatives of an institution.
            Example: A personal electric vehicle exposes an interface to a public charging station 
            so that the charging station can evaluate the charge status of the vehicle.
            </dd>
        </dl>
        <p>
            All of these in fact carry privacy risks.  Even in the case of factory
            automation, there is the chance that data about employee performance would
            be captured and would have to be managed appropriately.
        </p>
        <p>
            In the following we make frequent reference to "tracking".  This term covers
            multiple privacy risks, including location tracking and behavioral profiling.
            In general, the definition of "profiling" given in Article 4 of the 
            GDPR [[GDPR-Defs]] is to be considered equivalent to "tracking" as used in this document.
        </p>
        <p>
            With these definitions and categories established, we will now discuss some specific
            privacy risks and potential mitigations.
        </p>
        <section id="privacy-consideration-location-tracking">
            <h2>Location Tracking and Profiling</h2>
            <p>
                A discovery service may potentially allow the approximate location of a person to be determined without
                their consent.  This risk occurs in some specific circumstances which can be avoided or
                mitigated.  It is also similar to the risk posed by other network services such as DHCP and DNS.
            </p>
            <p>
                For this risk to occur, there first has to be an IoT device that can be reliably associated
                with a person's location, such as a necessary medical device or a vehicle.  
                Note that the risk only applies to personal use cases, not institutional ones.
                Secondly, the
                device has to be configured to register automatically with the nearest directory service.
                In this case, the location of the device can be inferred from the network range of the directory
                service and the location of the person inferred from the location of the device.
            </p>
            <p>
                There are a few variants of this: 
                </p>
                <ul>
                <li>The TD or Thing could report actual location information so no inferencing by network range is needed;</li>
                <li>A directory could support actual search by location;</li>
                <li>Absence of a TD in a directory could reveal negative location information.
		For example, if a TD
                    times out and is removed from a directory, that means the device has not been present for
                    a while, which could be used to infer that a person is NOT in a particular location, e.g. not at
                    home.</li>
                </ul>
            <p>
            Location tracking is not the only profiling risk.
            In general, "profiling" includes any mechanism used to evaluate
            information about a person, including economic status, health,
            preferences, interests, reliability, and behavior.
            Some of the metadata in a TD can be used to infer information
            of this kind if the described Thing can be associated with a person.
            Some of the mitigations below are also applicable to this more
            general definition of profiling.
            </p>
            <p>
                Some of these risks are shared by similar services.  For example, DCHP automatically responds to 
                requests for IP addresses on a local network, and devices typically provide an identifier (a MAC
                address) as part of this process, and the DHCP server maintains a registry. In theory, someone with
                access to the DHCP server in, say, a cafe, could use this information to track someone's phone and
                infer their location.
            </p>
            <dl>
                <dt>Mitigations:</dt>
                <dd>
                There are a few options to mitigate these risks:
                <ul>
                <li>
	        <!-- span class="not-a-rfc2119-assertion" id="priv-loc-disable-public-directories" -->
		To avoid location tracking and other forms of profiling, 
    a WoT Thing associated with a person may 
		disable registration with public directories.<!-- /span -->
		Registration would still be possible with 
                personal directories, for example, a home gateway, but a user could disable registration at other
                locations.  This has the disadvantage that functionality is lost: personal devices cannot be
                discovered in public locations.  This could be addressed by having internet-accessible private
                discovery services. For example, the user's home gateway could provide an internet-accessible service, but with
                access control limiting use to authorized users.</li>
		<li>
	  <!-- span class="not-a-rfc2119-assertion" id="priv-loc-anonymous-tds" -->
		To avoid location tracking and other forms of profiling,
    a WoT Thing associated with a person should use anonymous TDs
    when registering with a public directories.<!-- /span -->
		In some cases, it may be possible to use
		anonymous TDs and omit explicit IDs from TDs submitted to
		a TDD.  In this case the TDD will generate a local ID valid
		only in that TDD.  This does, however, complicate update since the client needs to
		remember the local ID assigned by the TDD.  
		Anonymous TDs also do not prevent tracking by other means, such as 
		fingerprinting.
		</li>
                <li>
	  <!-- span class="not-a-rfc2119-assertion" id="priv-loc-gen-ids" -->
		To avoid location tracking and other forms of profiling, 
    a WoT Thing associated with a person may 
		periodically generate new IDs.<!-- /span -->
		Using fixed IDs makes it exceptionally easy to track devices.  This problem
                also occurs in DHCP with MAC address and there is a similar partial mitigation: 
                generate new random IDs periodically.
                There are however, a few issues.  First of all, other identification information in the TD needs to be 
                hidden.  For example, client IDs issued by CSPs for API security should be omitted from TDs if 
                they cannot be easily changed.  Second, if the device generates a new ID, the user may still need to 
                know the current ID to find the device via discovery.  This can be accomplished however by generating new
                IDs using a deterministic cryptographic generator that is a function of the current time.
                However, note that regenerating IDs alone does not make tracking impossible since a TD might be fingerprinted.
                Also, updating an ID might be observable to the owner of the directory service, who could track
                and record the updated ID.  Even if the TD is deleted and reinserted the association could be 
                inferred.  This is however exactly parallel to the situation with DHCP and rotation of MAC addresses.
                In general, however, generating new IDs at least for each service or person to which a TD is supplied
                makes it harder to connect registration events at different locations and times.
It is also prudent to generate new identifiers upon major changes in configuration,
such as unregistering from a local network or hub and registering with a new one (which typically indicates
a change in ownership).
	        There is a related issue with long-lived IP addresses which might need to be updated periodically
		to mitigate tracking.  In the context of ipv6 [[RFC8981]] discusses this.
          Finally, there is a problem with devices that require immutable identifiers,
          e.g. medical devices in such jurisdictions.  
          This is discussed in [[wot-thing-description11]], but in summary the
          problem can be avoided if such immutable identifiers are made available
          only as protected properties, e.g. via affordances requiring authentication,
          not in the TD, and the TD identifier itself (if used) is
          independent of the immutable identifier, and so can be made mutable.
                </li>
                <li>
	        <span class="rfc2119-assertion" id="priv-loc-priv-dir-access">
		To reduce the risk of negative location inferencing, access to 
                private directories SHOULD be limited by using access controls.</span>
		If an attacker cannot access the service,
                they cannot retrieve information to infer location.  
		Access rights provided to guests (e.g. for Peer-to-Peer Personal scenarios)
                should be appropriately time-limited.
                Use of long time-to-live values may be appropriate in other cases.  
		In addition, TDs should be updated in a 
                directory only when they change.  
		For example, the TD for a car may only be updated when new car firmware is available
                providing new services, and the time-to-live might be set at one month (covering most absences).
                </li>
                <li>
	        <span class="rfc2119-assertion" id="priv-loc-explicit-care">
		When explicit location information is available, whether stored in a TD or available in a property,
                additional care SHOULD be taken to only share the TD and/or access to the device with trusted partners,
                including directories.</span>
	  <!-- span class="not-a-rfc2119-assertion" id="priv-loc-explicit-strip" -->
		If the TD must be shared with a public directory, the location information may be
                stripped.<!-- /span -->
                </ul>
                </dd>
            </dl>
        </section>
        <section id="privacy-consideration-query-tracking">
            <h2>Query Tracking</h2>
            <p>
            A directory service could potentially record and track queries by an individual,
            identifying that individual by their authenticated identity provided.
	    Then the set of queries associated with an individual could be used to 
	    profile that individual, and specific queries may also reveal personal information
	    about an individual.
            </p>
            <dl>
                <dt>Mitigations:</dt>
                <dd><p>
	        <!-- span class="not-a-rfc2119-assertion" id="priv-query-anon" -->
                When accessing a public directory, like any other public web service,
                users and implementations should use an anonymous identity provider.<!-- /span -->
                In particular, OAuth2 can provide tokens which don't identify specific individuals,
                they just assert access rights proven elsewhere.
                </p></dd>
            </dl>
        </section>

    </section>

    <section id="performance-considerations" class="informative">
        <h1>Performance Considerations</h1>
        
        <section id="perf-incremental-transfer">
            <h2>Incremental Transfer</h2>
	    <p>
            <a>TD</a> objects are not constrained in size. They may become 
            expensive to process and transfer individually or collectively.
            A single TD or a list of TDs could be too large for a constrained device,
            serving its own TD to consumers, submitting it to a directory,
            or consuming other TDs.

            To meet such requirements,
            servers should support incremental transfer of payloads 
            using protocol-specific mechanisms:
	    </p>
            <ul>
                <li>
		<!-- span class="not-a-rfc2119-assertion" id="perf-inc-chunked-1" -->
                HTTP/1.1 servers should support `chunked` 
                <a href="https://datatracker.ietf.org/doc/html/rfc7230#section-3.3.1">Transfer-Encoding</a> [[RFC7230]]
                to receive and server data incrementally.
		<!-- /span -->
                </li>
                <li>
		<!-- span class="not-a-rfc2119-assertion" id="perf-inc-chunked-2" -->
                HTTP/2 servers should handle the data incrementally using 
                <a href="https://datatracker.ietf.org/doc/html/rfc7540#section-4">HTTP Frames</a> [[RFC7540]].
                The HTTP/1.1 chunked transfer encoding is not supported in HTTP/2.
                <!-- /span -->
                </li>
                <li>
        <!-- span class="not-a-rfc2119-assertion" id="perf-inc-chunked-3" -->
                CoAP servers must suppoert block-wise transfer [[RFC7959]] when relying
                on an unreliable transport protocol like UDP and should support it when
                using a reliable transport protocol like TCP or WebSockets [[RFC8323]].
               <!-- /span -->
                </li>
            </ul>
            <p> 
            Most HTTP servers and clients automatically process the data that is transferred 
            in chunks.
            Memory-constrained clients should consider consuming the
            received data incrementally, instead of trying to load a whole
            object in memory for de-serialization. 
	    </p>
        </section>
    </section>

    <section id="iana-considerations" class="normative">
        <h1>IANA Considerations</h1>
        <section id="well-known-uri-suffix">
            <h2>Well-Known URI Registration</h2>
            <p>
                IANA will be asked to allocate the following value into the Well-Known URI
                defined in [[RFC8615]].
            </p>
            <ul>
                <li>URI suffix: <code>wot</code></li>
            </ul>
        </section>
        <section id="service-name">
            <h2>Service Name Registration</h2>
            <p>
                IANA will be asked to allocate the following value into Service Name and Transport Protocol Port Number Registry
                defined in [[RFC6335]].
            </p>
            <ul>
                <li>Service Name: <code>wot</code></li>
                <li>Transport Protocol: TCP, UDP</li>
                <li>Description: Service name to search for the Thing Description of a Thing or a Thing Description Directory in the W3C Web of Things</li>
                <li>Port Number: N/A</li>
                <li>Assignment notes: We use <code>_directory</code> subtype for a Thing Description Directory.</li>
            </ul>
        </section>
        <section id="core-resource-type">
            <h2>CoRE Resource Types Registration</h2>
            <p>
                IANA will be asked to allocate the following values into the Resource Type (<code>rt=</code>)
                Link Target Attribute Values sub-registry of the Constrained Restful Environments (CoRE)
                Parameters registry defined in [[RFC6690]].
            </p>
            <table class="def">
                <thead>
                    <tr>
                        <th>Value</th>
                        <th>Description</th>
                        <th>Reference</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td><code>wot.thing</code></td>
                        <td>Thing Description of a Thing</td>
                        <td>[[[#introduction-core-rd-sec]]]</td>
                    </tr>
                    <tr>
                        <td><code>wot.directory</code></td>
                        <td>Thing Description of a <a>Thing Description Directory</a></td>
                        <td>[[[#introduction-core-rd-sec]]]</td>
                    </tr>
                </tbody>
            </table>

        </section>
    </section>
    <section id="other-name-considerations" class="normative">
        <h1>Other Name Registration Considerations</h1>
        <section id="did-service-name">
            <h2>DID Service Name Registration</h2>
            <p>
                The following values will be allocated for the Service Type 
                used in DID Documents.
            </p>
            <table class="def">
                <thead>
                    <tr>
                        <th>Value</th>
                        <th>Description</th>
                        <th>Reference</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td><code>WotThing</code></td>
                        <td>Thing Description of a Thing</td>
                        <td>[[[#introduction-did-sec]]]</td>
                    </tr>
                    <tr>
                        <td><code>WotDirectory</code></td>
                        <td>Thing Description of a <a>Thing Description Directory</a></td>
                        <td>[[[#introduction-did-sec]]]</td>
                    </tr>
                </tbody>
            </table>

        </section>
    </section>

    <section id="tdd-extensions-jsonschema" class="appendix">
        <h1>JSON Schema for WoT Discovery TD-extensions</h1>
        The following JSON Schema specifies the extensions used in <a>Enriched TDs</a>.
        It can be used for validating <a>TDs</a> by a <a>TDD</a>
        as prescribed in [[[#exploration-directory-api-things-validation]]].
        <pre class="advisement json"
             data-include='validation/td-discovery-extensions-json-schema.json'></pre>
    </section>
    
    <section id="changes" class="appendix">
      <h1>Recent Specification Changes</h1>
      <h2 id="changes-from-pr">Changes from 11 July 2023 Proposed Recommendation</h2>
      <ul>
      <li>No normative changes from Proposed Recommendation.</li>
      <li>Add errata link.</li>
      <li>Update process link to 3 November 2023.</li>
      <li>Remove Editors' notes regarding date-time and Search API overview.</li>
      <li>Update references to DID registry and other WoT documents.</li>
      <li><a href="https://services.w3.org/htmldiff?doc1=https%3A%2F%2Fwww.w3.org%2FTR%2F2023%2FPR-wot-discovery-20230711%2F&doc2=https%3A%2F%2Fraw.githubusercontent.com%2Fw3c%2Fwot-discovery%2Fmain%2Fpublication%2F6-rec%2FOverview.html">HTML Diff</a></li>
      </ul>
      <h2 id="changes-from-cr">Changes from 19 January 2023 Candidate Recommendation</h2>
      <ul>
      <li>No normative changes from Candidate Recommendation.</li>
      <li>Add reference to IoT'16 paper by Arne Broering, Soumya Kanti Datta, and Christian Bonnet.</li>
      <li>At-risk assertions that did not receive sufficient implementations were removed or
          converted to informative statements.</li>
      <li><a href="https://services.w3.org/htmldiff?doc1=https%3A%2F%2Fwww.w3.org%2FTR%2F2023%2FCR-wot-discovery-20230119%2F&doc2=https%3A%2F%2Fraw.githubusercontent.com%2Fw3c%2Fwot-discovery%2Fpr-candidate%2Fstatic.html">HTML Diff</a></li>
<!--
      <li>Clarify response codes for security bootstrapping and resolve at-risk assertion exploration-secboot-oauth2-flows.</li>
      <li>Resolve at-risk assertion exploration-server-http-alternate-language - changed to informative statement.</li>
      <li>Remove at-risk assertions tdd-things-list-pagination-order and tdd-things-list-pagination-orderable, due to 
          ambiguity in testing results.</li>
      <li>Security and Privacy assertions 
              priv-loc-disable-public-directories, 
              priv-loc-anonymous-tds,
              priv-loc-gen-ids,
              priv-loc-explicit-strip,
              priv-query-anon,
              sec-tdd-query-watchdog,
              sec-tdd-intro-no-multicast,
              sec-self-proxy,
              sec-tdd-throttle-queries,
              sec-tdd-limit-query-complexity,
              sec-tdd-intro-limit-response-size, and
              sec-tdd-intro-throttling
          converted to informative statements.
       </li>
       <li>Resolve at-risk assertion tdd-notification-data-diff-unsupported - changed to informative statement.</li>
       <li>Resolve at-risk assertions tdd-http-alternate-language and tdd-validation-response-lang - changed to informative statements.</li>
       <li>Resolve at-risk assertion tdd-registrationinfo-expiry-config - changed to informative statement.</li>
-->
      </ul>
      <h2 id="changes-from-third-draft">Changes from 10 August 2022 Working Draft</h2>
      <ul>
      <li>Define sorting order to be based on Unicode code points.</li>
      <li>Clarify 3x rule for DDoS migitation to allow padding in request, and require it only outside of protected local networks.</li>
      <li>Define content types to be used for CoAP servers, paralleling TD servers.</li>
      <li>Update DID service names and refine DID assertions and add examples to clarify use for Introductions.</li>
      <li>Update DNS-SD section to include explicit scheme in TXT field.</li>
      <li>Replace reference to draft CoRE-RD with final specification published as RFC9176.</li>
      </ul>
      <h2 id="changes-from-second-draft">Changes from 2 June 2021 Working Draft</h2>
      <ul>
      <li>Use <code>wot</code> for well-known URI service name.</li>
      <li>Refer to TD and Architecture specs for general constraints on secure transport.</li>
      <li>Define requirements for CoAP-based TD Servers.</li>
      <li>Introduction of TD Server exploration, with self-description as a special case.</li>
      <li>Elaboration of class diagram to clarify that not all Directories need to be self-describing.</li>
      <li>Clarify and consolidate error codes and ontology.</li>
      <li>Add assertions for UTF-8 supporting internationalization.</li>
      <li>Update overview figure showing introduction and exploration mechanisms.</li>
      <li>Add Discoverer section defining requirements for discovery clients.</li>
      <li>Use Thing Model instead of a Thing Description example for Directory API.</li>
      <li>Refactor Directory Service API (td->thing, split anonymous create action, retrieve one and search as actions, listing as things property, split events)</li>
      <li>Add amplification DDOS security consideration.</li>
      <li>Split Security and Privacy Considerations into separate sections.</li>
      <li>Define status of search mechanisms: JSON Path, XPath, and SPARQL.</li>
      <li>Pagination as array and pagination as collection.</li> 
      <li>Updates to events API.</li>
      <li>TD expiry management.</li>
      <li>HEAD method support.</li>
      </ul>
      <h2 id="changes-from-first-draft">Changes from 24 November 2020 First Public Working Draft</h2>
      <ul>
      <li>Update name of directory service to "Thing Description Directory" with acronym TDD, 
      to avoid confusion with the acronym TD used for Thing Descriptions.
      </li>
      <li>Elaboration of complete API for registration of a Thing Description with a 
      Thing Description Directory, 
      including support for creation, update, retrieval, deletion, and listing.
      </li>
      <li>Add recommendation that TDs be validated before storage in a directory.
      Note: this corresponds to work under way in the TD spec to precisely define
      appropriate levels of automatic validation for different contexts, including
      directory registration.
      </li>
      <li>Addition of Security and Privacy Considerations 
      regarding Denial of Service and Location Tracking.
      </li>
      <li>Addition of IANA Considerations regarding CoRE Resource Types.
      </li>
      <li>Definition of Enriched TD to support embedded metadata in TDs returned by a TDD.
      </li>
      <li>Updates to description of exploration to avoid unnecessary dependence 
      on HTTP (in the future, other protocols may be supported).
      </li>
      <li>Use of "resource type" instead of "endpoint type" when describing entry in CoRE RD.
      </li>
      <li>Addition of ontology for TDDs that include the type <code>DirectoryDescription</code>
      identifying TDs of directories and 
      a type <code>LinkDescription</code> to identify a TD that is just a link to another 
      TD (useful for referring to remote directories in order to support federation).
      </li>
      <li>Add section for self-description exploration mechanism. 
      This supports the use case where a Thing hosts its own TD and peer-to-peer Thing
      communication.
      </li>
      <li>Addition of diagram showing the directory information model.
      </li>
      <li>Removal of reference to Issue 16, citing CRUD interface requirements.
      Replaced with CRUDL (CRUD + Listing) interface requirement.
      </li>
      <li>MAY assertion added to explicitly permit implementation of SPARQL federation, 
      and a requirement that if implemented, it needs to follow the SPARQL 1.1 specification.
      </li>
      <li>Updates to references: more recent versions of CoRE RD, DID Core, Eventsource, JSON-LD, 
      and JSON Path specifications. 
      Use of datatracker service (and URLs) to reference IETF RFCs. 
      Addition of normative references to RFC7396 and RFC7540.
      </li>
      </ul>
    </section>

    <section id="acknowledgements" class="appendix normative">
        <h1>Acknowledgments</h1>
        <p>Special thanks to Arne Broering, Soumya Kanti Datta, and Christian Bonnet
           for their survey work on existing discovery mechannisms in IoT.
           Special thanks to 
             Philipp Blum, 
             Victor Charpeney,
             Ben Francis, 
             Christian Glomb, 
             Daniel Peintner, 
             Christine Perey, 
             Jan Romann, 
             and
             Elodie Thieblin 
           for their contributions to this document.
        </p>
        <p>
            Many thanks to the W3C staff,
            especially
		Kazuyuki Ashimura
                and
                Dominique Hazael-Massieux,
	    and all other active Participants of the W3C Web
            of Things Interest Group (WoT IG) and Working Group (WoT WG) for their
            support, technical input and suggestions that led to improvements to
            this document.
        </p>
    </section>
</body>
</html>