+
+
+Communication
+metadata
+describing
+
+The
+Things
+API
+is
+a
+RESTful
+HTTP
+API
+served
+at
+
+the
+expected
+response
+message
+for
+additional
+responses.
+Vocabulary
+term
+Description
+Assignment
+Type
+
+
+success
+
+/things
+
+
+Signals
+if
+an
+additional
+response
+should
+not
+be
+considered
+an
+error.
+
+endpoint
+providing
+interfaces
+to
+create,
+retrieve,
+update,
+delete,
+and
+list
+(CRUDL)
+
+TDs
+.
+The
+design
+of
+this
+API
+is
+in
+accordance
+
+with
+default
+boolean
+
+[
+
+
+RFC7231
+
+
+contentType
+Assign
+a
+content
+type
+based
+on
+a
+media
+type
+(e.g.,
+text/plain
+)
+
+
+]
+
+and
+potential
+parameters
+(e.g.,
+charset=utf-8
+)
+for
+the
+media
+type
+
+[
+
+RFC2046
+
+
+REST-IOT
+
+
+
+].
+with
+default
+string
+schema
+Used
+to
+define
+the
+output
+data
+schema
+for
+an
+additional
+response
+if
+it
+differs
+from
+the
+default
+output
+data
+schema.
+Rather
+than
+a
+DataSchema
+object,
+the
+name
+of
+a
+previous
+definition
+given
+in
+a
+schemaDefinitions
+map
+must
+be
+used.
+optional
+string
+5.4
+Default
+Value
+Definitions
+
+
+
+The
+HTTP
+API
+follows
+these
+general
+rules:
+
-
+
When
+assignments
+in
+a
+TD
+are
+missing,
+a
+TD
+Processor
+
+
+The
+API
+
+
+MUST
+
+follow
+the
+Default
+Value
+assignments
+expressed
+in
+
+provide
+
+the
+table
+of
+Default
+Value
+Definitions
+.
+
+interface
+to
+list
+TDs.
+
+
+The
+following
+table
+gives
+all
+Default
+Values
+defined
+in
+the
+TD
+Information
+Model
+.
+Class
+Vocabulary
+Term
+Default
+Value
+Comment
+DataSchema
+readOnly
+false
+DataSchema
+writeOnly
+false
+PropertyAffordance
+observable
+false
+ActionAffordance
+safe
+false
+ActionAffordance
+idempotent
+false
+AdditionalExpectedResponse
+success
+false
+AdditionalExpectedResponse
+contentType
+value
+of
+the
+contentType
+of
+the
+Form
+element
+it
+belongs
+to.
+Form
+contentType
+application/json
+Form
+op
+
+Search
+API
+allows
+filtering
+and
+selection
+from
+this
+list;
+see
+
+
+7.3.2.3
+
+Search
+API
+. -
+
Array
+of
+string
+with
+
+
+The
+API
+
+MAY
+
+provide
+
+the
+elements
+readproperty
+
+interfaces
+to
+create,
+read,
+update,
+
+and
+writeproperty
+when
+readOnly
+
+delete
+(CRUD)
+individual
+TDs.
+ -
+A
+directory
+that
+provides
+both
+read
+
+and
+
writeOnly
+are
+set
+to
+false
+or
+Array
+of
+string
+with
+the
+element
+readproperty
+when
+readOnly
+
+write
+over
+HTTP
+
+is
+set
+to
+true
+or
+Array
+
+considered
+a
+full
+HTTP
+directory.
+
+Full
+HTTP
+directories
+
+SHOULD
+
+implement
+all
+
+of
+string
+with
+the
+element
+writeproperty
+when
+writeOnly
+
+CRUDL
+(create,
+read,
+update,
+delete,
+and
+list)
+interfaces.
+
+It
+
+is
+set
+
+practical
+
+to
+true
+.
+If
+defined
+within
+an
+instance
+of
+PropertyAffordance
+Form
+op
+invokeaction
+If
+defined
+within
+an
+instance
+of
+ActionAffordance
+Form
+op
+Array
+of
+string
+with
+
+implement
+only
+
+the
+elements
+subscribeevent
+
+interfaces
+to
+read
+
+and
+unsubscribeevent
+If
+defined
+within
+an
+instance
+
+list
+if
+the
+directory
+serves
+a
+static
+collection
+
+of
+EventAffordance
+BasicSecurityScheme
+in
+header
+DigestSecurityScheme
+in
+header
+DigestSecurityScheme
+qop
+auth
+APIKeySecurityScheme
+in
+query
+BearerSecurityScheme
+in
+header
+BearerSecurityScheme
+alg
+ES256
+BearerSecurityScheme
+format
+jwt
+6.
+TD
+Representation
+Format
+WoT
+Thing
+Descriptions
+represent
+Things
+and
+are
+modeled
+and
+structured
+based
+on
+5.
+TD
+Information
+Model
+
+
+TDs
+
+.
+This
+section
+defines
+a
+JSON-based
+representation
+format
+
+is
+also
+useful
+
+for
+Things
+,
+a
+serialization
+of
+instances
+of
+the
+Class
+Thing
+defined
+by
+the
+TD
+Information
+Model
+.
+A
+TD
+Processor
+MUST
+be
+able
+to
+serialize
+Thing
+Descriptions
+into
+the
+JSON
+format
+[
+RFC8259
+]
+and/or
+deserialize
+Thing
+Descriptions
+from
+
+directories
+
+that
+format,
+according
+
+intend
+
+to
+expose
+only
+retrieval
+operations
+over
+HTTP,
+and
+perform
+other
+operations
+via
+out-of-band
+mechanisms.
+
+To
+expose
+read-only
+access,
+
+the
+rules
+noted
+in
+6.1
+Mapping
+to
+JSON
+Types
+
+directory
+
+MUST
+
+enforce
+access
+control
+on
+create,
+update,
+
+and
+6.3
+Information
+Model
+Serialization
+.
+
+delete
+interfaces.
+
+
+
+-
+
+The
+
JSON
+
+default
+
+serialization
+of
+the
+TD
+Information
+Model
+is
+aligned
+with
+the
+syntax
+of
+JSON-LD
+1.1
+[
+json-ld11
+]
+in
+order
+to
+streamline
+semantic
+evaluation.
+Hence,
+the
+TD
+representation
+
+format
+can
+be
+processed
+either
+as
+raw
+JSON
+or
+with
+a
+JSON-LD
+1.1
+processor
+(for
+details
+about
+semantic
+processing,
+please
+refer
+to
+C.
+JSON-LD
+Context
+Usage
+
+for
+all
+request
+
+and
+the
+documentation
+under
+the
+namespace
+IRIs,
+e.g.,
+https://www.w3.org/2019/wot/td
+).
+In
+order
+to
+support
+interoperable
+internationalization,
+TDs
+
+success
+response
+bodies
+
+
+MUST
+
+be
+serialized
+according
+to
+the
+requirements
+defined
+in
+Section
+8.1
+of
+RFC8259
+
+JSON,
+with
+JSON-LD
+1.1
+
+[
+
+RFC8259
+
+
+JSON-LD11
+
+
+
+]
+for
+open
+ecosystems.
+In
+summary,
+this
+requires
+the
+following:
+TDs
+MUST
+be
+encoded
+using
+UTF-8
+[
+RFC3629
+].
+
+syntax
+to
+support
+extensions
+and
+semantic
+processing.
+
+
+
+-
+
Implementations
+
+
+Directories
+
+
+MUST
+NOT
+
+MAY
+
+
+add
+a
+byte
+order
+mark
+(U+FEFF)
+
+accept
+alternative
+representations
+based
+on
+request's
+indicated
+Content-Type
+or
+Content-Encoding
+headers.
+
+This
+is
+useful
+for
+applications
+that
+need
+to
+provide
+representations
+other
+than
+raw
+JSON
+as
+input
+
+to
+the
+beginning
+of
+
+a
+TD
+document.
+
+directory.
+
+
+-
+
TD
+Processors
+
+
+Directories
+
+
+MAY
+
+ignore
+
+provide
+alternative
+representations
+through
+server-driven
+content
+negotiation,
+that
+is
+by
+honouring
+
+the
+presence
+of
+a
+byte
+order
+mark
+rather
+
+request's
+Accept
+and
+Accept-Encoding
+headers
+and
+responding
+with
+the
+supported
+TD
+representation
+and
+equivalent
+Content-Type
+and
+Content-Encoding
+headers.
+
+This
+is
+useful
+for
+applications
+that
+need
+to
+retrieve
+representations
+other
+
+than
+treating
+it
+
+raw
+JSON
+from
+a
+directory,
+such
+
+as
+an
+error.
+
+Gzip-compressed
+JSON.
+
+
+
+
+The
+CRUDL
+operations
+are
+described
+in
+the
+following
+sections:
+
+
+
+The
+TD
+Information
+Model
+is
+constructed,
+so
+that
+there
+is
+an
+easy
+mapping
+between
+model
+Objects
+and
+JSON
+types.
+Every
+Class
+instances
+maps
+
+Creation
+refers
+
+to
+a
+JSON
+object,
+where
+each
+name-value
+pair
+of
+
+the
+Class
+instance
+is
+a
+member
+
+registration
+
+of
+a
+new
+
+TD
+
+inside
+
+the
+JSON
+object.
+
+directory.
+
+
+
+Every
+Simple
+Type
+mentioned
+
+The
+TD
+object
+is
+validated
+
+in
+accordance
+with
+
+
+5.3
+
+7.3.2.1.6
+
+
+Class
+Definitions
+(i.e.,
+string
+,
+anyURI
+,
+dateTime
+,
+integer
+,
+unsignedInt
+,
+double
+,
+and
+boolean
+)
+maps
+to
+a
+primitive
+JSON
+type
+(string,
+number,
+boolean),
+as
+per
+the
+rules
+listed
+below.
+These
+rules
+apply
+to
+values
+in
+name-value
+pairs:
+Values
+
+Validation
+.
+Note
+
+that
+are
+of
+type
+string
+
+a
+TD
+may
+
+or
+anyURI
+MUST
+be
+serialized
+as
+JSON
+strings.
+Values
+that
+are
+of
+type
+dateTime
+MUST
+
+may
+not
+
+be
+serialized
+as
+JSON
+strings
+following
+the
+"date-time"
+format
+specified
+
+generated
+
+by
+[
+RFC3339
+].
+Examples
+would
+include
+2019-05-24T13:12:45Z
+and
+2015-07-11T09:32:26+08:00
+.
+Values
+that
+are
+of
+type
+dateTime
+SHOULD
+use
+the
+literal
+Z
+representing
+
+the
+UTC
+time
+zone
+instead
+of
+an
+offset.
+Values
+that
+are
+of
+type
+integer
+
+
+Thing
+
+it
+describes.
+For
+brownfield
+devices
+in
+particular
+a
+separate
+
+Discoverer
+
+process
+
+or
+unsignedInt
+MUST
+
+service
+may
+
+be
+serialized
+as
+JSON
+numbers
+without
+
+required
+that
+generates
+and
+registers
+
+a
+fraction
+or
+exponent
+part.
+
+TD
+for
+a
+
+Thing
+
+on
+its
+behalf.
+
+Values
+that
+are
+of
+type
+
+
+A
+TD
+which
+is
+identified
+with
+an
+
+
+double
+
+id
+
+
+attribute
+
+
+MUST
+
+be
+serialized
+as
+JSON
+number.
+Values
+
+handled
+differently
+with
+one
+
+that
+are
+of
+type
+boolean
+MUST
+be
+serialized
+as
+JSON
+boolean.
+Every
+complex
+type
+of
+the
+
+has
+no
+identifier
+(
+
+Anonymous
+
+TD
+Information
+Model
+(i.e.,
+Arrays
+,
+Maps
+,
+and
+Class
+
+
+instances)
+maps
+to
+a
+structured
+JSON
+type
+(array
+and
+object),
+as
+per
+the
+rules
+listed
+
+).
+
+The
+create
+operations
+are
+elaborated
+
+below:
+
+
+-
+
+A
+
value
+of
+type
+Array
+
+TD
+that
+has
+an
+
+id
+
+
+MUST
+
+be
+serialized
+as
+JSON
+array,
+with
+each
+value
+of
+the
+name-value
+pairs
+as
+element
+of
+
+submitted
+to
+
+the
+JSON
+array
+ordered
+by
+
+directory
+in
+
+the
+numeric
+name
+
+body
+
+of
+an
+HTTP
+
+PUT
+
+request
+at
+
+/things/{id}
+
+endpoint,
+where
+
+id
+
+is
+
+the
+pair.
+A
+value
+of
+type
+Map
+MUST
+be
+serialized
+as
+JSON
+object,
+with
+each
+name-value
+pair
+as
+member
+of
+
+unique
+TD
+identifier,
+present
+inside
+
+the
+JSON
+
+TD
+
+object.
+
+A
+Class
+
+An
+
+Anonymous
+TD
+
+
+instance
+
+is
+handled
+differently;
+see
+below.
+
+The
+request
+
+
+MUST
+
+SHOULD
+
+
+be
+serialized
+as
+
+contain
+
+application/td+json
+
+Content-Type
+header
+for
+
+JSON
+object,
+following
+the
+detailed
+rules
+given
+individually
+in
+6.3
+Information
+Model
+Serialization
+.
+6.2
+Omitting
+Default
+Values
+A
+Thing
+Description
+
+serialization
+may
+omit
+Vocabulary
+Term
+for
+which
+Default
+Values
+are
+defined,
+as
+listed
+in
+the
+table
+given
+
+of
+TD.
+
+The
+TD
+object
+is
+validated
+
+in
+accordance
+with
+
+
+5.4
+
+7.3.2.1.6
+
+
+Default
+Value
+Definitions
+
+Validation
+
+.
+The
+following
+example
+shows
+
+
+Upon
+successful
+processing,
+
+the
+TD
+instance
+from
+Example
+1
+
+server
+
+MUST
+
+respond
+
+with
+a
+checkbox
+to
+also
+include
+
+201
+(Created)
+status.
+
+Note:
+If
+
+the
+members
+with
+Default
+Values
+(=checkbox
+checked).
+These
+members
+can
+be
+omitted
+(=checkbox
+unchecked)
+
+target
+location
+corresponds
+
+to
+simplify
+
+an
+existing
+TD,
+
+the
+TD
+serialization.
+Note
+that
+a
+TD
+Processor
+interprets
+these
+omitted
+members
+identically
+
+request
+shall
+instead
+proceed
+
+as
+if
+they
+were
+explicitly
+present
+with
+a
+given
+Default
+Value
+.
+
+an
+Update
+operation
+and
+respond
+the
+appropriate
+status
+code
+(see
+Update
+section).
+
+
+Example
+4
+with
+Default
+Values
+{
+ : <span class=
+"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
+ : <span class=
+"hljs-string">"urn:dev:ops:32473-WoTLamp-1234",
+ : <span class=
+"hljs-string">"MyLampThing",
+ : {
+ : {
+ : <span class=
+"hljs-string">"basic"
+ }
+ },
+ : <span class=
+"hljs-string">"basic_sc",
+ : {
+ : {
+ : <span class=
+"hljs-string">"string",
+ : [{
+ : <span class=
+"hljs-string">"https://mylamp.example.com/status"
+ }]
+ }
+ },
+ : {
+ : {
+ : [{
+ : <span class=
+"hljs-string">"https://mylamp.example.com/toggle"
+ }]
+ }
+ },
+ : {
+ : {
+ : {
+ : <span class=
+"hljs-string">"string"
+ },
+ : [{
+ : <span class=
+"hljs-string">"https://mylamp.example.com/oh",
+ <span class=
+"hljs-attr">"subprotocol": <span class=
+"hljs-string">"longpoll"
+ }]
+ }
+ }
+}
+{
+ : <span class=
+"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
+ : <span class=
+"hljs-string">"urn:dev:ops:32473-WoTLamp-1234",
+ : <span class=
+"hljs-string">"MyLampThing",
+ : {
+ : {
+ : <span class=
+"hljs-string">"basic",
+ : <span class=
+"hljs-string">"header"
+ }
+ },
+ : <span class=
+"hljs-string">"basic_sc",
+ : {
+ : {
+ : <span class=
+"hljs-string">"string",
+ : <span class=
+"hljs-literal">false,
+ <span class=
+"hljs-attr">"writeOnly",
+ <span class=
+"hljs-attr">"observable": <span class=
+"hljs-literal">false,
+ : [{
+ : [
+ <span class=
+"hljs-string">"readproperty",
+ <span class=
+"hljs-string">"writeproperty"
+ ],
+ : <span class=
+"hljs-string">"https://mylamp.example.com/status",
+ <span class=
+"hljs-attr">"contentType": <span class=
+"hljs-string">"application/json"
+ }]
+ }
+ },
+ : {
+ : {
+ : <span class=
+"hljs-literal">false,
+ <span class=
+"hljs-attr">"idempotent": <span class=
+"hljs-literal">false,
+ : [{
+ : <span class=
+"hljs-string">"invokeaction",
+ : <span class=
+"hljs-string">"https://mylamp.example.com/toggle",
+ <span class=
+"hljs-attr">"contentType": <span class=
+"hljs-string">"application/json"
+ }]
+ }
+ },
+ : {
+ : {
+ : {
+ : <span class=
+"hljs-string">"string",
+ <span class=
+"hljs-attr">"readOnly": <span class=
+"hljs-literal">false,
+ <span class=
+"hljs-attr">"writeOnly": <span class=
+"hljs-literal">false
+ },
+ : [{
+ : <span class=
+"hljs-string">"subscribeevent",
+ : <span class=
+"hljs-string">"https://mylamp.example.com/oh",
+ <span class=
+"hljs-attr">"contentType": <span class=
+"hljs-string">"application/json",
+ <span class=
+"hljs-attr">"subprotocol": <span class=
+"hljs-string">"longpoll"
+ }]
+ }
+ }
+}
+
+
+Please
+note
+that,
+depending
+on
+the
+Protocol
+Binding
+used,
+additional
+protocol-specific
+Vocabulary
+Terms
+
+The
+create
+operation
+for
+
+TDs
+
+
+may
+apply.
+They
+may
+also
+
+that
+
+have
+associated
+Default
+Values
+,
+and
+hence
+can
+also
+be
+omitted
+
+identifiers
+is
+specified
+
+as
+explained
+in
+this
+subsection.
+Further
+information
+can
+be
+found
+
+
+createThing
+
+action
+
+in
+8.3
+Protocol
+Bindings
+.
+
+
+
+6.3
+Information
+Model
+Serialization
+6.3.1
+
+7.3.2.4
+
+
+Thing
+Root
+Object
+A
+Thing
+Description
+is
+a
+data
+structure
+rooted
+at
+an
+Object
+of
+type
+Thing
+.
+In
+turn,
+a
+JSON
+serialization
+of
+the
+Thing
+Description
+is
+a
+JSON
+object,
+which
+is
+the
+root
+of
+a
+syntax
+tree
+constructed
+from
+the
+TD
+Information
+Model
+
+API
+Specification
+(Thing
+Model)
+
+.
+
+
+-
+
The
+root
+element
+of
+a
+TD Serialization
+
+
+An
+
+Anonymous
+TD
+
+
+
+MUST
+
+ be
+a
+JSON
+object
+that
+includes
+a
+member
+with
+the
+name
+@context
+and
+a
+value
+of
+type
+string
+or
+array
+that
+equals
+or
+respectively
+contains
+https://www.w3.org/2022/wot/td/v1.1
+.
+In
+general,
+this
+URI
+is
+used
+
+be
+submitted
+
+to
+identify
+
+the
+TD
+representation
+format
+version
+defined
+by
+this
+specification.
+For
+JSON-LD
+processing
+[
+json-ld11
+],
+this
+URI
+specifies
+
+directory
+in
+
+the
+Thing
+Description
+context
+file.
+An
+@context
+of
+type
+array
+indicates
+TD
+Context
+Extensions
+(see
+7.
+TD
+Context
+Extensions
+for
+details).
+Example
+5
+{
+ : <span class=
+"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
+ ...
+}
+All
+name-value
+pairs
+
+body
+
+of
+an
+instance
+of
+
+HTTP
+
+
+Thing
+,
+where
+the
+name
+is
+a
+Vocabulary
+Term
+in
+the
+Signature
+of
+
+POST
+
+request
+at
+
+
+Thing
+,
+MUST
+
+/things
+
+endpoint.
+
+The
+request
+
+SHOULD
+
+
+be
+serialized
+as
+
+contain
+
+application/td+json
+
+Content-Type
+header
+for
+
+JSON
+members
+
+serialization
+
+of
+the
+root
+object.
+
+TD.
+
+
+A
+
+The
+
+TD
+snippet
+for
+a
+serialized
+root
+
+object
+including
+all
+mandatory
+and
+optional
+members
+
+is
+given
+below:
+
+validated
+in
+accordance
+with
+
+Example
+6
+
+
+7.3.2.1.6
+
+
+:
+Sample
+of
+Thing
+serializations
+{
+ : <span class=
+"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
+ : <span class=
+"hljs-string">"Thing",
+ : <span class=
+"hljs-string">"urn:dev:ops:32473-Thing-1234",
+ : <span class=
+"hljs-string">"MyThing",
+ : {...},
+ : <span class=
+"hljs-string">"Human readable information.",
+ : {...},
+ : <span class=
+"hljs-string">"mailto:support@example.com",
+ : {...},
+ : <span class=
+"hljs-string">"2018-11-14T19:10:23.824Z",
+ : <span class=
+"hljs-string">"2019-06-01T09:12:43.124Z",
+ : {...},
+ : ...,
+ : <span class=
+"hljs-string">"https://servient.example.com/",
+ : {...},
+ : {...},
+ : {...},
+ : [...],
+ : [...]
+}
+All
+values
+assigned
+to
+version
+,
+securityDefinitions
+,
+properties
+,
+actions
+,
+and
+events
+in
+an
+instance
+of
+
+Validation
+.
+Upon
+successful
+processing,
+
+the
+Class
+Thing
+
+server
+
+MUST
+
+be
+serialized
+as
+JSON
+objects.
+All
+values
+assigned
+to
+links
+,
+
+respond
+with
+201
+(Created)
+status
+
+and
+forms
+in
+an
+instance
+
+a
+Location
+header
+containing
+a
+system-generated
+identifier
+for
+the
+TD.
+
+The
+scheme
+
+of
+the
+Class
+Thing
+MUST
+be
+serialized
+as
+JSON
+arrays
+containing
+JSON
+objects
+as
+defined
+
+system-generated
+ID
+is
+described
+
+in
+
+6.3.8
+
+
+7.3.1.3
+
+
+Anonymous
+TD
+Identifiers
+.
+The
+create
+operation
+for
+
+Anonymous
+TDs
+
+is
+specified
+as
+
+
+links
+
+createAnonymousThing
+
+
+and
+
+action
+in
+
+
+6.3.9
+
+7.3.2.4
+
+
+forms
+, respectively.
+
+API
+Specification
+(Thing
+Model)
+.
+
+
+
+
+A
+server
+that
+supports
+expirable
+TDs
+will
+realize
+such
+functionality
+as
+described
+in
+
+The
+value
+assigned
+to
+
+
+7.3.1.2
+
+Registration
+Expiry
+.
+In
+particular,
+if
+
+
+security
+
+ttl
+
+
+in
+an
+instance
+of
+Class
+
+(relative
+expiry)
+is
+given
+during
+the
+creation,
+such
+servers
+will
+calculate
+and
+store
+the
+
+
+Thing
+
+expires
+
+
+MUST
+ be
+serialized
+as
+JSON string
+or
+as
+JSON
+array
+whose
+elements
+are
+JSON
+strings.
+
+value.
+
+
+
+
+
+
+JSON
+members
+named
+
+
+The
+retrieval
+of
+an
+existing
+TD
+
+MUST
+
+be
+done
+using
+an
+HTTP
+
+
+title
+
+GET
+
+
+and
+
+request
+at
+
+
+description
+
+/things/{id}
+
+
+are
+used
+within
+a
+TD
+document
+to
+provide
+human-readable
+metadata.
+They
+can
+be
+used
+as
+comments
+for
+developers
+inspecting
+a
+TD
+document
+or
+as
+display
+texts
+for
+user
+interface.
+As
+defined
+in
+5.3.1.1
+
+endpoint,
+where
+
+
+Thing
+
+id
+
+
+,
+the
+base
+text
+direction
+used
+to
+display
+human-readable
+metadata
+can
+either
+be
+estimated
+using
+heuristics
+such
+as
+
+is
+
+the
+first-strong
+rule
+or
+inferred
+from
+language
+information.
+In
+
+unique
+
+TD
+documents
+
+identifier.
+
+A
+successful
+response
+
+MUST
+
+have
+200
+(OK)
+status
+and
+
+the
+default
+language
+is
+defined
+by
+a
+value
+assigned
+to
+@language
+
+requested
+TD
+
+in
+the
+@context
+,
+and
+this,
+along
+
+body.
+
+A
+successful
+response
+
+with
+a
+script
+subtag
+if
+necessary,
+can
+be
+used
+to
+determine
+a
+base
+text
+direction.
+However,
+when
+interpreting
+human-readable
+text,
+each
+human-readable
+string
+value
+
+JSON
+serialization
+
+MUST
+
+be
+processed
+independently.
+In
+other
+words,
+a
+TD
+Processor
+cannot
+carry
+forward
+changes
+in
+direction
+from
+one
+string
+to
+another,
+
+contain
+
+application/json
+
+or
+infer
+direction
+for
+one
+string
+from
+another
+one
+elsewhere
+
+more
+specifically,
+
+application/td+json
+
+in
+the
+TD.
+Note
+
+Content-Type
+header.
+
+
+Strings
+on
+the
+Web
+[
+STRING-META
+]
+suggests
+both
+strong-first
+and
+language-based
+inferencing
+as
+means
+to
+determine
+the
+base
+text
+direction.
+Given
+
+Note
+
+that
+the
+Thing
+Description
+format
+
+default
+serialization
+
+is
+based
+on
+JSON-LD
+1.1
+[
+json-ld11
+],
+which
+currently
+lacks
+explicit
+direction
+metadata,
+these
+approaches
+are
+currently
+considered
+appropriate
+at
+the
+time
+of
+this
+publication.
+However,
+if
+
+JSON
+with
+
+JSON-LD
+1.1
+adopts
+support
+for
+explicit
+base
+direction
+metadata
+as
+recommended
+by
+[
+STRING-META
+],
+the
+Thing
+Description
+format
+should
+
+syntax,
+and
+alternative
+serializations
+can
+
+be
+updated
+to
+take
+advantage
+of
+that
+feature.
+
+negotiated;
+see
+
+7.3.2.1
+
+Things
+API
+.
+
+
+A
+TD
+snippet
+using
+title
+and
+description
+is
+shown
+below.
+
+The
+default
+language
+
+retrieve
+operation
+
+is
+set
+to
+
+specified
+as
+
+
+en
+
+retrieveThing
+
+
+through
+the
+definition
+
+action
+in
+
+7.3.2.4
+
+API
+Specification
+(Thing
+Model)
+.
+The
+following
+is
+an
+example
+
+of
+the
+@language
+member
+within
+
+a
+JSON
+object
+in
+the
+@context
+array.
+
+retrieved
+TD:
+
+
+
+This
+is
+an
+
+Enriched
+
+TD
+document.
+All
+name-value
+pairs
+of
+a
+MultiLanguage
+Map
+
+
+MUST
+ be
+serialized
+as
+members
+of
+a
+JSON
+object,
+where
+
+which
+includes
+
+the
+name
+is
+a
+well-formed
+language
+tag
+
+registration
+information
+such
+
+as
+defined
+by
+[
+BCP47
+]
+and
+
+the
+value
+is
+a
+human-readable
+string
+in
+the
+language
+indicated
+by
+
+creation
+and
+modification
+time
+of
+
+the
+tag.
+See
+5.3.1.7
+MultiLanguage
+for
+details.
+All
+MultiLanguage
+object
+within
+a
+
+TD
+document
+SHOULD
+contain
+
+within
+
+the
+same
+set
+of
+language
+members.
+
+directory.
+
+
+
+A
+
+The
+example
+below
+shows
+a
+retrieved
+
+Anonymous
+
+TD
+snippet
+using
+titles
+
+
+that
+is
+in
+
+Enriched
+TD
+
+form
+
+and
+has
+local
+identifier
+
+
+descriptions
+at
+different
+levels
+is
+given
+below:
+
+urn:uuid:48951ff3-4019-4e67-b217-dbbf011873dc
+.
+
+
+The
+following
+is
+an
+example
+of
+
+a
+retrieved
+
+TD
+document,
+each
+title
+and
+description
+member
+SHOULD
+have
+
+that
+was
+registered
+with
+
+a
+corresponding
+titles
+and
+descriptions
+member,
+respectively.
+The
+language
+
+relative
+expiry
+time
+
+of
+3600
+seconds
+(one
+hour).
+The
+server
+has
+calculated
+
+the
+default
+text
+is
+indicated
+by
+the
+default
+language,
+which
+is
+usually
+set
+by
+the
+creator
+of
+
+absolute
+expiry
+time
+as
+one
+hour
+after
+
+the
+Thing
+Description
+instance.
+
+modification
+time.
+
+
+
+For
+
+the
+corresponding
+default
+language
+
+sake
+
+of
+readability,
+
+the
+returned
+content.
+When
+the
+default
+language
+has
+been
+negotiated
+successfully,
+TD
+documents
+SHOULD
+include
+the
+appropriate
+matching
+
+time
+
+values
+for
+the
+members
+title
+and
+description
+in
+preference
+to
+MultiLanguage
+objects
+
+in
+titles
+and
+descriptions
+members.
+Note
+however
+that
+Things
+MAY
+choose
+to
+not
+support
+such
+dynamically-generated
+TDs
+nor
+
+this
+example
+are
+set
+
+to
+support
+language
+negotiation
+(e.g.,
+because
+of
+resource
+constraints).
+
+exact
+numbers.
+In
+realistic
+settings,
+time
+values
+may
+include
+fractions.
+
+
+
+
+
+
+The
+update
+operations
+are
+to
+replace
+or
+partially
+modify
+an
+existing
+TD.
+
+The
+update
+operations
+are
+described
+below:
+
-
+
All
+name-value
+pairs
+of
+
+
+A
+modified
+TD
+
+MUST
+
+replace
+
+an
+instance
+of
+
+existing
+one
+when
+submitted
+using
+an
+HTTP
+
+
+VersionInfo
+,
+
+PUT
+
+request
+at
+
+/things/{id}
+
+endpoint,
+
+where
+the
+name
+
+
+id
+
+is
+a
+Vocabulary
+Term
+included
+in
+
+the
+Signature
+
+identifier
+
+of
+VersionInfo
+,
+
+the
+existing
+TD.
+
+The
+request
+
+
+MUST
+
+SHOULD
+
+
+be
+serialized
+as
+
+contain
+
+application/td+json
+
+Content-Type
+header
+for
+
+JSON
+members
+with
+the
+Vocabulary
+Term
+as
+name.
+
+serialization
+of
+TD.
+
+
+A
+
+The
+
+TD
+snippet
+of
+a
+version
+information
+
+object
+is
+given
+below:
+
+validated
+in
+accordance
+with
+
+Example
+10
+
+
+7.3.2.1.6
+
+
+{
+ ...
+ "version": { <span class=
+"hljs-string">"instance": <span class=
+"hljs-string">"1.2.1" },
+ ...
+}
+
+Validation
+.
+Upon
+success,
+the
+server
+
+MUST
+
+respond
+with
+204
+(No
+Content)
+status.
+
+
+The
+version
+member
+
+This
+operation
+
+is
+intended
+
+specified
+
+as
+container
+for
+additional
+application-
+and/or
+device-specific
+version
+information
+based
+on
+TD
+Context
+Extensions
+.
+See
+
+
+updateThing
+
+property
+in
+
+7.1
+
+
+7.3.2.4
+
+
+Semantic
+Annotations
+for
+details.
+
+API
+Specification
+(Thing
+Model)
+.
+
+
+A
+server
+that
+supports
+expirable
+TDs
+will
+realize
+such
+functionality
+as
+described
+in
+
+6.3.4
+
+
+7.3.1.2
+
+
+Registration
+Expiry
+.
+If
+
+
+securityDefinitions
+
+ttl
+
+
+(relative
+expiry)
+is
+set
+during
+the
+update
+operation,
+the
+server
+will
+calculate
+
+and
+set
+the
+
+
+security
+
+expires
+
+
+(absolute
+expiry)
+value.
+
+
+In
+a
+Thing
+instance,
+
+Note:
+If
+
+the
+value
+assigned
+
+target
+location
+does
+not
+correspond
+
+to
+securityDefinitions
+is
+a
+Map
+of
+instances
+of
+SecurityScheme
+.
+All
+name-value
+pairs
+of
+a
+Map
+of
+SecurityScheme
+instances
+MUST
+ be
+serialized
+as
+members
+of
+the
+JSON
+object
+that
+results
+from
+serializing
+the
+Map
+;
+
+an
+existing
+TD,
+
+the
+name
+of
+a
+pair
+MUST
+ be
+serialized
+
+request
+shall
+instead
+proceed
+
+as
+a
+JSON
+string
+
+Create
+operation
+
+and
+respond
+
+the
+value
+of
+the
+pair,
+
+appropriate
+status
+code
+(see
+Create
+section).
+In
+other
+words,
+
+an
+instance
+of
+
+HTTP
+
+
+SecurityScheme
+,
+MUST
+be
+serialized
+
+PUT
+
+request
+acts
+
+as
+a
+JSON
+object.
+
+create
+or
+update
+operation.
+
+
+
+-
+
All
+name-value
+pairs
+of
+an
+instance
+of
+one
+of
+
+
+An
+existing
+TD
+
+MUST
+
+be
+partially
+modified
+when
+
+the
+Subclasses
+of
+
+modified
+parts
+are
+submitted
+using
+an
+HTTP
+
+
+SecurityScheme
+,
+
+PATCH
+
+request
+at
+
+/things/{id}
+
+endpoint,
+
+where
+the
+name
+
+
+id
+
+is
+a
+Vocabulary
+Term
+included
+in
+
+the
+Signature
+
+identifier
+
+of
+that
+Subclass
+or
+in
+
+the
+Signature
+of
+SecurityScheme
+,
+
+existing
+TD.
+
+The
+partial
+update
+
+
+MUST
+
+be
+serialized
+as
+members
+of
+
+processed
+using
+
+the
+JSON
+object
+that
+results
+from
+serializing
+the
+SecurityScheme
+Subclass
+'s
+instance,
+with
+the
+Vocabulary
+Term
+
+merge
+patch
+format
+described
+in
+[
+
+RFC7396
+
+
+as
+name.
+
+The
+following
+TD
+snippet
+shows
+a
+simple
+security
+configuration
+specifying
+basic
+username/password
+authentication
+in
+the
+header.
+
+
+].
+
+The
+value
+given
+for
+
+request
+
+MUST
+
+contain
+
+
+in
+
+application/merge-patch+json
+
+
+is
+actually
+the
+Default
+Value
+(
+
+Content-Type
+
+header
+)
+and
+could
+be
+omitted.
+A
+named
+security
+configuration
+must
+be
+given
+in
+the
+securityDefinitions
+map.
+That
+definition
+must
+be
+activated
+by
+including
+its
+
+for
+
+JSON
+name
+in
+the
+security
+member,
+which
+can
+and
+should
+be
+
+serialization
+
+of
+type
+string
+when
+only
+one
+definition
+is
+activated.
+Example
+11
+...
+: {
+ : {
+ : <span class=
+"hljs-string">"basic",
+ : <span class=
+"hljs-string">"header"
+ }
+},
+: <span class=
+"hljs-string">"basic_sc",
+...
+Security
+configuration
+in
+
+the
+TD
+is
+mandatory.
+At
+least
+one
+security
+definition
+
+merge
+patch
+document.
+
+The
+input
+
+
+MUST
+
+be
+activated
+through
+the
+security
+member
+at
+the
+Thing
+level
+(i.e.,
+
+in
+
+Partial
+TD
+
+form
+and
+conform
+to
+
+the
+original
+
+TD
+root
+object).
+
+structure.
+
+
+This
+configuration
+can
+be
+seen
+as
+the
+default
+security
+mechanism
+required
+to
+interact
+with
+
+If
+
+the
+Thing
+.
+Security
+definitions
+MAY
+also
+be
+activated
+at
+
+input
+contains
+members
+that
+appear
+in
+
+the
+form
+level
+by
+including
+
+original
+TD,
+their
+values
+are
+replaced.
+If
+
+a
+security
+
+member
+does
+not
+appear
+
+in
+form
+objects,
+which
+overrides
+(i.e.,
+completely
+replace)
+all
+definitions
+activated
+at
+the
+Thing
+level.
+The
+nosec
+security
+scheme
+is
+provided
+for
+
+the
+case
+
+original
+TD,
+
+that
+no
+security
+is
+needed.
+The
+minimal
+security
+configuration
+for
+a
+Thing
+
+member
+
+is
+activation
+of
+
+added.
+If
+
+the
+member
+is
+set
+to
+
+
+nosec
+
+null
+
+
+security
+scheme
+at
+the
+Thing
+level,
+as
+shown
+
+but
+appear
+
+in
+the
+following
+example:
+Example
+12
+{
+ : <span class=
+"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
+ : <span class=
+"hljs-string">"urn:dev:ops:32473-Thing-1234",
+ : <span class=
+"hljs-string">"MyThing",
+ : <span class=
+"hljs-string">"Human readable information.",
+ : <span class=
+"hljs-string">"https://servient.example.com/contact",
+ <span class=
+"hljs-string">"securityDefinitions": { <span class=
+"hljs-string">"nosec_sc": { <span class=
+"hljs-string">"scheme": <span class=
+"hljs-string">"nosec" }},
+ : <span class=
+"hljs-string">"nosec_sc",
+ : {...},
+ : {...},
+ : {...},
+ : [...]
+}
+6.3.4.1
+Multiple
+Security
+Definitions
+To
+give
+a
+more
+complex
+example,
+suppose
+we
+have
+a
+Thing
+where
+all
+Interaction
+Affordances
+require
+basic
+authentication
+except
+for
+one,
+for
+which
+no
+authentication
+
+original
+TD,
+that
+member
+
+is
+required.
+For
+
+removed.
+Members
+with
+object
+values
+are
+processed
+recursively.
+After
+applying
+
+the
+status
+Property
+and
+
+modifications,
+
+the
+toggle
+Action,
+basic
+authentication
+
+TD
+object
+
+is
+required
+and
+defined
+at
+the
+Thing
+level.
+For
+
+validated
+in
+accordance
+with
+
+7.3.2.1.6
+
+Validation
+.
+Upon
+success,
+
+the
+server
+
+MUST
+
+respond
+with
+a
+204
+(No
+Content)
+status.
+
+This
+operation
+is
+specified
+as
+
+
+overheating
+
+partiallyUpdateThing
+
+
+Event,
+however,
+no
+authentication
+is
+required,
+and
+hence
+the
+security
+configuration
+is
+overridden
+at
+the
+form
+level.
+
+property
+in
+
+Example
+13
+
+
+7.3.2.4
+
+
+{
+ ...
+ "securityDefinitions": {
+ : {<span class=
+"hljs-string">"scheme": <span class=
+"hljs-string">"basic"},
+ "nosec_sc": {<span class=
+"hljs-string">"scheme": <span class=
+"hljs-string">"nosec"}
+ },
+ "security": ,
+ ...
+ : {
+ : {
+ ...
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://mylamp.example.com/status"
+ }]
+ }
+ },
+ "actions": {
+ : {
+ ...
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://mylamp.example.com/toggle"
+ }]
+ }
+ },
+ "events": {
+ : {
+ ...
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://mylamp.example.com/oh",
+ <span class=
+"hljs-string">"security": <span class=
+"hljs-string">"nosec_sc"
+ }]
+ }
+ }
+}
+
+API
+Specification
+(Thing
+Model)
+.
+
+A
+server
+that
+supports
+expirable
+
+TDs
+can
+specify
+a
+combination
+of
+security
+schemes
+
+will
+realize
+such
+functionality
+
+as
+well.
+Below
+is
+a
+TD
+snippet
+showing
+digest
+authentication
+on
+a
+proxy
+combined
+with
+bearer
+token
+authentication
+on
+the
+Thing
+
+described
+in
+
+7.3.1.2
+
+Registration
+Expiry
+
+.
+In
+
+During
+
+the
+digest
+scheme,
+
+partial
+update
+operation,
+if
+
+the
+Default
+Value
+
+resulting
+
+TD
+
+
+of
+in
+(i.e.,
+
+has
+
+
+header
+
+ttl
+
+
+)
+is
+omitted,
+but
+still
+applies.
+Note
+that
+
+(relative
+expiry),
+
+the
+corresponding
+private
+security
+configuration
+such
+as
+username/password
+
+server
+will
+calculate
+
+and
+tokens
+must
+be
+configured
+in
+the
+Consumer
+to
+interact
+successfully.
+When
+activating
+multiple
+security
+definitions,
+the
+
+set
+a
+new
+
+
+security
+
+expires
+
+
+member
+becomes
+an
+array.
+
+(absolute
+expiry)
+value.
+
+
+Example
+14
+...
+: {
+ : {
+ : <span class=
+"hljs-string">"digest",
+ : <span class=
+"hljs-string">"https://portal.example.com/"
+ },
+ : {
+ : <span class=
+"hljs-string">"bearer",
+ :<span class=
+"hljs-string">"header",
+ : <span class=
+"hljs-string">"jwt",
+ : <span class=
+"hljs-string">"ES256",
+ <span class=
+"hljs-string">"authorization": <span class=
+"hljs-string">"https://servient.example.com:8443/"
+ }
+},
+: [<span class=
+"hljs-string">"proxy_sc", <span class=
+"hljs-string">"bearer_sc"],
+...
+
+
+However,
+
+A
+patch
+operation
+is
+particularly
+useful
+to
+efficiently
+extend
+
+the
+use
+
+expiry
+
+of
+an
+array
+with
+multiple
+elements
+to
+combine
+security
+schemes
+in
+
+a
+registration
+that
+uses
+
+a
+
+security
+element
+is
+now
+deprecated.
+A
+ComboSecurityScheme
+
+ttl
+
+
+should
+be
+used
+instead
+as
+in
+the
+following
+example,
+which
+
+(relative
+expiry)
+value.
+This
+
+is
+exactly
+equivalent
+
+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
+one
+above:
+Example
+15
+...
+: {
+ : {
+ : <span class=
+"hljs-string">"digest",
+ : <span class=
+"hljs-string">"https://portal.example.com/"
+ },
+ : {
+ : <span class=
+"hljs-string">"bearer",
+ :<span class=
+"hljs-string">"header",
+ : <span class=
+"hljs-string">"jwt",
+ : <span class=
+"hljs-string">"ES256",
+ <span class=
+"hljs-string">"authorization": <span class=
+"hljs-string">"https://servient.example.com:8443/"
+ },
+ : {
+ : <span class=
+"hljs-string">"combo",
+ : [<span class=
+"hljs-string">"proxy_sc", <span class=
+"hljs-string">"bearer_sc"]
+ }
+},
+: <span class=
+"hljs-string">"combo_sc",
+...
+6.3.4.2
+
+recalculation
+of
+
+
+security
+
+expires
+
+
+(absolute
+expiry)
+value.
+This
+expiry
+functionality
+only
+works
+if
+the
+server
+supports
+it
+as
+defined
+
+in
+Forms
+
+
+Security
+configurations
+can
+also
+be
+specified
+for
+different
+forms
+within
+the
+same
+Interaction
+Affordance
+
+
+7.3.1.2
+
+Registration
+Expiry
+
+.
+This
+may
+be
+required
+for
+devices
+that
+support
+multiple
+protocols,
+for
+
+
+
+The
+following
+
+example
+HTTP
+and
+CoAP
+[
+RFC7252
+],
+which
+support
+different
+security
+mechanisms.
+This
+
+is
+also
+useful
+when
+alternative
+authentication
+mechanisms
+are
+allowed.
+Here
+is
+a
+TD
+snippet
+demonstrating
+three
+possible
+ways
+to
+activate
+
+a
+Property
+affordance:
+via
+HTTPS
+with
+basic
+authentication,
+with
+digest
+authentication,
+with
+bearer
+token
+authentication.
+In
+other
+words,
+the
+use
+of
+different
+security
+configurations
+within
+multiple
+forms
+provides
+a
+way
+
+merge
+patch
+document
+
+to
+combine
+security
+mechanisms
+in
+an
+"OR"
+fashion.
+In
+contrast,
+putting
+multiple
+security
+configurations
+in
+
+update
+only
+
+the
+same
+
+
+security
+
+base
+
+
+member
+combines
+them
+in
+an
+"AND"
+fashion,
+since
+in
+that
+case
+they
+would
+all
+need
+to
+be
+satisfied
+to
+allow
+activation
+
+and
+registration
+
+expires
+
+fields
+
+of
+the
+Interaction
+Affordance
+.
+Note
+that
+activating
+one
+(default)
+configuration
+at
+the
+Thing
+level
+is
+still
+mandatory.
+
+a
+TD:
+
+
+
+
+
+
+
+As
+another
+more
+complex
+example,
+OAuth
+2.0
+makes
+use
+of
+scopes.
+These
+are
+identifiers
+that
+may
+appear
+in
+tokens
+and
+must
+match
+with
+corresponding
+identifiers
+in
+a
+resource
+to
+allow
+access
+to
+that
+resource
+(or
+Interaction
+Affordance
+in
+the
+case
+of
+W3C
+WoT).
+For
+example,
+in
+the
+following,
+the
+status
+Property
+can
+
+
+A
+delete
+operation
+
+MUST
+
+be
+read
+by
+Consumers
+
+done
+
+using
+bearer
+tokens
+containing
+the
+scope
+limited
+,
+but
+the
+configure
+Action
+can
+only
+be
+invoked
+with
+a
+token
+containing
+the
+special
+scope.
+Scopes
+are
+not
+identical
+to
+roles,
+but
+are
+often
+associated
+with
+them;
+for
+example,
+perhaps
+only
+those
+in
+an
+administrative
+role
+are
+authorized
+to
+perform
+"special"
+interactions.
+Tokens
+can
+have
+more
+than
+one
+scope
+and
+are
+issued
+by
+dedicated
+web
+services
+to
+users.
+In
+this
+example,
+
+an
+administrator
+could
+be
+issued
+tokens
+with
+both
+the
+
+HTTP
+
+
+limited
+
+DELETE
+
+
+and
+
+request
+at
+
+
+special
+
+/things/{id}
+,
+where
+
+id
+
+
+scopes,
+while
+ordinary
+users
+could
+be
+provided
+with
+tokens
+with
+
+is
+the
+identifier
+of
+
+the
+existing
+TD.
+
+A
+successful
+response
+
+MUST
+
+have
+204
+(No
+Content)
+status.
+
+The
+retrieve
+operation
+is
+specified
+as
+
+
+limited
+
+deleteThing
+
+
+scope.
+
+property
+in
+
+Example
+18
+
+
+7.3.2.4
+
+
+{
+ ...
+ "securityDefinitions": {
+ : {
+ : <span class=
+"hljs-string">"oauth2",
+ : <span class=
+"hljs-string">"client",
+ : <span class=
+"hljs-string">"https://example.com/token",
+ <span class=
+"hljs-string">"scopes"]
+ }
+ },
+ "security": ,
+ ...
+ : {
+ : {
+ ...
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://scopes.example.com/status",
+ <span class=
+"hljs-string">"scopes": [<span class=
+"hljs-string">"limited"]
+ }]
+ }
+ },
+ "actions": {
+ : {
+ ...
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://scopes.example.com/configure",
+ <span class=
+"hljs-string">"scopes": [<span class=
+"hljs-string">"special"]
+ }]
+ }
+ },
+ ...
+}
+
+API
+Specification
+(Thing
+Model)
+.
+
+
+
+
+A
+Thing
+can
+require
+an
+onboarding
+process
+that
+results
+in
+the
+Consumer
+requiring
+an
+API
+key
+to
+interact
+with
+the
+Thing.
+This
+API
+key
+can
+be
+included
+in
+the
+request
+to
+the
+Thing
+in
+
+The
+listing
+endpoint
+provides
+
+different
+ways
+as
+
+to
+query
+
+the
+API
+key
+scheme
+specifies.
+Below
+is
+an
+example
+
+collection
+
+of
+how
+it
+can
+be
+used
+as
+a
+URI
+template
+where
+the
+API
+key
+should
+be
+replaced
+in
+the
+URI
+by
+
+full
+TD
+objects
+from
+
+the
+Consumer
+when
+sending
+an
+HTTPS
+request.
+
+directory.
+
+
+Example
+19
+{
+ ...
+ "securityDefinitions": {
+ : {
+ : <span class=
+"hljs-string">"apikey",
+ : <span class=
+"hljs-string">"uri",
+ : <span class=
+"hljs-string">"adminKey"
+ }
+ },
+ "security": ,
+ : {
+ : {
+ ...
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://example.com/{adminKey}/status",
+ ...
+ }]
+ }
+ },
+ ...
+}
+
+
+To
+give
+another
+example
+
+In
+many
+scenarios,
+retrieving
+parts
+instead
+
+of
+the
+use
+
+full
+TD
+objects
+is
+preferred
+because
+only
+a
+subset
+
+of
+the
+
+elements
+are
+needed
+(e.g.
+
+
+ComboSecurityScheme
+
+id
+
+
+in
+addition
+to
+the
+use
+of
+URI
+templates
+example
+shown
+above,
+suppose
+there
+is
+a
+security
+scheme
+where
+a
+client
+ID
+
+and
+
+href
+
+of
+
+a
+"secret"
+key
+provided
+by
+a
+cloud
+service
+provider
+must
+both
+be
+embedded
+in
+the
+URL.
+Technically,
+only
+the
+key
+is
+actually
+secret
+and
+must
+be
+handled
+out-of-band,
+
+property
+for
+all
+TDs)
+
+and
+the
+client
+ID,
+which
+is
+not
+secret,
+could
+be
+embedded
+in
+the
+TD.
+However,
+if
+the
+client
+ID
+cannot
+be
+easily
+rotated
+we
+may
+want
+to
+avoid
+embedding
+it
+in
+the
+TD
+
+to
+enhance
+privacy.
+In
+this
+case
+we
+can
+combine
+two
+instances
+
+save
+networking
+resources.
+The
+Search
+API
+allows
+querying
+parts
+
+of
+TD
+objects;
+see
+
+APIKeySecurityScheme
+
+
+7.3.2.3
+
+Search
+API
+.
+,
+both
+
+
+The
+directory
+
+MUST
+
+allow
+retrieval
+of
+existing
+TDs
+
+using
+the
+uri
+value
+for
+the
+
+HTTP
+
+
+in
+
+GET
+
+
+location
+specifier,
+to
+declare
+two
+URI
+variables.
+These
+can
+then
+(in
+fact,
+they
+must)
+be
+used
+in
+
+requests
+at
+
+the
+
+href
+in
+a
+Form
+where
+the
+security
+scheme
+is
+active.
+An
+example
+follows:
+Example
+20
+{
+ ...
+ "securityDefinitions": {
+ : {
+ : <span class=
+"hljs-string">"apikey",
+ : <span class=
+"hljs-string">"uri",
+ : <span class=
+"hljs-string">"secKey"
+ },
+ "apikey_id": {
+ : <span class=
+"hljs-string">"apikey",
+ : <span class=
+"hljs-string">"uri",
+ : <span class=
+"hljs-string">"secClientID"
+ },
+ "apikey_combo": {
+ : <span class=
+"hljs-string">"combo",
+ : [<span class=
+"hljs-string">"apikey_key",<span class=
+"hljs-string">"apikey_id"]
+ }
+ },
+ "security": ,
+ ...
+ : {
+ : {
+ ...
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://example.com/{secClientID}/status/{secKey}",
+ ...
+ }]
+ }
+ },
+ ...
+}
+While
+not
+shown
+in
+this
+example,
+it
+is
+legal
+to
+declare
+additional
+URI
+template
+variables
+using
+uriVariables
+
+/things
+
+
+endpoint.
+
+A
+successful
+response
+
+MUST
+
+have
+200
+(OK)
+status
+
+and
+include
+them
+in
+the
+same
+URI
+template,
+although
+the
+names
+cannot
+conflict
+with
+those
+declared
+in
+security
+schemes.
+Using
+a
+specific
+prefix
+as
+
+an
+array
+of
+TDs
+
+in
+the
+above
+example
+for
+URI
+variables
+declared
+in
+security
+schemes
+can
+make
+it
+easier
+to
+avoid
+name
+conflicts.
+API
+Key
+in
+Body:
+Security
+parameters
+might
+also
+be
+included
+along
+
+body.
+
+A
+successful
+response
+
+with
+the
+payload
+in
+some
+systems.
+For
+example,
+suppose
+a
+system
+requires
+every
+payload
+to
+be
+a
+
+JSON
+object
+including
+a
+member
+named
+
+serialization
+
+MUST
+
+contain
+
+
+auth
+
+application/json
+
+
+whose
+value
+is
+an
+object
+containing
+a
+member
+called
+
+or
+more
+specifically,
+
+
+key
+
+application/ld+json
+
+
+containing
+an
+access
+key.
+Depending
+on
+the
+interaction,
+however,
+other
+elements
+of
+the
+JSON
+object
+might
+vary.
+This
+situation
+can
+be
+dealt
+with
+using
+
+in
+
+the
+body
+security
+information
+location.
+
+Content-Type
+header.
+
+Note
+that
+for
+this
+location,
+
+the
+name
+parameter
+
+default
+serialization
+
+is
+actually
+a
+
+JSON
+pointer
+evaluated
+relative
+to
+the
+root
+of
+the
+DataSchema
+for
+each
+interaction
+it
+is
+bound
+with,
+which
+allows
+it
+to
+be
+used
+
+with
+payloads
+that
+vary
+in
+other
+respects.
+As
+an
+example,
+here
+is
+a
+light
+that
+has
+a
+property
+to
+set
+its
+brightness
+and
+color
+and
+two
+separate
+actions
+to
+turn
+it
+on
+
+JSON-LD
+syntax,
+
+and
+off.
+Although
+the
+JSON
+payloads
+are
+different
+for
+these
+actions
+the
+/auth/key
+element
+occurs
+in
+the
+same
+relative
+location
+so
+single
+JSON
+pointer
+
+alternative
+serializations
+
+can
+be
+used.
+Note:
+if
+the
+security
+key
+occurs
+in
+different
+inconsistent
+locations,
+it
+will
+
+negotiated;
+see
+
+7.3.2.1
+
+Things
+API
+.
+There
+may
+
+be
+necessary
+
+scenarios
+in
+which
+clients
+need
+
+to
+use
+multiple
+security
+scheme
+definitions.
+
+retrieve
+the
+collection
+in
+small
+subsets
+of
+TDs.
+While
+the
+Search
+API
+(
+
+Example
+21
+
+
+7.3.2.3
+
+
+Search
+API
+
+
+{
+ ...
+ "securityDefinitions": {
+ : {
+ : <span class=
+"hljs-string">"apikey",
+ : <span class=
+"hljs-string">"body",
+ : <span class=
+"hljs-string">"/auth/key"
+ }
+ },
+ "security": ,
+ ...
+ : {
+ : {
+ ...
+ : <span class=
+"hljs-string">"object",
+ : {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"number",
+ ...
+ },
+ "rgb": {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"array",
+ ...
+ },
+ "auth": {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"object",
+ <span class=
+"hljs-string">"properties": {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"string"
+ }
+ },
+ "required": [<span class=
+"hljs-string">"key"]
+ }
+ },
+ "required": [<span class=
+"hljs-string">"brightness", <span class=
+"hljs-string">"rgb", <span class=
+"hljs-string">"auth"],
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://example.com/color",
+ ...
+ }]
+ }
+ },
+ "action": {
+ : {
+ ...
+ : {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"object",
+ <span class=
+"hljs-string">"properties": {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"string"
+ }
+ },
+ "required": [<span class=
+"hljs-string">"key"]
+ }
+ },
+ "required": [],
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://example.com/on",
+ ...
+ }]
+ },
+ "off": {
+ ...
+ : {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"object",
+ <span class=
+"hljs-string">"properties": {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"string"
+ }
+ },
+ "required": [<span class=
+"hljs-string">"key"]
+ }
+ },
+ "required": [],
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://example.com/off",
+ ...
+ }]
+ }
+ },
+ ...
+}
+However,
+it
+is
+rather
+annoying
+and
+redundant
+to
+add
+
+)
+does
+offer
+
+the
+security
+information
+to
+every
+data
+schema.
+It
+is
+possible
+
+ability
+
+to
+simplify
+this
+example
+by
+using
+the
+feature
+that
+the
+location
+referenced
+by
+a
+JSON
+pointer
+in
+
+query
+
+a
+body
+location
+will
+be
+automatically
+inserted
+if
+
+specific
+range,
+
+it
+does
+
+may
+
+not
+exist.
+In
+this
+case
+the
+above
+example
+can
+
+be
+simplified
+
+optimal,
+nor
+developer-friendly.
+
+The
+pagination
+must
+
+be
+created
+for
+the
+actions
+
+based
+
+on
+and
+off
+to
+hold
+just
+
+the
+security
+information.
+Example
+22
+{
+ ...
+ "securityDefinitions": {
+ : {
+ : <span class=
+"hljs-string">"apikey",
+ : <span class=
+"hljs-string">"body",
+ : <span class=
+"hljs-string">"/auth/key"
+ }
+ },
+ "security": ,
+ ...
+ : {
+ : {
+ ...
+ : <span class=
+"hljs-string">"object",
+ : {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"number",
+ ...
+ },
+ "rgb": {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"array",
+ ...
+ }
+ },
+ "required": [<span class=
+"hljs-string">"brightness", <span class=
+"hljs-string">"rgb"],
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://example.com/color",
+ ...
+ }]
+ }
+ },
+ "action": {
+ : {
+ ...
+ <span class=
+"hljs-string">"required": [<span class=
+"hljs-string">"auth"],
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://example.com/on",
+ ...
+ }]
+ },
+ "off": {
+ ...
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"https://example.com/off",
+ ...
+ }]
+ }
+ },
+ ...
+}
+6.3.5
+properties
+
+following
+rules:
+
-
+
The
+value
+assigned
+to
+properties
+in
+a
+
+
+
+-
+
All
+name-value
+pairs
+of
+an
+instance
+
+
+Moreover,
+it
+may
+include
+additional
+arguments
+that
+are
+necessary
+for
+ordering
+or
+session
+management.
+ -
+
+The
+link
+may
+be
+absolute
+or
+relative
+to
+directory
+API's
+base
+URL.
+The
+
+
+ActionAffordance
+
+etag
+
+
+MUST
+
+value
+could
+
+be
+serialized
+as
+JSON
+objects.
+They
+
+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
+Class
+
+
+DataSchema
+
+etag
+
+
+,
+whose
+serialization
+is
+defined
+in
+6.3.10
+Data
+Schemas
+.
+The
+
+value
+assigned
+
+to
+forms
+in
+an
+instance
+
+know
+whether
+the
+collection
+remains
+consistent
+across
+paginated
+retrieval
+
+of
+ActionAffordance
+
+the
+collection.
+For
+example,
+creation
+or
+deletion
+of
+TDs
+or
+update
+of
+TD
+fields
+used
+for
+ordering
+may
+make
+shift
+the
+calculated
+paging
+window.
+ -
+
...
+"actions": {
+ : {
+ : <span class=
+"hljs-string">"Fade in/out",
+ <span class=
+"hljs-string">"description",
+ : {
+ : <span class=
+"hljs-string">"object",
+ : {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"integer",
+ <span class=
+"hljs-string">"minimum",
+ <span class=
+"hljs-string">"maximum": <span class=
+"hljs-number">100
+ },
+ "": {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"integer",
+ <span class=
+"hljs-string">"minimum",
+ <span class=
+"hljs-string">"maximum": <span class=
+"hljs-number">100
+ },
+ "duration": {<span class=
+"hljs-string">"type": <span class=
+"hljs-string">"number"}
+ },
+ "required": [<span class=
+"hljs-string">"to",<span class=
+"hljs-string">"duration"]
+ },
+ "output": {<span class=
+"hljs-string">"type": <span class=
+"hljs-string">"string"},
+ "forms": [...]
+ }
+},
+...
+6.3.7
+
+
+All
+name-value
+pairs
+of
+an
+instance
+of
+EventAffordance
+,
+where
+the
+name
+is
+a
+Vocabulary
+Term
+included
+in
+(one
+of)
+
+
+The
+values
+assigned
+to
+subscription
+,
+data
+,
+and
+cancellation
+in
+an
+instance
+of
+EventAffordance
+
+
+...
+"events": {
+ : {
+ : {
+ : <span class=
+"hljs-string">"string"
+ },
+ "forms": [...]
+ }
+},
+...
+
+
+
+
+Event
+affordances
+have
+been
+defined
+in
+
+This
+above
+specification
+follows
+
+a
+flexible
+manner,
+in
+order
+to
+adopt
+existing
+(e.g.,
+WebSub
+[
+websub
+])
+or
+customer-oriented
+event
+mechanisms
+(e.g.,
+Webhooks).
+For
+this
+reason,
+subscription
+and
+cancellation
+can
+be
+defined
+according
+to
+the
+desired
+mechanism.
+Please
+find
+further
+details
+in
+
+subset
+of
+Linked
+Data
+Paging
+
+[
+
+WOT-BINDING-TEMPLATES
+
+
+LDP-Paging
+
+
+
+].
+Example
+A.3
+Webhook
+Event
+Example
+illustrates
+how
+Events
+can
+use
+subscription
+and
+cancellation
+
+]
+
+to
+describe
+Webhooks.
+6.3.8
+links
+All
+name-value
+pairs
+of
+an
+instance
+
+allow
+optional
+pagination
+
+of
+Link
+,
+where
+the
+name
+is
+a
+Vocabulary
+Term
+included
+in
+
+the
+Signature
+
+JSON-LD
+array.
+Additional
+parts
+
+of
+Link
+,
+MUST
+
+Linked
+Data
+Paging
+may
+
+be
+serialized
+as
+members
+of
+the
+JSON
+object
+that
+results
+from
+serializing
+the
+Link
+instance,
+with
+the
+Vocabulary
+Term
+as
+name.
+It
+is
+recommended
+to
+follow
+the
+link
+relation
+values
+as
+provided
+in
+Section
+5.3.4.1
+Link
+.
+The
+
+implemented
+for
+
+examples
+provided
+below
+demonstrate
+the
+use
+of
+different
+
+to
+honour
+client's
+query
+preference
+or
+to
+add
+other
+
+link
+relation
+types.
+
+relations
+for
+semantic
+annotation
+and
+alternative
+navigation
+links.
+
+
+
+A
+reference
+can
+be
+provided
+that
+points
+to
+a
+Thing
+(e.g.,
+
+The
+following
+example
+provides
+
+a
+controller)
+that
+controls
+
+walk-through
+of
+
+the
+underlying
+unit
+(e.g.,
+a
+lamp).
+For
+this
+controlledBy
+can
+be
+used:
+
+paginated
+retrieval
+of
+TDs:
+
+
+
+
+In
+such
+a
+case,
+
+
+
+
+The
+serialization
+of
+each
+value
+in
+the
+map
+assigned
+to
+uriVariables
+in
+an
+instance
+of
+Form
+MUST
+rely
+on
+the
+Class
+DataSchema
+,
+whose
+serialization
+
+alternative
+pagination
+format
+
+is
+defined
+in
+6.3.10
+Data
+Schemas
+
+derived
+from
+
+Hydra
+Advanced
+Concepts
+,
+more
+concretely
+the
+
+Partial
+Collection
+View
+
+.
+A
+TD
+snippet
+
+Adapted
+to
+our
+purposes
+and
+
+using
+a
+URI
+Template
+
+the
+
+members
+
+field
+to
+accomodate
+the
+array
+of
+TDs,
+it
+looks
+as
+follows
+
+for
+query
+parameters
+and
+uriVariables
+in
+
+the
+Interaction
+Affordance
+level
+is
+given
+below:
+
+listing
+endpoint:
+
+
+
+
+Alternatively,
+as
+defined
+in
+[
+RFC6570
+],
+
+To
+tell
+the
+server
+which
+format
+to
+send,
+the
+additional
+query
+parameter
+
+
+uriVariables
+
+?format=array|collection
+
+
+can
+be
+used
+for
+replacing
+
+added
+to
+
+the
+request.
+
+
+href
+
+?format=array
+
+
+structure.
+An
+example
+TD
+
+is
+provided
+below
+where
+a
+valid
+request
+to
+get
+
+the
+forecast
+of
+Bogota,
+Colombia
+would
+be
+an
+HTTP
+GET
+request
+
+default
+parameter,
+does
+not
+have
+
+to
+http://example.org/weather/bogota
+:
+Example
+32
+{
+ : <span class=
+"hljs-string">"http://www.w3.org/ns/td",
+ ...
+ : {
+ : {
+ ...
+ : {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"string",
+ <span class=
+"hljs-string">"description": <span class=
+"hljs-string">"City name to find the weather information for"
+ }
+ },
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"http://example.org/weather/{city}",
+ <span class=
+"hljs-string">"htv:methodName": <span class=
+"hljs-string">"GET"
+ }]
+ },
+ ...
+ },
+ ...
+}
+The
+two
+examples
+below
+can
+
+be
+also
+combined,
+while
+using
+
+provided
+explicitly,
+and
+yields
+to
+a
+server
+response
+of
+
+the
+same
+
+pure
+array
+of
+TDs.
+
+
+uriVariables
+
+?format=collection
+
+
+feature.
+An
+HTTP
+GET
+request
+
+should
+yield
+
+to
+http://example.org/weather/bogota/?unit=Celsius
+can
+be
+described
+
+a
+server
+response
+with
+the
+format
+
+as
+follows:
+
+described
+in
+
+Example
+
+33
+
+8
+
+
+{
+ : <span class=
+"hljs-string">"http://www.w3.org/ns/td",
+ ...
+ : {
+ : {
+ ...
+ : {
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"string",
+ <span class=
+"hljs-string">"description": <span class=
+"hljs-string">"City name to find the weather information for"
+ },
+ : {
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"string",
+ <span class=
+"hljs-string">"enum":[<span class=
+"hljs-string">"Fahrenheit",<span class=
+"hljs-string">"Celsius"],
+ <span class=
+"hljs-string">"description": <span class=
+"hljs-string">"Desired unit for the temperature value"
+ }
+ },
+ : [{
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"http://example.org/weather/{city}/{?unit}",
+ <span class=
+"hljs-string">"htv:methodName": <span class=
+"hljs-string">"GET"
+ }]
+ },
+ ...
+ },
+ ...
+}
+
+.
+
+
+uriVariables
+are
+mainly
+for
+properties
+and
+events.
+When
+retrofitting
+an
+existing
+system,
+it
+may
+be
+necessary
+to
+use
+uriVariables
+for
+actions.
+In
+general,
+it
+
+The
+listing
+operation
+
+is
+recommended
+to
+avoid
+
+specified
+as
+
+
+uriVariables
+
+things
+
+
+as
+much
+as
+possible
+when
+a
+new
+WoT-based
+system
+is
+designed.
+
+property
+in
+
+7.3.2.4
+
+API
+Specification
+(Thing
+Model)
+.
+
+
+
+
+
+
+The
+contentType
+member
+
+syntactic
+validation
+of
+TD
+objects
+before
+storage
+
+is
+used
+
+
+RECOMMENDED
+
+to
+assign
+a
+media
+type
+
+prevent
+common
+erroneous
+submissions.
+
+The
+server
+
+SHOULD
+
+use
+at
+least
+
+Minimal
+Validation
+
+as
+defined
+in
+
+[
+
+RFC2046
+
+
+wot-thing-description11
+
+
+
+]
+to
+validate
+TDs,
+
+including
+media
+type
+parameters
+as
+attribute-value
+pairs
+separated
+by
+a
+;
+character.
+Example:
+Example
+34
+...
+: <span class=
+"hljs-string">"text/plain; charset=utf-8",
+...
+6.3.9.3
+response
+In
+some
+
+use
+cases,
+the
+form
+metadata
+
+of
+the
+Interaction
+Affordance
+
+
+WoT
+Thing
+Description
+(1.0)
+JSON
+Schema
+
+
+not
+only
+describes
+the
+request,
+but
+also
+provides
+metadata
+for
+
+or
+
+WoT
+Thing
+Description
+1.1
+JSON
+Schema
+,
+and
+
+the
+expected
+response.
+For
+instance,
+an
+Action
+takePhoto
+defines
+an
+input
+
+JSON
+
+schema
+to
+submit
+parameter
+settings
+of
+a
+camera
+(aperture
+priority,
+timer,
+etc.)
+using
+
+defined
+in
+
+A.
+
+JSON
+Schema
+for
+WoT
+Discovery
+TD-extensions
+
+for
+
+Enriched
+TDs
+,
+as
+appropriate
+based
+on
+
+the
+request
+payload
+(i.e.,
+"contentType":
+"application/json"
+).
+The
+output
+
+value
+
+of
+this
+action
+is
+the
+photo
+taken,
+which
+is
+available
+in
+JPEG
+format,
+for
+example.
+In
+such
+cases,
+
+the
+
+response
+member
+is
+used
+
+@context
+.
+Additional
+forms
+of
+validation
+can
+be
+added
+
+to
+indicate
+the
+representation
+format
+
+support
+various
+use
+cases.
+For
+example,
+a
+use
+case
+may
+require
+stateful
+validation
+
+of
+the
+response
+payload
+(e.g.,
+"contentType":
+"image/jpeg"
+).
+Here
+no
+
+input
+TDs
+to
+ensure
+that
+the
+
+
+output
+
+version
+
+
+schema
+
+value
+
+is
+required,
+as
+the
+content
+type
+fully
+specifies
+the
+representation
+format.
+
+initialized
+and
+updated
+according
+to
+pre-defined
+rules.
+
+
+
+
+If
+present,
+
+the
+value
+assigned
+
+server
+fails
+
+to
+response
+in
+an
+instance
+of
+Form
+MUST
+be
+a
+JSON
+object.
+If
+present,
+
+validate
+
+the
+response
+object
+
+TD
+object,
+it
+
+
+MUST
+
+contain
+a
+contentType
+member
+as
+defined
+in
+
+inform
+
+the
+Class
+definition
+of
+ExpectedResponse
+.
+A
+form
+snippet
+
+client
+
+with
+necessary
+details
+to
+identify
+and
+resolve
+
+the
+response
+member
+is
+shown
+below
+based
+on
+the
+takePhoto
+Action
+
+errors.
+
+The
+validation
+error
+
+MUST
+
+be
+
+described
+above:
+Example
+35
+{
+ ...
+ "actions": {
+ : {
+ ...
+ : [{
+ : <span class=
+"hljs-string">"invokeaction",
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"http://camera.example.com/api/snapshot",
+ <span class=
+"hljs-string">"contentType": <span class=
+"hljs-string">"application/json",
+ : {
+ <span class=
+"hljs-string">"contentType": <span class=
+"hljs-string">"image/jpeg"
+ }
+ }]
+ }
+ },
+ ...
+}
+6.3.9.4
+contentMediaType
+and
+contentEncoding
+
+as
+Problem
+Details
+[
+
+
+RFC7807
+
+
+In
+some
+cases
+binary
+data
+is
+embedded
+in
+text-based
+values,
+e.g.,
+a
+JSON
+string-based
+value
+embeds
+a
+base64
+encoded
+image.
+The
+terms
+contentMediaType
+and
+
+
+]
+with
+an
+extension
+field
+called
+
+
+contentEncoding
+can
+be
+used
+
+validationErrors
+,
+set
+
+to
+clarify
+the
+context
+and
+encoding
+format
+of
+such
+name-value
+pairs.
+A
+sample
+usage
+
+an
+array
+
+of
+objects
+with
+
+
+contentMediaType
+
+field
+
+
+and
+
+contentEncoding
+is
+shown
+below:
+Example
+36
+{
+ ...
+ "properties": {
+ : {
+ <span class=
+"hljs-string">"description": <span class=
+"hljs-string">"Provides latest image",
+ <span class=
+"hljs-string">"type": <span class=
+"hljs-string">"string",
+ <span class=
+"hljs-string">"contentMediaType": <span class=
+"hljs-string">"image/png",
+ <span class=
+"hljs-string">"contentEncoding": <span class=
+"hljs-string">"base64",
+ : [{
+ <span class=
+"hljs-string">"op": <span class=
+"hljs-string">"readproperty",
+ <span class=
+"hljs-string">"href": <span class=
+"hljs-string">"coaps://mylamp.example.com/lastPicture",
+ <span class=
+"hljs-string">"cov:methodName": <span class=
+"hljs-string">"GET",
+ <span class=
+"hljs-string">"contentType": <span class=
+"hljs-string">"application/json"
+ }]
+ }
+ },
+ ...
+}
+6.3.9.5
+Top
+level
+forms
+When
+forms
+
+description
+
+
+fields.
+
+This
+
+is
+present
+at
+the
+top
+level,
+it
+can
+be
+used
+
+necessary
+
+to
+describe
+meta
+interactions
+offered
+by
+a
+Thing
+.
+For
+example,
+the
+operation
+types
+readallproperties
+and
+writeallproperties
+are
+for
+meta
+interactions
+with
+a
+Thing
+by
+which
+Consumers
+can
+read,
+write
+or
+observe
+all
+properties
+at
+once.
+In
+
+represent
+
+the
+example
+below,
+
+error
+in
+
+a
+forms
+member
+is
+included
+
+machine-readable
+way.
+
+All
+validation
+error
+responses
+described
+using
+Problem
+Details
+
+MUST
+
+be
+encoded
+using
+UTF-8.
+
+Validation
+error
+responses
+
+MAY
+
+report
+details
+
+in
+different
+languages
+using
+proactive
+negotiation,
+if
+
+the
+TD
+root
+object
+and
+the
+Consumer
+can
+use
+the
+submission
+target
+
+
+https://mylamp.example.com/properties
+both
+to
+read
+or
+write
+all
+Properties
+(i.e.,
+on
+,
+brightness
+,
+and
+timer
+
+Accept-Language
+
+
+)
+of
+
+header
+field
+has
+been
+set
+in
+
+the
+Thing
+
+HTTP
+request
+[
+
+RFC7231
+
+
+in
+a
+single
+protocol
+transaction.
+
+
+].
+
+
+
+
+Example
+
+37
+
+9
+
+
+
+{
+ ...
+ "properties": {
+ : {
+ : <span class=
+"hljs-string">"boolean",
+ : [...]
+ },
+ "brightness": {
+ : <span class=
+"hljs-string">"number",
+ : [...]
+ },
+ "timer": {
+ : <span class=
+"hljs-string">"integer",
+ : [...]
+ }
+ },
+ ...
+ "forms": [{
+ : <span class=
+"hljs-string">"readallproperties",
+ : <span class=
+"hljs-string">"https://mylamp.example.com/properties",
+ <span class=
+"hljs-string">"contentType",
+ <span class=
+"hljs-string">"htv:methodName": <span class=
+"hljs-string">"GET"
+ },
+ {
+ "op": <span class=
+"hljs-string">"writeallproperties",
+ : <span class=
+"hljs-string">"https://mylamp.example.com/properties",
+ <span class=
+"hljs-string">"contentType",
+ <span class=
+"hljs-string">"htv:methodName": <span class=
+"hljs-string">"PUT"
+ }]
+}
+Thing-level
+uriVariables
+can
+be
+used
+here
+to
+supply
+further
+variables
+to
+the
+operation
+or
+to
+specify
+a
+list
+of
+Property
+Affordance
+names
+for
+a
+readmultipleproperties
+operation.
+In
+the
+
+is
+an
+
+example
+below,
+the
+unit
+for
+the
+properties
+can
+be
+set
+via
+such
+a
+variable
+and
+the
+desired
+list
+of
+properties
+can
+be
+set:
+
+error
+response
+with
+two
+validation
+errors.
+
+
+
+
+
+
+
+Issue
+99
+:
+Define
+requirements
+and
+add
+section
+for
+validation
+
+
+
For
+
+
+How
+much
+validation
+does
+
+a
+readmultipleproperties
+operation,
+an
+example
+HTTP
+GET
+request
+
+directory
+need
+
+to
+the
+URI
+https://mylamp.example.com/properties?propertyNames=humidity,temperature&unitSystem=metric
+would
+return
+the
+values
+humidity
+and
+temperature
+Property
+Affordances,
+with
+the
+metric
+System
+of
+Measurement.
+
+do?
+
+
+
In
+the
+case
+of
+operation
+type
+writeallproperties
+,
+it
+is
+expected
+that
+the
+Consumer
+provides
+all
+writable
+(non
+readOnly
+)
+properties
+and
+the
+(new)
+assigned
+values
+(e.g.,
+within
+payload).
+Similarly,
+for
+the
+writemultipleproperties
+operation
+type,
+
+
+-
+If
+
+it
+only
+supports
+syntactic
+queries,
+
+is
+
expected
+that
+the
+Consumer
+provides
+writable
+(non
+readOnly
+)
+properties.
+On
+the
+Thing
+side,
+Thing
+is
+expected
+
+JSONSchema
+validation
+sufficient?
+Do
+we
+also
+use
+SHACL?
+ -
+If
+we
+support
+SPARQL,
+do
+we
+need
+
+to
+
return
+readable
+(non
+writeOnly
+)
+properties
+in
+
+do
+more
+to
+make
+sure
+
+the
+case
+
+ontologies
+used
+are
+correct?
+ -
+Is
+there
+a
+subset
+
+of
+
readmultipleproperties
+and
+readallproperties
+operation
+types.
+
+TD
+assertions
+we
+should
+check?
+
+Per
+default
+
+A
+template
+for
+
+the
+API
+of
+
+Thing
+Description
+supports
+the
+Protocol
+Binding
+based
+on
+HTTP
+by
+including
+the
+HTTP
+RDF
+vocabulary
+definitions
+from
+HTTP
+Vocabulary
+in
+RDF
+1.0
+[
+HTTP-in-RDF10
+].
+This
+vocabulary
+can
+
+Directories
+is
+given
+here
+as
+a
+
+Thing
+Model
+.
+The
+Thing
+Model
+is
+normative
+(except
+where
+noted)
+but
+should
+not
+
+be
+directly
+used
+within
+TD
+instances
+by
+the
+usage
+of
+
+considered
+as
+
+the
+prefix
+htv
+,
+which
+points
+
+sole
+reference
+
+to
+http://www.w3.org/2011/http#
+.
+Further
+details
+of
+Protocol
+Binding
+based
+on
+HTTP
+can
+be
+found
+in
+[
+WOT-BINDING-TEMPLATES
+].
+To
+
+implement
+or
+
+interact
+with
+a
+Thing
+that
+implements
+the
+Protocol
+Binding
+based
+on
+HTTP,
+a
+Consumer
+needs
+to
+know
+what
+HTTP
+method
+to
+use
+when
+submitting
+a
+form.
+In
+the
+general
+case,
+a
+
+Thing
+Description
+can
+explicitly
+include
+a
+term
+indicating
+the
+method,
+i.e.,
+htv:methodName
+.
+For
+the
+sake
+of
+conciseness,
+the
+Protocol
+Binding
+based
+on
+HTTP
+defines
+Default
+Values
+for
+the
+operation
+types
+listed
+below,
+which
+
+Directory.
+Please
+refer
+
+also
+aims
+at
+convergence
+of
+the
+methods
+expected
+by
+Things
+(e.g.,
+GET
+to
+read,
+PUT
+
+to
+write).
+When
+no
+method
+is
+indicated
+in
+a
+form
+representing
+an
+Protocol
+Binding
+based
+on
+HTTP,
+a
+Default
+Value
+MUST
+be
+assumed
+as
+shown
+in
+
+the
+following
+table.
+
+specifications
+given
+in
+
+
+7.3.2
+
+Directory
+Service
+API
+.
+
+Vocabulary
+term
+Default
+value
+Context
+htv:methodName
+GET
+Form
+with
+operation
+type
+readproperty
+,
+readallproperties
+,
+readmultipleproperties
+htv:methodName
+PUT
+Form
+with
+operation
+type
+writeproperty
+,
+writeallproperties
+,
+writemultipleproperties
+htv:methodName
+POST
+
+
+The
+
+
+Form
+
+searchJSONPath
+
+
+with
+operation
+type
+
+and
+
+
+invokeaction
+
+searchXPath
+
+
+For
+example,
+the
+Example
+1
+
+affordances
+given
+
+in
+1.
+Introduction
+does
+
+this
+Thing
+Model
+are
+
+not
+contain
+operation
+types
+
+normative
+
+and
+HTTP
+methods
+in
+the
+forms.
+The
+following
+Default
+Values
+should
+be
+assumed
+
+are
+provided
+
+for
+the
+forms
+in
+the
+Example
+1
+:
+
+information
+only.
+
+
+Example
+49
+with
+default
+values
+for
+Protocol
+Binding
+based
+on
+HTTP
+{
+ : <span class=
+"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
+ : <span class=
+"hljs-string">"urn:dev:ops:32473-WoTLamp-1234",
+
+{
+ "@context": [
+ "http://www.w3.org/ns/td",
+ "hljs-string">"https://w3c.github.io/wot-discovery/context/discovery-context.jsonld"
+ ],
+ "@type": [ "tm:ThingModel", "ThingDirectory"
+ ],
+
+ "title": "hljs-string">"MyLampThing",
+ : {
+ : {
+ : <span class=
+"hljs-string">"basic",
+ : <span class=
+"hljs-string">"header"
+ }
+
+"hljs-string">"Thing Description Directory (TDD) Thing Model",
+ "version": { "model":
+"hljs-string">"1.0.0-beta.2"
+
+ },
+ : [
+
+
+ "base": "hljs-string">"{{DIRECTORY_BASE_URL}}",
+ "tm:required": [ "#/properties/things"
+ ],
+ "properties": {
+ : {
+ : <span class=
+
+ "things": {
+ "hljs-attr">"description": "Retrieve all Thing Descriptions",
+ "uriVariables": { "offset": {
+"hljs-attr">"title": "Number of TDs to skip before the page",
+
+"hljs-attr">"type": "number",
+
+"hljs-attr">"default": 0
+ },
+ "limit": {
+"hljs-attr">"title": "Number of TDs in a page",
+
+"hljs-attr">"type": "number"
+ },
+ "format": {
+"hljs-attr">"title": "Payload format",
+
+"hljs-attr">"type":
+"hljs-string">"string",
+ : <span class=
+"hljs-literal">true,
+
+ "enum": [
+ "array",
+ "hljs-string">"collection"
+ ],
+
+"hljs-attr">"default": "array"
+ },
+ "sort_by": {
+"hljs-attr">"title": "Comparator TD attribute for collection sorting",
+
+"hljs-attr">"type": "string",
+
+"hljs-attr">"default": "id"
+ },
+ "sort_order": {
+"hljs-attr">"title": "Sorting order",
+
+"hljs-attr">"type": "string",
+ "enum": [ "asc", "desc"
+ ],
+
+"hljs-attr">"default": "asc"
+ }
+ },
+
+ "forms": [
+ {
+ "hljs-attr">"op": <span class=
+"hljs-string">"readproperty",
+ <span class=
+
+"hljs-attr">"href": "hljs-string">"https://mylamp.example.com/status"
+
+"hljs-string">"/things{?offset,limit,format,sort_by,sort_order}",
+
+"hljs-attr">"htv:methodName": "GET",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"htv:statusCodeValue": 200,
+
+"hljs-attr">"contentType": "application/ld+json",
+
+"hljs-attr">"htv:headers": [
+ {
+
+"hljs-attr">"htv:fieldName": "Link"
+ }
+ ]
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "Invalid query arguments",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 400
+ }
+ ]
+
+ }
+ ]
+ }
+ },
+ "actions": {
+ : {
+
+ "createThing": {
+ "hljs-attr">"description": "Create a Thing Description",
+ "uriVariables": { "id": {
+"hljs-attr">"@type": "ThingID",
+
+"hljs-attr">"title": "Thing Description ID",
+
+"hljs-attr">"type": "string",
+
+"hljs-attr">"format": "iri-reference"
+ }
+ },
+ "input": {
+"hljs-attr">"description": "The schema is implied by the content type",
+ "type":
+"hljs-string">"object"
+ },
+
+ "forms": [
+ {
+ "href": "hljs-string">"https://mylamp.example.com/toggle"
+
+"hljs-string">"/things/{id}",
+
+"hljs-attr">"htv:methodName": "PUT",
+
+"hljs-attr">"contentType": "application/td+json",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"htv:statusCodeValue": 201
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "Invalid serialization or TD",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 400
+ }
+ ]
+
+ }
+ ]
+ }
+ },
+ : {
+ : {
+ : {
+
+ },
+ "createAnonymousThing": {
+"hljs-attr">"description": "Create an anonymous Thing Description",
+ "input": {
+"hljs-attr">"description": "The schema is implied by the content type",
+
+ "type": "hljs-string">"string"
+
+"hljs-string">"object"
+
+ },
+ "forms": [
+ {
+ "href": "hljs-string">"https://mylamp.example.com/oh",
+
+"hljs-string">"/things",
+
+ "hljs-attr">"subprotocol": <span class=
+"hljs-string">"longpoll"
+
+"hljs-attr">"htv:methodName": "POST",
+
+"hljs-attr">"contentType": "application/td+json",
+ "response": {
+"hljs-attr">"description": "Success response including the system-generated URI",
+
+"hljs-attr">"htv:headers": [
+ {
+
+"hljs-attr">"description": "System-generated URI",
+
+"hljs-attr">"htv:fieldName": "Location"
+ }
+ ],
+
+"hljs-attr">"htv:statusCodeValue": 201
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "Invalid serialization or TD",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 400
+ }
+ ]
+
+ }
+ ]
+ }
+ }
+}
+{
+ : <span class=
+"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
+ : <span class=
+"hljs-string">"urn:dev:ops:32473-WoTLamp-1234",
+ : <span class=
+"hljs-string">"MyLampThing",
+ : {
+ : {
+ : <span class=
+"hljs-string">"basic",
+ : <span class=
+"hljs-string">"header"
+ }
+ },
+ : [
+
+ ],
+ : {
+ : {
+ : <span class=
+
+ },
+ "retrieveThing": {
+"hljs-attr">"description": "Retrieve a Thing Description",
+ "uriVariables": { "id": {
+"hljs-attr">"@type": "ThingID",
+
+"hljs-attr">"title": "Thing Description ID",
+
+"hljs-attr">"type":
+"hljs-string">"string",
+ : <span class=
+
+ "hljs-attr">"format": "iri-reference"
+ }
+ },
+ "output": {
+"hljs-attr">"description": "The schema is implied by the content type",
+ "type":
+"hljs-string">"object"
+ },
+ "safe":
+"hljs-literal">true,
+
+"hljs-attr">"idempotent":
+"hljs-literal">true,
+ "forms": [
+ {
+ "hljs-attr">"op": <span class=
+"hljs-string">"readproperty",
+
+"hljs-attr">"href": "/things/{id}",
+
+"hljs-attr">"htv:methodName": "GET",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"htv:statusCodeValue": 200,
+
+"hljs-attr">"contentType": "application/td+json"
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "TD with the given id not found",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 404
+ }
+ ]
+ }
+ ]
+ },
+ "updateThing": {
+"hljs-attr">"description": "Update a Thing Description",
+ "uriVariables": { "id": {
+"hljs-attr">"@type": "ThingID",
+
+"hljs-attr">"title": "Thing Description ID",
+
+"hljs-attr">"type": "string",
+
+"hljs-attr">"format": "iri-reference"
+ }
+ },
+ "input": {
+"hljs-attr">"description": "The schema is implied by the content type",
+ "type":
+"hljs-string">"object"
+ },
+ "forms": [
+ {
+
+ "href": "hljs-string">"https://mylamp.example.com/status",
+
+"hljs-string">"/things/{id}",
+
+ "htv:methodName": "hljs-string">"GET"
+
+"hljs-string">"PUT",
+
+"hljs-attr">"contentType": "application/td+json",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"htv:statusCodeValue": 204
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "Invalid serialization or TD",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 400
+ }
+ ]
+
+ }
+ ]
+ }
+ },
+ : {
+ : {
+
+ },
+ "partiallyUpdateThing": {
+"hljs-attr">"description": "Partially update a Thing Description",
+ "uriVariables": { "id": {
+"hljs-attr">"@type": "ThingID",
+
+"hljs-attr">"title": "Thing Description ID",
+
+"hljs-attr">"type": "string",
+
+"hljs-attr">"format": "iri-reference"
+ }
+ },
+ "input": {
+"hljs-attr">"description": "The schema is implied by the content type",
+ "type":
+"hljs-string">"object"
+ },
+
+ "forms": [
+ {
+ "hljs-attr">"op": <span class=
+"hljs-string">"invokeaction",
+
+"hljs-attr">"href": "/things/{id}",
+
+"hljs-attr">"htv:methodName": "PATCH",
+
+"hljs-attr">"contentType": "application/merge-patch+json",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"htv:statusCodeValue": 204
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "Invalid serialization or TD",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 400
+ },
+ {
+
+"hljs-attr">"description": "TD with the given id not found",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 404
+ }
+ ]
+ }
+ ]
+ },
+ "deleteThing": {
+"hljs-attr">"description": "Delete a Thing Description",
+ "uriVariables": { "id": {
+"hljs-attr">"@type": "ThingID",
+
+"hljs-attr">"title": "Thing Description ID",
+
+"hljs-attr">"type": "string",
+
+"hljs-attr">"format": "iri-reference"
+ }
+ },
+ "forms": [
+ {
+
+ "href": "hljs-string">"https://mylamp.example.com/toggle",
+
+"hljs-string">"/things/{id}",
+
+ "htv:methodName": "hljs-string">"POST"
+
+"hljs-string">"DELETE",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"htv:statusCodeValue": 204
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "TD with the given id not found",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 404
+ }
+ ]
+
+ }
+ ]
+ }
+ },
+ : {
+ : {
+ : {
+
+ },
+ "searchJSONPath": {
+"hljs-attr">"description": "JSONPath syntactic search. This affordance is not normative and is provided for information only.",
+ "uriVariables": { "query": {
+"hljs-attr">"title": "A valid JSONPath expression",
+
+"hljs-attr">"type": "string"
+ }
+ },
+ "output": {
+"hljs-attr">"description": "The schema depends on the given query",
+
+ "type": "hljs-string">"object"
+ },
+ "safe":
+"hljs-literal">true,
+
+"hljs-attr">"idempotent": true,
+ "forms": [
+ {
+
+"hljs-attr">"href": "/search/jsonpath?query={query}",
+
+"hljs-attr">"htv:methodName": "GET",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"contentType": "application/json",
+
+"hljs-attr">"htv:statusCodeValue": 200
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "JSONPath expression not provided or contains syntax errors",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 400
+ }
+ ]
+ }
+ ]
+ },
+ "searchXPath": {
+"hljs-attr">"description": "XPath syntactic search. This affordance is not normative and is provided for information only.",
+ "uriVariables": { "query": {
+"hljs-attr">"title": "A valid XPath expression",
+
+"hljs-attr">"type":
+"hljs-string">"string"
+ }
+ },
+ "output": {
+"hljs-attr">"description": "The schema depends on the given query",
+ "type":
+"hljs-string">"object"
+
+ },
+ "safe": "hljs-literal">true,
+
+"hljs-attr">"idempotent": true,
+
+ "forms": [
+ {
+ "hljs-attr">"op": <span class=
+"hljs-string">"subscribeevent",
+
+"hljs-attr">"href": "/search/xpath?query={query}",
+
+"hljs-attr">"htv:methodName": "GET",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"contentType": "application/json",
+
+"hljs-attr">"htv:statusCodeValue": 200
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "XPath expression not provided or contains syntax errors",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 400
+ }
+ ]
+ }
+ ]
+ },
+ "searchSPARQL": {
+"hljs-attr">"description": "SPARQL semantic search",
+ "uriVariables": { "query": {
+"hljs-attr">"title": "A valid SPARQL 1.1. query",
+
+"hljs-attr">"type": "string"
+ }
+ },
+ "output": {
+"hljs-attr">"description": "The schema depends on the given query",
+ "type":
+"hljs-string">"object"
+ },
+ "safe":
+"hljs-literal">true,
+
+"hljs-attr">"idempotent": true,
+ "forms": [
+ {
+
+ "href": "hljs-string">"https://mylamp.example.com/oh",
+
+"hljs-string">"/search/sparql?query={query}",
+
+ "hljs-attr">"subprotocol": <span class=
+"hljs-string">"longpoll"
+
+"hljs-attr">"htv:methodName": "GET",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"contentType": "application/json",
+
+"hljs-attr">"htv:statusCodeValue": 200
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "SPARQL query not provided or contains syntax errors",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 400
+ }
+ ]
+ },
+ {
+
+"hljs-attr">"href": "/search/sparql",
+
+"hljs-attr">"htv:methodName": "POST",
+ "response": {
+"hljs-attr">"description": "Success response",
+
+"hljs-attr">"contentType": "application/json",
+
+"hljs-attr">"htv:statusCodeValue": 200
+ },
+
+"hljs-attr">"additionalResponses": [
+ {
+
+"hljs-attr">"description": "SPARQL query not provided or contains syntax errors",
+
+"hljs-attr">"contentType": "application/problem+json",
+
+"hljs-attr">"htv:statusCodeValue": 400
+ }
+ ]
+
+ }
+ ]
+ }
+ }
+}
+In
+the
+case
+of
+a
+forms
+entry
+that
+has
+multiple
+op
+values
+the
+usage
+of
+the
+htv:methodName
+is
+not
+permitted.
+A
+TD
+Processor
+will
+extend
+the
+multiple
+op
+values
+to
+separate
+forms
+entries
+and
+associates
+a
+single
+operation
+with
+the
+default
+assumption.
+The
+address
+information
+(e.g.
+href
+)
+and
+other
+metadata
+are
+taken
+over
+in
+the
+extended
+version.
+Example
+50
+extended
+forms
+in
+case
+of
+multiple
+values
+in
+op
+{
+ : <span class=
+"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
+ : <span class=
+"hljs-string">"urn:dev:ops:32473-WoTLamp-1234",
+ : <span class=
+"hljs-string">"MyLampThing",
+ : {
+ : {
+ : <span class=
+"hljs-string">"basic",
+ : <span class=
+"hljs-string">"header"
+ }
+
+ },
+ : [
+
+ ],
+ : {
+ : {
+ : <span class=
+"hljs-string">"string",
+
+ "events": {
+ "thingCreated": {
+ "hljs-attr">"description": "Registration of Thing Descriptions inside the directory",
+ "uriVariables": { "diff": {
+"hljs-attr">"description": "Receive the full created TD as event data",
+
+"hljs-attr">"type": "boolean"
+ }
+ },
+ "data": {
+"hljs-attr">"title": "Partial/Full TD",
+ "type":
+"hljs-string">"object"
+ },
+
+ "forms": [
+ {
+ "hljs-attr">"op" : [<span class=
+"hljs-string">"readproperty", <span class=
+"hljs-string">"writeproperty"],
+
+"hljs-attr">"op": "subscribeevent",
+
+ "href": "hljs-string">"https://mylamp.example.com/status"
+
+"hljs-string">"/events/thing_created{?diff}",
+
+"hljs-attr">"subprotocol": "sse",
+ "htv:headers": [
+ {
+
+"hljs-attr">"description": "ID of the last event for reconnection",
+
+"hljs-attr">"htv:fieldName": "Last-Event-ID"
+ }
+ ],
+ "response": {
+"hljs-attr">"contentType": "text/event-stream"
+ }
+
+ }
+ ]
+ }
+ }
+}
+{
+ : <span class=
+"hljs-string">"https://www.w3.org/2022/wot/td/v1.1",
+ : <span class=
+"hljs-string">"urn:dev:ops:32473-WoTLamp-1234",
+ : <span class=
+"hljs-string">"MyLampThing",
+ : {
+ : {
+ : <span class=
+"hljs-string">"basic",
+ : <span class=
+"hljs-string">"header"
+ }
+ },
+ : [
+
+ ],
+ : {
+ : {
+ : <span class=
+"hljs-string">"string",
+
+ },
+ "thingUpdated": {
+"hljs-attr">"description": "Updates to Thing Descriptions within the directory",
+ "uriVariables": { "diff": {
+"hljs-attr">"description": "Include TD changes inside event data",
+
+"hljs-attr">"type": "boolean"
+ }
+ },
+ "data": {
+"hljs-attr">"title": "Partial TD",
+ "type":
+"hljs-string">"object",
+
+"hljs-attr">"contentMediaType": "application/merge-patch+json"
+ },
+
+ "forms": [
+ {
+ "op": "hljs-string">"readproperty",
+
+"hljs-string">"subscribeevent",
+
+ "href": "hljs-string">"https://mylamp.example.com/status",
+
+"hljs-string">"/events/thing_updated{?diff}",
+
+ "hljs-attr">"htv:methodName": <span class=
+"hljs-string">"GET"
+ },
+
+"hljs-attr">"subprotocol": "sse",
+ "htv:headers": [
+ {
+
+"hljs-attr">"description": "ID of the last event for reconnection",
+
+"hljs-attr">"htv:fieldName": "Last-Event-ID"
+ }
+ ],
+ "response": {
+"hljs-attr">"contentType": "text/event-stream"
+ }
+ }
+ ]
+ },
+ "thingDeleted": {
+"hljs-attr">"description": "Deletion of Thing Descriptions from the directory",
+ "data": {
+"hljs-attr">"title": "Partial TD",
+ "type":
+"hljs-string">"object"
+ },
+ "forms": [
+ {
+ "op": "hljs-string">"writeproperty",
+
+"hljs-string">"subscribeevent",
+
+ "href": "hljs-string">"https://mylamp.example.com/status",
+
+"hljs-string">"/events/thing_deleted",
+
+ "hljs-attr">"htv:methodName": <span class=
+"hljs-string">"PUT"
+
+"hljs-attr">"subprotocol": "sse",
+ "htv:headers": [
+ {
+
+"hljs-attr">"description": "ID of the last event for reconnection",
+
+"hljs-attr">"htv:fieldName": "Last-Event-ID"
+ }
+ ],
+ "response": {
+"hljs-attr">"contentType": "text/event-stream"
+ }
+
+ }
+ ]
+ }
+ }
+}
+
+
+8.3.2
+Other
+Protocol
+Bindings
+The
+number
+of
+Protocol
+Bindings
+a
+Thing
+can
+implement
+is
+not
+restricted.
+Other
+Protocol
+Bindings
+(e.g.,
+for
+CoAP,
+MQTT,
+or
+OPC
+UA)
+are
+intended
+to
+be
+standardized
+in
+separate
+documents
+such
+as
+a
+protocol
+Vocabulary
+similar
+to
+HTTP
+Vocabulary
+in
+RDF
+1.0
+[
+HTTP-in-RDF10
+]
+or
+specifications
+including
+Default
+Value
+definitions.
+Such
+protocols
+can
+be
+simply
+integrated
+into
+the
+TD
+by
+the
+usage
+of
+the
+TD
+Context
+Extension
+mechanism
+(see
+7.
+TD
+Context
+Extensions
+).
+Please
+refer
+to
+[
+WOT-BINDING-TEMPLATES
+]
+for
+information
+on
+how
+to
+describe
+IoT
+platforms
+and
+ecosystems.
+
+
+
+
+Editor's
+note
+
+:
+Context
+URIs
+
+
+
+Needs
+to
+be
+updated
+to
+include
+points
+noted
+in
+TD
+Issue
+1348
+.
+Note
+that
+separate
+Security
+and
+Privacy
+Consideration
+sections
+
+The
+context
+URIs
+
+are
+now
+required,
+so
+this
+section
+has
+been
+refactored.
+
+tentative
+and
+subject
+to
+change.
+
+
+
+
+
+
+
+