Add link arrays to Property, Action and Event objects

[benfrancis]

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 links member. This will allow links to be assigned a mediaType and rel where 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 form objects 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 mediaType is currently used, consistent with the current top level links member. In the latest W3C draft mediaType was recently changed to contentType for forms, while links use the term link. I've filed https://github.com/w3c/wot-thing-description/issues/306 to find out whether this difference is intentional. We may eventually need to change mediaType to to contentType or type once 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).

[mrstegeman]

@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 rel?

[benfrancis]

@mrstegeman wrote:

@dhylands I don’t see a need to retain backwards compatibility for an in-development spec. We can do that on the gateway side.

I agree.

@benfrancis Should the individual property links have a rel?

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.

[hobinjk]

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)

[benfrancis]

@hobinjk wrote:

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

Yep, that makes sense. The links array of Property, Action and Event objects already re-uses the Link object, which can have a rel member. I've added some text to each to note the implied default values for rel if not provided. We can add additional examples later if we think of use cases for other possible values for rel.

(e.g. is an optional high-bandwidth video stream that severely impacts battery life)

This particular case might be better expressed by the mediaType (or some other additional metadata) because the actual relationship between the resources is really still the same. The linked resource represents a property of the current resource (the Thing Description), so implcitly rel=property.

[benfrancis]

Oops, forgot to squash.