Add link arrays to Property, Action and Event objects #119
Conversation
ghost
assigned 
|
@dhylands I don’t see a need to retain backwards compatibility for an in-development spec. We can do that on the gateway side. @benfrancis Should the individual property links have a |
|
@mrstegeman wrote:
I agree.
I thought about that for consistency, and they could, but I think the relationship is probably implied by the context of the links array (a links array in the context of a Property object provides link(s) to representation(s) of the property). Are there other types of link relation that might be present, with different types of relationship which need differentiating? Either way a "property", "action" and "event" relations could be implied defaults for Property, Action and Event objects respectively. |
|
It makes sense to me to have an optional "rel" with sensible defaults so that a link can highlight that it has some kind of special functionality (e.g. is an optional high-bandwidth video stream that severely impacts battery life) |
index.html
Outdated
| @@ -193,7 +193,8 @@ <h3><code>events</code> member</h3> | |||
| </section> | |||
| <section> | |||
| <h3><code>links</code> member</h3> | |||
| <p>The links member provides an array of link relations ([[!web-linking]]) to other resources of a thing. Links can include a link relation type (<code>rel</code>) and an optional media type (<code>mediaType</code>). Examples of links include a link to a <a href="#properties-resource">Properties resource</a> (<code>"rel":"properties"</code>), an <a href="#actions-resource">Actions resource</a> (<code>"rel":"actions"</code>) or an <a href="#events-resource">Events resource</a>. It can also include links to alternate representations of a thing such as a WebSocket API endpoint or an HTML user interface (<code>"rel":"alternate"</code>).</p> | |||
| <p>The links member provides an array of <a href="#event-object">Link Object</a>s which link to other resources of a thing.</p> | |||
There was a problem hiding this comment.
You're linking to #event-objects here.
index.html
Outdated
| <li>A <code>description</code> (A string providing a human friendly description)</li> | ||
| <li>A <code>links</code> array (An array of <a href="#link-object">Link object</a>s linking to one or more representations of a <a href="#property-resource">Property resource</a>)</li> | ||
| <li><code>enum</code> (an enumeration of possible values for the property)</li> | ||
| <li><code>readOnly</code> (A boolean indicating whether or not the property is read-only)</li> |
There was a problem hiding this comment.
Should we indicate here the readOnly defaults to false?
|
@hobinjk wrote:
Yep, that makes sense. The links array of Property, Action and Event objects already re-uses the Link object, which can have a
This particular case might be better expressed by the |
|
Oops, forgot to squash. |
Closes #79 and closes #108.
Live preview viewable here.
This is a proposal to add an array of Link objects to Property, Action and Event objects in the same format as the top level
linksmember. This will allow links to be assigned amediaTypeandrelwhere required and is particularly useful for binary properties which link to a binary file or stream (e.g. images and videos) with a defined media type.This is similar to the
formobjects in the current W3C spec, but with simple link relations rather than forms with operations. This may eventually change as the links vs. forms debate continues.Note that the term
mediaTypeis currently used, consistent with the current top level links member. In the latest W3C draftmediaTypewas recently changed tocontentTypefor forms, while links use the termlink. I've filed w3c/wot-thing-description#306 to find out whether this difference is intentional. We may eventually need to changemediaTypeto tocontentTypeortypeonce this becomes more clear.This is a breaking API change and we should make an effort to be backwards compatible with the deprecated href member in our next release (perhaps with a console warning).