The Thing Description (TD) ontology is an RDF axiomatization of the TD information model, one of the building blocks of the Web of Things (WoT). Besides providing an alternative to the standard JSON representation format for TD documents, the TD ontology can also be used to process contextual information on Things and for alignments with other WoT-related ontologies.

Validation of the document by the Working Group is expected by the end of June 2019.

Introduction

The TD ontology is an idiomatic RDF axiomatization of the TD information model [[WOT-THING-DESCRIPTION]], which can be used to describe WoT things and their interaction affordances. The TD ontology imports the hypermedia controls ontology. However, although the TD information model also includes terms for data schemas and security configurations, the TD ontology does not force the use of the corresponding JSON schema and WoT security vocabularies. Other schema languages like SHACL [[shacl]] can thus be leveraged to describe WoT Things.

Please note that the Turtle version of the ontology can be always obtained by doing content negotiation as explained in Appendix D of the Thing Description Recommendation. You can include Accept: text/turtle in the request to obtain the Turtle version of this ontology.

Terminology

The fundamental WoT terminology such as Thing, Consumer, Thing Description (TD), Interaction Model, Interaction Affordance, Property, Action, Event, Protocol Binding, Servient, etc. is defined in Section 3 of the WoT Architecture specification [[WOT-ARCHITECTURE]].

The Thing Description terminology such as TD Information Model, TD Document, Term (Vocabulary Term), etc. is defined in Section 3 of the WoT Thing Description specification [[WOT-THING-DESCRIPTION]].

Axiomatization

Classes

ActionAffordance

IRI: https://www.w3.org/2019/wot/td#ActionAffordance

An Interaction Affordance that allows to invoke a function of the Thing, which manipulates state (e.g., toggling a lamp on or off) or triggers a process on the Thing (e.g., dim a lamp over time).
Sub-class oftd:InteractionAffordance
In the domain oftd:hasInputSchema
td:hasOutputSchema
td:isIdempotent
td:isSafe
td:isSynchronous
In the range oftd:hasActionAffordance

EventAffordance

IRI: https://www.w3.org/2019/wot/td#EventAffordance

An Interaction Affordance that describes an event source, which asynchronously pushes event data to Consumers (e.g., overheating alerts).
Sub-class oftd:InteractionAffordance
In the domain oftd:hasCancellationSchema
td:hasNotificationResponseSchema
td:hasNotificationSchema
td:hasSubscriptionSchema
In the range oftd:hasEventAffordance

InteractionAffordance

IRI: https://www.w3.org/2019/wot/td#InteractionAffordance

Metadata of a Thing that shows the possible choices to Consumers, thereby suggesting how Consumers may interact with the Thing. There are many types of potential affordances, but W3C WoT defines three types of Interaction Affordances: Properties, Actions, and Events.
Super-class oftd:ActionAffordance
td:EventAffordance
td:PropertyAffordance
In the domain oftd:descriptionInLanguage
td:hasForm
td:hasUriTemplateSchema
td:name
td:titleInLanguage
tm:ref
In the range oftd:hasInteractionAffordance

OperationType

IRI: https://www.w3.org/2019/wot/td#OperationType

Enumeration of well-known operation types necessary to implement the WoT interaction model
Enumeration memberstd:cancelAction
td:invokeAction
td:observeAllProperties
td:observeProperty
td:queryAction
td:queryAllActions
td:readAllProperties
td:readMultipleProperties
td:readProperty
td:subscribeAllEvents
td:subscribeEvent
td:unobserveAllProperties
td:unobserveProperty
td:unsubscribeAllEvents
td:unsubscribeEvent
td:writeAllProperties
td:writeMultipleProperties
td:writeProperty

PropertyAffordance

IRI: https://www.w3.org/2019/wot/td#PropertyAffordance

An Interaction Affordance that exposes state of the Thing. This state can then be retrieved (read) and/or updated (write). Things can also choose to make Properties observable by pushing the new state after a change.
Sub-class oftd:InteractionAffordance
In the domain oftd:isObservable
In the range oftd:hasPropertyAffordance

Thing

IRI: https://www.w3.org/2019/wot/td#Thing

An abstraction of a physical or a virtual entity whose metadata and interfaces are described by a WoT Thing Description, whereas a virtual entity is the composition of one or more Things.
In the domain oftd:baseURI
td:definesSecurityScheme
td:descriptionInLanguage
td:followsProfile
td:hasForm
td:hasInteractionAffordance
td:hasSecurityConfiguration
td:titleInLanguage

Object Properties

definesSecurityScheme

IRI: https://www.w3.org/2019/wot/td#definesSecurityScheme

A Thing may define abstract security schemes, used to configure the secure access of (a set of) affordance(s).
Domain includestd:Thing

hasActionAffordance

IRI: https://www.w3.org/2019/wot/td#hasActionAffordance

All Action-based interaction affordance of the Thing.
Range includestd:ActionAffordance

hasCancellationSchema

IRI: https://www.w3.org/2019/wot/td#hasCancellationSchema

Defines any data that needs to be passed to cancel a subscription, e.g., a specific message to remove a Webhook
Domain includestd:EventAffordance

hasEventAffordance

IRI: https://www.w3.org/2019/wot/td#hasEventAffordance

All Event-based interaction affordance of the Thing.
Range includestd:EventAffordance

hasForm

IRI: https://www.w3.org/2019/wot/td#hasForm

Set of form hypermedia controls that describe how an operation can be performed. Forms are serializations of Protocol Bindings. The array cannot be empty
Domain includestd:InteractionAffordance
td:Thing
Range includeshctl:Form

hasInputSchema

IRI: https://www.w3.org/2019/wot/td#hasInputSchema

Used to define the input data schema of the action.
Domain includestd:ActionAffordance

hasInstanceConfiguration

IRI: https://www.w3.org/2019/wot/td#hasInstanceConfiguration

Instantiation, as used here, is a form of non-symmetric equivalence between a scheme and a configuration: whatever statement on the scheme is also true of the configuration but not vice-versa.
Domain includeswotsec:SecurityScheme

hasInteractionAffordance

IRI: https://www.w3.org/2019/wot/td#hasInteractionAffordance

Offers an affordance to interact with the Thing
Domain includestd:Thing
tm:ThingModel
Range includestd:InteractionAffordance

hasNotificationResponseSchema

IRI: https://www.w3.org/2019/wot/td#hasNotificationResponseSchema

Defines the data schema of the Event response messages sent by the consumer in a response to a data message.
Domain includestd:EventAffordance

hasNotificationSchema

IRI: https://www.w3.org/2019/wot/td#hasNotificationSchema

Defines the data schema of the Event instance messages pushed by the Thing.
Domain includestd:EventAffordance

hasOutputSchema

IRI: https://www.w3.org/2019/wot/td#hasOutputSchema

Used to define the output data schema of the action.
Domain includestd:ActionAffordance

hasPropertyAffordance

IRI: https://www.w3.org/2019/wot/td#hasPropertyAffordance

All Property-based interaction affordance of the Thing.
Range includestd:PropertyAffordance

hasSecurityConfiguration

IRI: https://www.w3.org/2019/wot/td#hasSecurityConfiguration

A security configuration is a a security scheme applied to a (set of) affordance(s).
Domain includeshctl:Form
td:Thing

hasSubscriptionSchema

IRI: https://www.w3.org/2019/wot/td#hasSubscriptionSchema

Defines data that needs to be passed upon subscription, e.g., filters or message format for setting up Webhooks.
Domain includestd:EventAffordance

hasUriTemplateSchema

IRI: https://www.w3.org/2019/wot/td#hasUriTemplateSchema

Define URI template variables according to [[RFC6570]] as collection based on schema specifications. The individual variables DataSchema cannot be an ObjectSchema or an ArraySchema.
Domain includestd:InteractionAffordance

Datatype Properties

baseURI

IRI: https://www.w3.org/2019/wot/td#baseURI

Define the base URI that is used for all relative URI references throughout a TD document. In TD instances, all relative URIs are resolved relative to the base URI using the algorithm defined in [RFC3986]. base does not affect the URIs used in @context and the IRIs used within Linked Data [LINKED-DATA] graphs that are relevant when semantic processing is applied to TD instances.
Domain includestd:Thing
Range includesschema:URL

description

IRI: https://www.w3.org/2019/wot/td#description

Provides description of the Thing Model element.
Domain includestm:ThingModel
Range includesschema:Text

descriptionInLanguage

IRI: https://www.w3.org/2019/wot/td#descriptionInLanguage

description of the TD element (Thing, interaction affordance, security scheme or data schema) with language tag. By convention, a language tag must be added to the object of 'descriptionInLanguage' triples. Otherwise, use 'description'.
Domain includesjsonschema:DataSchema
wotsec:SecurityScheme
td:InteractionAffordance
td:Thing
Range includesschema:Text

followsProfile

IRI: https://www.w3.org/2019/wot/td#followsProfile

Indicates the WoT Profile mechanisms followed by this Thing Description and the corresponding Thing implementation.
Domain includestd:Thing
Range includes

instance

IRI: https://www.w3.org/2019/wot/td#instance

Provides a version identicator of this TD instance.
Domain includestd:versionInfo

isIdempotent

IRI: https://www.w3.org/2019/wot/td#isIdempotent

Indicates whether the action is idempotent (=true) or not. Informs whether the action can be called repeatedly with the same result, if present, based on the same input.
Domain includestd:ActionAffordance
Range includesschema:Boolean

isObservable

IRI: https://www.w3.org/2019/wot/td#isObservable

A hint that indicates whether Servients hosting the Thing and Intermediaries should provide a Protocol Binding that supports the observeproperty and unobserveproperty operations for this Property.
Domain includestd:PropertyAffordance
Range includesschema:Boolean

isSafe

IRI: https://www.w3.org/2019/wot/td#isSafe

Signals if the action is safe (=true) or not. Used to signal if there is no internal state (cf. resource state) is changed when invoking an Action. In that case responses can be cached as example.
Domain includestd:ActionAffordance
Range includesschema:Boolean

isSynchronous

IRI: https://www.w3.org/2019/wot/td#isSynchronous

Indicates whether the action is synchronous (=true) or not. A synchronous action means that the response of action contains all the information about the result of the action and no further querying about the status of the action is needed. Lack of this keyword means that no claim on the synchronicity of the action can be made.
Domain includestd:ActionAffordance
Range includesschema:Boolean

model

IRI: https://www.w3.org/2019/wot/td#model

Provides a version indicator of the underlying TM.
Domain includestd:versionInfo

name

IRI: https://www.w3.org/2019/wot/td#name

Indexing property to store entity names when serializing them in a JSON-LD @index container.
Domain includestd:InteractionAffordance
Range includesschema:Text

title

IRI: https://www.w3.org/2019/wot/td#title

Provide the title of the Thing Model
Domain includestm:ThingModel
Range includesschema:Text

titleInLanguage

IRI: https://www.w3.org/2019/wot/td#titleInLanguage

title of the TD element (Thing, interaction affordance or data schema) with language tag. By convention, a language tag must be added to the object of 'titleInLanguage' triples. Otherwise, use 'title'.
Domain includesjsonschema:DataSchema
td:InteractionAffordance
td:Thing
Range includesschema:Text

Annotation Properties

supportContact

IRI: https://www.w3.org/2019/wot/td#supportContact

Provides information about the TD maintainer as URI scheme (e.g., mailto [[RFC6068]], tel [[RFC3966]], https[[RFC9112]]).

versionInfo

IRI: https://www.w3.org/2019/wot/td#versionInfo

Provides version information.

Named Individuals

cancelAction

IRI: https://www.w3.org/2019/wot/td#cancelAction

Operation type of forms used to cancel an action
Instance oftd:OperationType

invokeAction

IRI: https://www.w3.org/2019/wot/td#invokeAction

Operation type of forms used to read a property value
Instance oftd:OperationType

observeAllProperties

IRI: https://www.w3.org/2019/wot/td#observeAllProperties

Operation type of forms used to observe all property values
Instance oftd:OperationType

observeProperty

IRI: https://www.w3.org/2019/wot/td#observeProperty

Operation type of forms used to observe a property value
Instance oftd:OperationType

queryAction

IRI: https://www.w3.org/2019/wot/td#queryAction

Operation type of forms used to query the status of an action
Instance oftd:OperationType

queryAllActions

IRI: https://www.w3.org/2019/wot/td#queryAllActions

Operation type of forms used to query the status of all actions
Instance oftd:OperationType

readAllProperties

IRI: https://www.w3.org/2019/wot/td#readAllProperties

Operation type of forms used to read all property values
Instance oftd:OperationType

readMultipleProperties

IRI: https://www.w3.org/2019/wot/td#readMultipleProperties

Operation type of forms used to read a property value
Instance oftd:OperationType

readProperty

IRI: https://www.w3.org/2019/wot/td#readProperty

Operation type of forms used to read a property value
Instance oftd:OperationType

subscribeAllEvents

IRI: https://www.w3.org/2019/wot/td#subscribeAllEvents

Operation type of forms used to subscribe to all event types
Instance oftd:OperationType

subscribeEvent

IRI: https://www.w3.org/2019/wot/td#subscribeEvent

Operation type of forms used to read a property value
Instance oftd:OperationType

unobserveAllProperties

IRI: https://www.w3.org/2019/wot/td#unobserveAllProperties

Operation type of forms used to unobserve all property value
Instance oftd:OperationType

unobserveProperty

IRI: https://www.w3.org/2019/wot/td#unobserveProperty

Operation type of forms used to unobserve a property value
Instance oftd:OperationType

unsubscribeAllEvents

IRI: https://www.w3.org/2019/wot/td#unsubscribeAllEvents

Operation type of forms used to unsubscribe from all event types
Instance oftd:OperationType

unsubscribeEvent

IRI: https://www.w3.org/2019/wot/td#unsubscribeEvent

Operation type of forms used to read a property value
Instance oftd:OperationType

writeAllProperties

IRI: https://www.w3.org/2019/wot/td#writeAllProperties

Operation type of forms used to read a property value
Instance oftd:OperationType

writeMultipleProperties

IRI: https://www.w3.org/2019/wot/td#writeMultipleProperties

Operation type of forms used to write a property value
Instance oftd:OperationType

writeProperty

IRI: https://www.w3.org/2019/wot/td#writeProperty

Operation type of forms used to write a property value
Instance oftd:OperationType

Alignments

The TD ontology shares commonalities with other WoT-related vocabularies, in particular with SOSA [[vocab-ssn]] and schema.org. Alignments between these vocabularies are provided in a human-readable way in the following.

SOSA

All alignments with SOSA are also available here in OWL: td-sosa.ttl.

Alignment of td:Thing with SOSA:

Sub-Class Super-Class
td:Thing sosa:Sensor or
sosa:Actuator or
sosa:Platform or
sosa:FeatureOfInterest
td:Thing and
sosa:FeatureOfInterest 		ssn:hasProperty some (
(sosa:isObservedBy some sosa:Sensor) or
(sosa:isActedOnBy some sosa:Actuator)
)
td:Thing and
sosa:Sensor 		sosa:observes some
sosa:ObservableProperty
td:Thing and
sosa:Actuator 		sosa:actsOnProperty some
sosa:ActuatableProperty
td:Thing and
sosa:Platform 		sosa:hosts some (
(
sosa:Sensor and
sosa:observes some
sosa:ObservableProperty
) or (
sosa:Actuator and
sosa:actsOnProperty some
sosa:ActuatableProperty
)
)

Alignment of td:InteractionAffordance with SOSA:

Sub-Class Super-Class
td:PropertyAffordance and
td:hasForm some
hctl:hasOperationType value
td:readProperty 		ssn:forProperty some sosa:ObservableProperty
td:PropertyAffordance and
td:hasForm some
hctl:hasOperationType value
td:writeProperty 		ssn:forProperty some sosa:ActuatableProperty
td:ActionAffordance ssn:forProperty some
sosa:ActuatableProperty
td:EventAffordance ssn:forProperty some
sosa:ObservableProperty

Schema.org

The alignments with schema.org's actions are also available here in OWL: td-sdo.ttl.

Sub-Class Super-Class
td:InteractionAffordance schema:Action and
schema:actionStatus value schema:PotentialActionStatus
Sub-Property Super-Property
td:hasInteractionAffordance schema:potentialAction

Usage Examples

Thing Description JSON-LD 1.1 Instance to RDF Dataset

The following example shows a TD instance from Example 1 Thing Description specification [[WOT-THING-DESCRIPTION]] in JSON-LD 1.1 (JSON-LD 1.1 tab) and in a RDF dataset (RDF tab).

The RDF dataset contains the corresponding Thing Description IRIs as defined in this document. This IRI mapping is provided by the Thing Description context file https://www.w3.org/2019/wot/td/v1. For instance, the field actions is transformed to <https://www.w3.org/2019/wot/td#hasActionAffordance>.

Merging Thing Descriptions

The following example includes two TD documents in the standard TD JSON representation format [[WOT-THING-DESCRIPTION]], identified by a unique electronic product code [[RFC5134]].

If these two documents are being merged together with contextual information in the form of an RDF graph that uses the same identifiers, it is possible to retrieve form metadata of these TDs depending on the relations that exist between Things. Here, the two Things share information on room 101 of some example building.

Internal State of a Thing

It is possible for affordances of different kinds to have the same effect. For instance, an affordance to a writable property may be equivalent to an affordance to invoke an action that changes the property value. Similarly, for every observable property, there may be an equivalent affordance to subscribe to an event that occurs at every property value change.

WoT clients can avoid having to deal with these discrepancies by using the generic td:hasInteractionAffordance predicate. They can then decide to perform an action based solely on the operation type of the form embedded in the affordance object.

Specifying Affordances by Device Classes

It is possible to use the TD ontology to extend the definition of well-known subclasses of Thing by defining expected affordances that Things of such types should present. The following example specifies that every temperature sensor presents an affordance to a temperature property (expressed in the SAREF vocabulary [[smartM2M]]).