Mozilla W3C Differences

This wiki page documents differences between the Mozilla and W3C specifications for Thing Descriptions (TDs), with a view to converging them over time.

Note: This is not a complete list and will be added to and removed from over time.

Thing

• @context
  • The value of this member is usually https://www.w3.org/2019/wot/td/v1 in a W3C TD and https://iot.mozilla.org/schemas/ in a Mozilla TD. This is an intentional difference until the two specifications have converged.
  • The value of the W3C member can be an array in order to specify multiple contexts as per JSON-LD
• titles
  • The Mozilla TD relies on HTTP content negotiation to request TDs in different languages using the Accept-Language header rather than including all languages in a single TD. This is the approach taken by the W3C Web App Manifest specification.
• descriptions
  • Same as with titles
• version
  • Not in Mozilla TD.
• created
  • Not in Mozilla TD.
• modified
  • Not in Mozilla TD. Relies on Last-Modified header in HTTP
• support
  • Not in Mozilla TD.
• base
  • Not in Mozilla TD. Assumed to be the URL the Thing Description was served from.
• forms
  • Not in Mozilla TD (see Links vs. Forms section)
• security
  • This is not in the Mozilla specification, but there is actually a security member in the Thing Descriptions exposed by the WebThings Gateway. This was judged to be largely pointless since the Thing Descriptions themselves are authenticated and therefore if a client has access to this metadata it already knows about the security requirements. The gateway does not support security metadata for web things consumed/proxied by the web thing adapter acting as a client. This means all local web things being proxied are assumed to be unauthenticated, which is a significant shortcoming of the implementation.
• securityDefinitions
  • Not in Mozilla TD.

Property

• titles
  • See Thing section.
• descriptions
  • See Thing section.
• forms
  • See Links vs. Forms section.
• uriVariables
  • Not in Mozilla TD.
• observable
  • Not in Mozilla TD. If a TD provides a WebSocket endpoint all properties are considered observable, otherwise no properties are considered observable.

Action

• titles
  • See Thing section.
• descriptions
  • See Thing section.
• forms
  • See Links vs. Forms section.
• uriVariables
  • Not in Mozilla TD.
• output
  • Not in Mozilla TD. Didn't come across a use case, but have considered adding it.
• safe
  • Not in Mozilla TD. It is assumed that all actions change state in some way.
• idempotent
  • Not in Mozilla TD.

Event

• titles
  • See Thing section.
• descriptions
  • See Thing section.
• forms
  • See Links vs. Forms section.
• uriVariables
  • Not in Mozilla TD.
• subscription
  • Not in Mozilla TD. There is no concept of subscriptions in the REST API (where polling is used), and the WebSocket API describes the content of an addEventSubscription message.
• data
  • Not in Mozilla TD. Currently the data schema for an event exists at the top level of the Event object.
• cancellation
  • Not in Mozilla TD. There's currently no way to cancel an event subscription (missing feature), it is just assumed that a subscription ends when a WebSocket is closed.

Data Schemas

• The Mozilla specification does not separately specify data schema vocabulary definitions, but the Property, Action and Event objects do re-use some features of JSON Schema like unit, enum, readOnly, minimum, maximum and multipleOf.

Directory

• The Mozilla specification defines a way for a gateway to expose a list of the things it manages via the Things endpoint of the Web Thing REST API.

Links vs. Forms

The biggest difference between the Mozilla and W3C specifications is that the W3C specification defines both links and forms whereas the Mozilla specification only defines links. This is due to an architectural difference where the Mozilla specification defines a concrete REST API and WebSocket sub-protocol in the specification itself, whereas the W3C specification relies on APIs and protocols being described by metadata in an instance of a Thing Description using forms.

For very simple examples, links from the Mozilla specification work in the same way as forms in the W3C specifcation (they have a href, rel and mediaType member). However, the WebThings Gateway implementation assumes that all web things follow the Web Thing REST API and/or Web Thing WebSocket API and will not attempt to communicate with a web thing by parsing its form members. The Thing Descriptions exposed by the gateway contain only links, not forms.

Other differences:

• The Mozilla specification also defines link relation types of properties, actions and events and uses an alternate link relation to point to a WebSocket endpoint and HTML UI for a web thing.
• The Mozilla specification uses mediaType rather than type and does not define an anchor member of a Link.
• The Mozilla specification does not define op, contentType, contentEncoding, subprotocol, security, scopes or response members of a Link as the W3C specification does for a Form.
• The Mozilla specification defines an Event resource for getting a log of instances of an event, an Events resource for getting a log of all events and a top level link to a WebSocket endpoint which can be used to push all types of events from the server to the client. By contrast the W3C specification defines a form for each event affordance, but does not specify a default mechanism for communicating event data.
• The Mozilla specification uses links at the top level of the Thing Description to link to Properties, Actions and Events resources which are an aggregation of individual Property, Action and Event resources respectively. This allows for operations such as getting the value of all properties at once, getting a list of action requests of all types and getting a log of all events for a device.

Protocol Bindings

• The Mozilla specification defines a concrete REST API and WebSocket sub-protocol, whereas the W3C specification only defines a basic HTTP protocol binding with a small number of defaults.
• The Mozilla specification defines a payload format which includes an object wrapper for Property, Action and Event resources which includes the name of the property, action or event as an object key. This is implicitly assumed to be part of the interaction payload and is therefore not included in the data schema definition in the Thing Description. It was defined this way to be compatible with an older version of the JSON specification, to provide consistency between Property/Properties, Action/Actions and Event/Events resources and between the REST and WebSocket APIs (where WebSocket messages don't have the additional context of a property/action/event URL). This differs from the W3C specification where the payload of a request is assumed to directly follow the format described in the data schema.
• The Mozilla specification provides mechanisms to get a list of action requests, query the status of an action and cancel an action. At the time of writing this is not currently possible to express using a W3C thing description.
• The Mozilla specification does not support the use of non-web protocols like MQTT as this is considered out of scope for the Web of Things.
• The W3C specification does not provide any guidance on error conditions.