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.

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., dimm a lamp over time).
Sub-class oftd:InteractionAffordance
In the domain oftd:hasInputSchema
td:hasOutputSchema
td:isIdempotent
td:isSafe
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: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:hasForm
td:hasUriTemplateSchema
td:name
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:invokeAction
td:observeProperty
td:readAllProperties
td:readMultipleProperties
td:readProperty
td:subscribeEvent
td:unobserveProperty
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 optionally 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:hasForm
td:hasInteractionAffordance
td:hasSecurityConfiguration

Object Properties

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

hasInteractionAffordance

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

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

hasLink

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

Provides Web links to arbitrary resources that relate to the specified Thing Description.
Range includeshctl:Link

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

Set of security definition names, chosen from those defined in securityDefinitions. These must all be satisfied for access to resources.
Domain includestd: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 as collection based on schema specifications.
Domain includestd:InteractionAffordance

Datatype Properties

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

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

Named Individuals

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

readAllProperties

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

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 read a property value
Instance oftd:OperationType

unobserveProperty

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

Operation type of forms used to read a property value
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

subscribeEvent

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

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

writeProperty

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

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

observeProperty

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

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

invokeAction

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

Operation type of forms used to read 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]]).