Copyright © 2017-2018 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
The Web of Things (WoT) provides layered interoperability between Things by using the WoT Interfaces.
This specification describes a programming interface representing the WoT Interface that allows scripts run on a Thing to discover and consume (retrieve) other Things and to expose Things characterized by WoT Interactions, i.e. Properties, Actions and Events.
Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications like Thing Directory.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. 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/.
Implementers need to be aware that this specification is considered unstable. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository and take part in the discussions.
Please contribute to this draft using the GitHub Issue feature of the WoT Scripting API repository. For feedback on security and privacy considerations, please use the WoT Security and Privacy Issues.
This document was published by the Web of Things Working Group as a Working Draft. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. Please send them to public-wot-wg@w3.org (subscribe, archives).
Changes from the previous publication can be found in Appendix A. A diff-marked version of this document is also available for comparison purposes.
Publication as a Working Draft does not imply endorsement by the W3C Membership. 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 1 February 2018 W3C Process Document.
The overall WoT concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable format, the Thing Description (TD) and expose these capabilities through the WoT Interface. Support for scripting is optional for WoT devices.
By consuming a TD, a client Thing creates a runtime resource model that allows accessing the Properties, Actions and Events exposed by the server Thing.
Exposing a Thing requires defining a Thing Description (TD) and instantiating a software stack needed to serve requests for accessing the exposed Properties, Actions and Events. This specification describes how to expose and consume Things by a script.
Typically scripts are meant to be used on devices able to provide resources (with a WoT interface) for managing (installing, updating, running) scripts, such as bridges or gateways that expose and control simpler devices as WoT Things.
This specification does not make assumptions on how the WoT Runtime handles and runs scripts, including single or multiple tenancy, script deployment and lifecycle management. The API already supports the generic mechanisms that make it possible to implement script management, for instance by exposing a manager Thing whose Actions (action handlers) implement script lifecycle management operations.
For an introduction on how scripts could be used in Web of Things, check the Primer document. For some background on API design decisions check the Rationale document.
This section is non-normative.
The following scripting use cases are supported in this specification:
ExposedThing
to be exposed, based on
a Thing Description provided in
string serialized format, or out of a template or an
existing ConsumedThing
object.
WoT
objectThe WoT object is the API entry point and it is exposed by an implementation of the WoT Runtime. The WoT object does not expose properties, only methods for discovering, consuming and exposing a Thing.
Browser implementations SHOULD use a namespace object such as
wot
, and Node.js-like runtimes MAY provide the API object through
the require()
or
import
mechanism.
interfaceWoT
{Observable
<ConsumedThing
> discover(optionalThingFilter
filter); Promise<ThingDescription
> fetch(USVString url);ConsumedThing
consume(ThingDescription
td);ExposedThing
produce(ThingModel
model); }; typedef USVStringThingDescription
; typedef (ThingTemplate
orThingDescription
)ThingModel
;
The algorithms for the WoT methods will be specified later, including error handling and security considerations.
discover()
methodStarts the discovery process that will provide
objects that match the optional argument ConsumedThing
. When the argument
is not provided, starts the widest discovery the Thing Description and Protocol Bindings allow and support. Returns an
ThingFilter
Observable
object that can be subscribed to and unsubscribed from.
DiscoveryMethod
enumerationtypedef DOMString DiscoveryMethod
;
DiscoveryMethod
represents the discovery type to be used:
ThingFilter
dictionaryThe ThingFilter
dictionary that represents the constraints for discovering
Things as key-value pairs.
dictionary ThingFilter
{
DiscoveryMethod
method
= "any";
USVString url
;
USVString query
;
sequence<Dictionary> constraints
;
};
The method
property represents the
discovery type that should be used in the discovery
process. The possible values are defined by the
enumeration
that can be extended by string values defined by solutions
(with no guarantee of interoperability).DiscoveryMethod
The DiscoveryMethod
enumeration can be
extended by the Thing Description
with values that are not specified here. This
extensibility of DiscoveryMethod
by proprietary or
private methods is a working assumption until consensus
is formed and may be removed later.
The url
property represents additional
information for the discovery method, such as the URL of
the target entity serving the discovery request, such as a
Thing Directory or a Thing.
The query
property represents a
query string accepted by the implementation, for instance a
SPARQL query.
The constraints
property
represents additional information for the discovery method
in the form of a list of sets of property-value pairs
(dictionaries). The list elements (dictionaries) are in OR
relationship, and within a constraint dictionary the
key-value pairs are in AND relationship. Implementations
SHOULD make the
following mapping from the constraint dictionaries to
SemanticAnnotations
:
for each property-value pair in a constraint
dictionary,
name
property of a defined
SemanticType
on the
target Thing object, or the name of a
Property on the target
Thing.
Constraints are experimental feature, implementations are not required to support them.
fetch()
methodAccepts an url
argument and returns a
Promise
that resolves with a
ThingDescription
.
ThingDescription
typeRepresentation of the Thing Description, standardized in the Wot Things Description specification.
In this version of the API, Thing Descriptions are represented as opaque strings, denoting a serialized form, for instance JSON or JSON-LD. See Issue 38 and Issue 45.
consume()
methodAccepts an td
argument of type
and returns a
ThingDescription
ConsumedThing
object
instantiated based on that description.
produce()
methodAccepts a model
argument of type
and
returns an ThingModel
ExposedThing
object,
locally created based on the provided initialization
parameters. An ExposedThing
can be created in the
following ways:
ConsumedThing
object), then adding
request handlers.
ThingModel
typeA Thing model is used for producing a new ExposedThing
and can be either a
ThingTemplate
, or a
ThingDescription
.
SemanticAnnotations
dictionaryA dictionary that provides the semantic types and semantic metadata.
dictionary SemanticAnnotations
{
sequence<SemanticType
> semanticType
;
sequence<SemanticMetadata
> metadata
;
};
The semanticType
property denotes a list of SemanticType
objects that define the
semantic types that can be used in semantic metadata
type-value pairs.
The metadata
property
denotes a list of SemanticMetadata
objects (type-value
pairs).
SemanticType
dictionaryRepresents a semantic type annotation, containing a name, a context and a prefix.
name
attribute represents the
name of the semantic type in the given context.context
attribute represents
an URL link to the context of the semantic
classification.prefix
attribute represents a
short prefix associated with a context.Semantic type examples to be added.
SemanticMetadata
dictionarydictionary SemanticMetadata
{
SemanticType
type
;
any value
;
};
The SemanticMetadata
dictionary describes a pair of semantic type and value:
type
attribute represents the semantic type name defined by a
SemanticType
object.
value
attribute
represents the metadata value.ThingTemplate
dictionaryA Thing Template is a dictionary that provides a user
given name, and the semantic types and semantic metadata
attached to the ExposedThing
Thing Description's root level.
dictionary ThingTemplate
: SemanticAnnotations
{
required DOMString name
;
};
The ThingTemplate
dictionary extends SemanticAnnotations
and contains
properties to initialize a Thing:
name
attribute represents the
user given name of the Thing.
Support for configuration and security data might be added later.
let discoveryFilter = {
method: "directory",
url: "http://directory.wotservice.org"
};
let subscription = wot.discover(discoveryFilter).subscribe(
thing => { console.log("Found Thing " + thing.name); },
error => { console.log("Discovery finished because an error: " + error.message); },
() => { console.log("Discovery finished successfully");}
);
setTimeout( () => {
subscription.unsubscribe();
console.log("Discovery timeout");
},
5000);
Note that canceling a discovery (through
unsubscribe()
) may not be successful in all
cases, for instance when discovery is based on open ended
broadcast requests. However, once
unsubscribe()
has been called, implementations
MUST suppress further
event handling ( i.e. further discoveries and errors) on
the Observable. Also, a discovery error may not mean the
end of the discovery process. However, in order to respect
Observable semantics (error always terminates processing),
implementations MUST
close or suppress further event handling on the
Observable.
let subscription = wot.discover({ method: "local" }).subscribe(
thing => { console.log("Found local Thing " + thing.name); },
error => { console.log("Discovery error: " + error.message); },
() => { console.log("Discovery finished successfully");}
);
let subscription = wot.discover({ method: "local" }).subscribe({
thing => { console.log("Found local Thing " + thing.name); },
error: err => { console.log("Discovery error: " + err.message); },
complete: () => { console.log("Discovery finished successfully");}
});
let subscription = wot.discover({
method: "nearby",
constraints: [{ protocol: "BLE-4.2" }, { protocol: "NFC"}]
}).subscribe(
thing => { console.log("Found nearby Thing " + thing.name); },
error => { console.log("Discovery error: " + error.message); },
() => { console.log("Discovery finished successfully");}
);
let subscription = wot.discover({
method: "other",
constraints: [{ solution: "XYZ123", key: "..."}]
}).subscribe(
thing => { console.log("Found Thing " + thing.name); },
error => { console.log("Discovery error: " + error.message); },
() => { console.log("Discovery finished successfully");}
);
ConsumedThing
interfaceThe ConsumedThing
interface
is a client API for sending requests to servers in order to
retrieve or update Properties, invoke
Actions, and observe Properties and Events.
interface ConsumedThing
{
readonly attribute DOMString name
;
ThingDescription
getThingDescription();
Promise<any> readProperty(DOMString name);
Promise<void> writeProperty(DOMString name, any value);
Promise<any> invokeAction(DOMString name, any parameters);
Observable
onPropertyChange(DOMString name);
Observable
onEvent(DOMString name);
Observable
onTDChange();
};
ConsumedThing
represents a local proxy object
of the remote Thing.
name
propertyThe name
property represents the name of the
Thing as specified in the TD. In this version it
is read only.
getThingDescription()
methodReturns the Thing Description of the Thing.
In this version, introspection based on TD is out of scope. Parsing and exposing Thing Descriptions is discussed in Issue 38.
readProperty()
methodTakes the Property name as the name
argument, then requests from the underlying platform and the
Protocol Bindings to retrieve the
Property on the remote Thing and return the
result. Returns a Promise
that
resolves with the Property value or
rejects with an Error.
writeProperty()
methodTakes the Property name as the name
argument and the new value as the value argument,
then requests from the underlying platform and the Protocol Bindings to update the Property on the remote Thing and return the
result. Returns a Promise
that
resolves on success or rejects with an Error.
invokeAction()
methodTakes the Action name from the name
argument and the list of parameters, then requests from the
underlying platform and the Protocol
Bindings to invoke the Action on the remote
Thing and return the result. Returns a
Promise
that resolves with
the return value or rejects with an Error.
onPropertyChange()
methodReturns an Observable
for the
Property specified in the name argument,
allowing subscribing to and unsubscribing from
notifications.
The callback function passed to the
subscribe()
method when invoked on the returned
observer will receive the new property value each time it is
changed.
onEvent()
methodReturns an Observable
for the
Event specified in the name argument,
allowing subscribing to and unsubscribing from
notifications.
The callback function passed to the
subscribe()
method when invoked on the returned
observer will receive the event data each time the event is
fired.
onTDChange()
methodReturns an Observable
, allowing
subscribing to and unsubscribing from notifications to the
Thing Description.
The callback function passed to the
subscribe()
method when invoked on the returned
observer will receive the new Thing Description each time it is changed.
Below a
interface example
is given.ConsumedThing
try { let td = await wot.fetch("http://mmyservice.org/mySensor"); let thing = wot.consume(td); console.log("Thing " + thing.name + " has been consumed."); let subscription = thing.onPropertyChange("temperature") .subscribe(function(value) { console.log("Temperature + " has changed to " + value); }); thing.invokeAction("startMeasurement", { units: "Celsius" }) .then(() => { console.log("Temperature measurement started."); }) .catch(e => { console.log("Error starting measurement."); subscription.unsubscribe(); }) } catch(error) { console.log("Error during fetch or consume: " + error.message); };
ExposedThing
interfaceThe ExposedThing
interface is
the server API that allows defining request handlers,
properties, Actions, and Events to a
Thing. It also implements the ConsumedThing
interface. An ExposedThing
is created by the produce() method.
It is under consideration to use a constructor
for ExposedThing
instead of
a factory method.
ExposedThing
implementsConsumedThing
; interfaceExposedThing
{ // define how to expose and run the Thing Promise<void> start(); Promise<void> stop(); Promise<void> register(optional USVString directory); Promise<void> unregister(optional USVString directory); Promise<void> emitEvent(DOMString eventName, any payload); // define Thing Description modifiersExposedThing
addProperty(ThingProperty
property);ExposedThing
removeProperty(DOMString name);ExposedThing
addAction(ThingAction
action);ExposedThing
removeAction(DOMString name);ExposedThing
addEvent(ThingEvent
event);ExposedThing
removeEvent(DOMString name); // define request handlersExposedThing
setPropertyReadHandler(DOMString name,PropertyReadHandler
readHandler);ExposedThing
setPropertyWriteHandler(DOMString name,PropertyWriteHandler
writeHandler);ExposedThing
setActionHandler(DOMString name,ActionHandler
action); }; callbackPropertyReadHandler
= Promise<any> (); callbackPropertyWriteHandler
= Promise<void> (any value); callbackActionHandler
= Promise<any> (any parameters);
start()
methodStart serving external requests for the Thing.
stop()
methodStop serving external requests for the Thing.
register()
methodGenerates the Thing Description
given the properties, Actions and Event defined for this object. If a
directory
argument is given, make a request to
register the Thing Description with
the given WoT repository by invoking its
register
Action.
unregister()
methodIf a directory
argument is given, make a
request to unregister the Thing
Description with the given WoT repository by invoking its
unregister
Action. Then, and in
the case no arguments were provided to this function, stop
the Thing and remove the Thing Description.
emitEvent()
methodEmits an the event initialized with the event name
specified by the eventName
argument and data
specified by the payload
argument.
DataSchema
typetypedef USVString DataSchema
;
The DataSchema
type
represents a data type
specified
in the Thing Description in a serialized
form.
DataSchema
is under
development, currently it can denote any type supported by
the Thing Description and the WoT Runtime.
addProperty()
methodAdds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.
ThingProperty
dictionarydictionary ThingProperty
: SemanticAnnotations
{
required DOMString name
;
required DataSchema
schema
;
any value
;
boolean writable
= false;
boolean observable
= false;
};
Represents the Thing Property description.
name
attribute represents the name of the Property.
schema
attribute represents
the data type for the Property
described by DataSchema
.
value
attribute represents the value of the Property.
writable
attribute
defines whether the Property can be
updated. The default value is false
.
observable
attribute
defines whether the Property changes
can be observed by an external client. The default
value is false
.
removeProperty()
methodRemoves the Property specified by the
name
argument and updates the Thing Description. Throws on error. Returns a
reference to the same object for supporting chaining.
addAction()
methodAdds an Action to the Thing object as
defined by the action
argument of type ThingAction
and updates the Thing Description. Throws on error. Returns a
reference to the same object for supporting chaining.
ThingAction
dictionarydictionary ThingAction
: SemanticAnnotations
{
required DOMString name
;
DataSchema
inputSchema
;
DataSchema
outputSchema
;
};
The ThingAction
dictionary describes the arguments and the return
value.
name
attribute provides the
Action name.
inputSchema
attribute provides the description of the input arguments
(argument list is represented by an object). If missing,
it means the action does not accept arguments.outputSchema
attribute provides the description of the returned data.
If missing, it means the action does not return
data.removeAction()
methodRemoves the Action specified by the
name
argument and updates the Thing Description. Throws on error. Returns a
reference to the same object for supporting chaining.
addEvent()
methodAdds an event to the Thing object as
defined by the event
argument of type ThingEvent
and updates the Thing Description. Throws on error. Returns a
reference to the same object for supporting chaining.
ThingEvent
dictionarydictionary ThingEvent
: SemanticAnnotations
{
required DOMString name
;
DataSchema
schema
;
};
name
attribute represents the
event name.schema
attribute represents
the type of the data that is attached to the event. If
missing, it means the event does not carry data.removeEvent()
methodRemoves the event specified by the name
argument and updates the Thing
Description. Returns a reference to the same object for
supporting chaining.
PropertyReadHandler
callbackA function that returns a Promise and resolves it with the
value of the Property matching the
name
argument to the
setPropertyReadHandler
function, or rejects with
an error if the property is not found or the value cannot be
retrieved.
PropertyWriteHandler
callbackA function called with value
as argument that
returns a Promise which is resolved when the value of the
Property matching the name
argument to
the setPropertyReadHandler
function is updated
with value
, or rejects with an error if the
property is not found or the value cannot be updated.
Note that this function is invoked by
implementations before the property is updated, so the code
in this callback function can invoke the
readProperty()
method to find out the old
value of the property, if needed. Therefore the old value
is not provided to this method.
ActionHandler
callbackA function called with a parameters
dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request.
It returns a Promise that rejects with an error or resolves
if the action is successful or ongoing (may also resolve with
a control object such as an Observable
for actions that need
progress notifications or that can be canceled).
setPropertyReadHandler()
methodTakes name
as string argument and
readHandler
as argument of type PropertyReadHandler
.
Sets the handler function for reading the specified Property matched by name
. Throws on
error. Returns a reference to the same object for supporting
chaining.
The readHandler
callback function will
implement reading a Property and
SHOULD be called by
implementations when a request for reading a Property is received from the underlying
platform.
There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler.
setPropertyWriteHandler()
methodTakes name
as string argument and
writeHandler
as argument of type PropertyWriteHandler
.
Sets the handler function for writing the specified Property matched by name
. Throws on
error. Returns a reference to the same object for supporting
chaining.
There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers on change.
setActionHandler()
methodTakes name
as string argument and
action
as argument of type ActionHandler
. Sets the handler
function for the specified Action matched by
name
. Throws on error. Returns a reference to
the same object for supporting chaining.
If provided, this callback function will implement
invoking an Action and SHOULD be called by implementations when
a request for invoking a Action is received
from the underlying platform. The callback will receive a
parameters
dictionary argument.
There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client.
Below some
interface examples
are given.ExposedThing
try {
var thing = WoT.produce({ name: "tempSensor" });
// manually add Interactions
thing.addProperty({
name: "temperature",
value: 0.0,
schema: '{ "type": "number" }'
// use default values for the rest
}).addProperty({
name: "max",
value: 0.0,
schema: '{ "type": "number" }'
// use default values for the rest
}).addAction({
name: "reset",
// no input, no output
}).addEvent({
name: "onchange",
schema: '{ "type": "number" }'
});
// add server functionality
thing.setActionHandler("reset", () => {
console.log("Resetting maximum");
thing.writeProperty("max", 0.0);
});
thing.start().then(() => {
thing.register();
});
// define Thing business logic
setInterval( async () => {
let mock = Math.random()*100;
thing.writeProperty("temperature", mock);
let old = await thing.readProperty("max");
if (old < mock) {
thing.writeProperty("max", mock);
thing.emitEvent("onchange");
}
}, 1000);
} catch (err) {
console.log("Error creating ExposedThing: " + err);
}
let thingDescription = '{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
try {
// note that produce() fails if thingDescription contains error
let thing = WoT.produce(thingDescription);
// Interactions were added from TD
// WoT adds generic handler for reading any property
// define a specific handler for one property
let name = "examplePropertyName";
thing.setPropertyReadHandler(name, () => {
console.log("Handling read request for " + name);
return new Promise((resolve, reject) => {
let examplePropertyValue = 5;
resolve(examplePropertyValue);
},
e => {
console.log("Error");
});
});
thing.start();
} catch(err) {
console.log("Error creating ExposedThing: " + err);
}
// fetch an external TD, e.g., to set up a proxy for that Thing
WoT.fetch("http://myservice.org/mySensor/description").then(td => {
// WoT.produce() ignores instance-specific metadata (security, form)
let thing = WoT.produce(td);
// Interactions were added from TD
// add server functionality
// ...
});
This section is non-normative.
The ThingDescription
related
functionality, such as enumerating Properties,
Actions, Events and links (introspection) is an
API extension that is out of scope for this specification.
However, the draft interfaces are defined here for informative
purposes.
partial interface ConsumedThing
{
sequence<ThingProperty
> getProperties();
sequence<ThingAction
> getActions();
sequence<ThingEvent
> getEvents();
sequence<TDLink
> getLinks();
};
getProperties()
methodReturns the list of Properties defined in
the Thing Description of the Thing in the form of a list of ThingProperty
objects.
getActions()
methodReturns the list of Actions defined in the
Thing Description of the Thing in the form of a list of ThingAction
objects.
getEvents()
methodReturns the list of Events defined in the
Thing Description of the Thing in the form of a list of ThingEvent
objects.
getLinks()
methodReturns the list of linked resources in Thing Description of the Thing in the
form of a list of TDLink
objects.
TDLink
dictionaryContains a hyperlink reference, a relation type and a media type.
The TDLink
dictionary
contains the following properties:
href
attribute represents a
hyperlink reference.
rel
attribute represents a
relation type.
mediaType
attribute
represents a IANA media type.
For TDs there will be registered
media types, so applications will be able to check
whether an href
link points to a TD, i.e. whether the link is fetcheable with
this API.
This section is non-normative.
Observables are proposed to be included in ECMAScript and are used for handling pushed data associated with various possible sources, for instance events, timers, streams, etc. A minimal required implementation is described here.
This section is informal and contains rather laconic information for implementations on what to support for interoperability.
interfaceObservable
{Subscription
subscribe
((Observer
orOnNext
) next, optionalOnError
error, optionalOnComplete
complete); }; interfaceSubscription
{ voidunsubscribe
(); readonly attribute booleanclosed
; }; interfaceObserver
{ void next(any value); void error(Error error); void complete(); }; callbackOnNext
= void (any value); callbackOnError
= void (Error error); callbackOnComplete
= void ();
Observer
interfaceThe Observer
interface
defines the callbacks needed to handle an Observable
:
next()
function,
as well as the OnNext
callback takes the next
sample for the data in the value
argument.error()
function, as well as the OnError
callback
takes an error in the value
argument. It is
called when an error occured in producing the data the
client should know about.complete()
function, as well as the OnComplete
callback is called when the data source has finished
sending values.Subscription
interfaceContains the closed
property of
type boolean
that tells if the subscription is
closed or active.
Also, contains the unsubscribe
()
method that cancels the subscription, i.e. makes a request to
the underlying platform to stop receiving data from the
source, and sets the closed
property to
false
.
Observable
interfaceThe Observable
interface
enabled subscribing to pushed data notifications by the
subscribe
()
method:
subscribe()
method is called with
an Observer
object,
initialize the data, error and completion handling
callbacks from that object, or throw on error.
subscribe()
method is
called with a function, initialize the data handler
callback with that function. If the next argument is
provided and is a function, initialize the error handling
callback with that function, or throw on error. If the
third argument is provided and is a function, initialize
the completion handler with that function, or throw on
error.Please see the WoT Security and Privacy repository for work in progress regarding threat models, assets, risks, recommended mitigations, and best practices for security and privacy for systems using the Web of Things. Once complete, security and privacy considerations relevant to the Scripting API will be summarized in this section.
The generic WoT terminology is defined in [WOT-ARCHITECTURE]: Thing, Thing Description (in short TD), Web of Things (in short WoT), WoT Interface, Protocol Bindings, WoT Runtime, Consuming a Thing Description, Thing Directory, WoT Interactions, Property, Action, Event etc.
JSON-LD is
defined in [JSON-LD] as a JSON document that is
augmented with support for Linked Data by providing a
@context
property with a defining URI .
The terms URL and URL path are defined in [URL].
The following terms are defined in [HTML52] and are used in the context of browser implementations: browsing context, top-level browsing context, global object, incumbent settings object, Document, document base URL, Window, WindowProxy, origin, ASCII serialized origin, executing algorithms in parallel, queue a task, task source, iframe, valid MIME type.
A browsing context refers to the
environment in which Document objects are
presented to the user. A given browsing context
has a single WindowProxy
object, but it can have many Document
objects, with their associated Window
objects. The script execution context
associated with the browsing context identifies the
entity which invokes this API, which can be a web app, a
web page, or an iframe.
The term secure context is defined in [WEBAPPSEC].
Error, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError , script execution context, Promise, JSON, JSON.stringify and JSON.parse are defined in [ECMASCRIPT].
DOMString, USVString, ArrayBuffer, BufferSource and any are defined in [WEBIDL].
The algorithms utf-8 encode, and utf-8 decode are defined in [ENCODING].
IANA media types (formerly known as MIME types) are defined in RFC2046.
The terms hyperlink reference and relation type are defined in [HTML52] and RFC8288.
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.
The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].
This document defines conformance criteria that apply to a single product: the UA (user agent) that implements the interfaces it contains.
This specification can be used for implementing the WoT Scripting API in multiple programming languages. The interface definitions are specified in [WEBIDL].
The user agent (UA) may be implemented in the browser, or in a separate runtime environment, such as Node.js or small embedded runtimes.
Implementations that use ECMAScript executed in a browser to implement the APIs defined in this document MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL].
Implementations that use TypeScript or ECMAScript in a runtime to implement the APIs defined in this document MUST implement them in a manner consistent with the TypeScript Bindings defined in the TypeScript specification [TYPESCRIPT].
This document serves a general description of the WoT Scripting API. Language and runtime specific issues are discussed in separate extensions of this document.
The following is a list of major changes to the document. For a complete list of changes, see the github change log. You can also view the recently closed bugs.
ThingDescription
, ThingTemplate
,
SemanticAnnotations
, SemanticType
,
SemanticMetadata
, input and output data
descriptions, etc.
consume()
to fetch()
and consume()
.expose()
to accept a Thing Template.
addListener()
,
removeListener()
introduced
onEvent()
, onPropertyChange()
,
onTDChange()
.ExposedThing
handlers for Property,
Action and Event.Observable
.The following problems are being discussed and need most attention:
DataSchema
better (https://github.com/w3c/wot-scripting-api/issues/89).
ExposedThing
(https://github.com/w3c/wot-scripting-api/issues/45).
Special thanks to former editor Johannes Hund (until August 2017, when at Siemens AG) for developing this specification. Also, the editors would like to thank Dave Raggett, Matthias Kovatsch, Michael Koster and Michael McCool for their comments and guidance.