Web of Things (WoT) Thing Description (TD) Ontology

W3C Editor's Draft

More details about this document
This version:
https://www.w3.org/2019/wot/td
Latest published version:
none
Latest editor's draft:
https://www.w3.org/2019/wot/td
Editors:
Victor Charpenay (Siemens AG)
Maxime Lefrançois (École des Mines de Saint-Étienne)
María Poveda Villalón (Universidad Politécnica de Madrid)
Sebastian Käbisch (Siemens AG)
Ontology in RDF
Download
Open

Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

Abstract

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.

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

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

This document was published by the Web of Things Working Group as an Editor's Draft.

Publication as an Editor's Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 03 November 2023 W3C Process Document.

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

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

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

4. Axiomatization

4.1 Classes

4.1.1 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 of td:InteractionAffordance
In the domain of td:hasInputSchema
td:hasOutputSchema
td:isIdempotent
td:isSafe
td:isSynchronous
In the range of td:hasActionAffordance

4.1.2 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 of td:InteractionAffordance
In the domain of td:hasCancellationSchema
td:hasNotificationResponseSchema
td:hasNotificationSchema
td:hasSubscriptionSchema
In the range of td:hasEventAffordance

4.1.3 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 of td:ActionAffordance
td:EventAffordance
td:PropertyAffordance
In the domain of td:descriptionInLanguage
td:hasForm
td:hasUriTemplateSchema
td:name
td:titleInLanguage
tm:ref
In the range of td:hasInteractionAffordance

4.1.4 OperationType

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

Enumeration of well-known operation types necessary to implement the WoT interaction model
Enumeration members td: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

4.1.5 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 of td:InteractionAffordance
In the domain of td:isObservable
In the range of td:hasPropertyAffordance

4.1.6 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 of td:baseURI
td:definesSecurityScheme
td:descriptionInLanguage
td:followsProfile
td:hasForm
td:hasInteractionAffordance
td:hasSecurityConfiguration
td:titleInLanguage

4.2 Object Properties

4.2.1 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 includes td:Thing

4.2.2 hasActionAffordance

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

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

4.2.3 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 includes td:EventAffordance

4.2.4 hasEventAffordance

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

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

4.2.5 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 includes td:InteractionAffordance
td:Thing
Range includes hctl:Form

4.2.6 hasInputSchema

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

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

4.2.7 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 includes wotsec:SecurityScheme

4.2.8 hasInteractionAffordance

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

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

4.2.10 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 includes td:EventAffordance

4.2.11 hasNotificationSchema

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

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

4.2.12 hasOutputSchema

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

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

4.2.13 hasPropertyAffordance

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

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

4.2.14 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 includes hctl:Form
td:Thing

4.2.15 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 includes td:EventAffordance

4.2.16 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 includes td:InteractionAffordance

4.3 Datatype Properties

4.3.1 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 includes td:Thing
Range includes schema:URL

4.3.2 description

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

Provides description of the Thing Model element.
Domain includes tm:ThingModel
Range includes schema:Text

4.3.3 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 includes jsonschema:DataSchema
wotsec:SecurityScheme
td:InteractionAffordance
td:Thing
Range includes schema:Text

4.3.4 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 includes td:Thing
Range includes

4.3.5 instance

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

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

4.3.6 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 includes td:ActionAffordance
Range includes schema:Boolean

4.3.7 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 includes td:PropertyAffordance
Range includes schema:Boolean

4.3.8 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 includes td:ActionAffordance
Range includes schema:Boolean

4.3.9 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 includes td:ActionAffordance
Range includes schema:Boolean

4.3.10 model

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

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

4.3.11 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 includes td:InteractionAffordance
Range includes schema:Text

4.3.12 title

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

Provide the title of the Thing Model
Domain includes tm:ThingModel
Range includes schema:Text

4.3.13 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 includes jsonschema:DataSchema
td:InteractionAffordance
td:Thing
Range includes schema:Text

4.4 Annotation Properties

4.4.1 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]).

4.4.2 versionInfo

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

Provides version information.

4.5 Named Individuals

4.5.1 cancelAction

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

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

4.5.2 invokeAction

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

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

4.5.3 observeAllProperties

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

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

4.5.4 observeProperty

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

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

4.5.5 queryAction

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

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

4.5.6 queryAllActions

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

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

4.5.7 readAllProperties

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

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

4.5.8 readMultipleProperties

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

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

4.5.9 readProperty

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

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

4.5.10 subscribeAllEvents

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

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

4.5.11 subscribeEvent

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

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

4.5.12 unobserveAllProperties

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

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

4.5.13 unobserveProperty

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

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

4.5.14 unsubscribeAllEvents

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

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

4.5.15 unsubscribeEvent

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

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

4.5.16 writeAllProperties

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

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

4.5.17 writeMultipleProperties

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

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

4.5.18 writeProperty

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

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

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

5.1 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

5.2 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

6. Usage Examples

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

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

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

6.4 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]).

A. References

A.1 Normative references

[RFC3966]
The tel URI for Telephone Numbers. H. Schulzrinne. IETF. December 2004. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3966
[RFC5134]
A Uniform Resource Name Namespace for the EPCglobal Electronic Product Code (EPC) and Related Standards. M. Mealling. IETF. January 2008. Informational. URL: https://www.rfc-editor.org/rfc/rfc5134
[RFC6068]
The 'mailto' URI Scheme. M. Duerst; L. Masinter; J. Zawinski. IETF. October 2010. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6068
[RFC6570]
URI Template. J. Gregorio; R. Fielding; M. Hadley; M. Nottingham; D. Orchard. IETF. March 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6570
[RFC9112]
HTTP/1.1. R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. IETF. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9112.html
[shacl]
Shapes Constraint Language (SHACL). Holger Knublauch; Dimitris Kontokostas. W3C. 20 July 2017. W3C Recommendation. URL: https://www.w3.org/TR/shacl/
[smartM2M]
ETSI TS 103 264 V2.1.1 (2017-03): SmartM2M; Smart Appliances; Reference Ontology and oneM2M Mapping. ETSI. March 2017. Published. URL: http://www.etsi.org/deliver/etsi_ts/103200_103299/103264/02.01.01_60/ts_103264v020101p.pdf
[vocab-ssn]
Semantic Sensor Network Ontology. Armin Haller; Krzysztof Janowicz; Simon Cox; Danh Le Phuoc; Kerry Taylor; Maxime Lefrançois. W3C. 19 October 2017. W3C Recommendation. URL: https://www.w3.org/TR/vocab-ssn/
[WOT-ARCHITECTURE]
Web of Things (WoT) Architecture. Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/
[WOT-THING-DESCRIPTION]
Web of Things (WoT) Thing Description. Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/