Add 'link' as top-level field of the TD (for Prague WD)

[mkovatsc]

This is a proposal for a use case that we have internally and which was also already discussed informally with other Members: linking to related Things and other resources from a TD.

The changes are minimal and the vocabulary and mechanics would follow RFC 8288.

Example:

{
  "@context": [ "http://w3c.github.io/wot/w3c-wot-td-context.jsonld" ],
  "@type": [ "Thing" ],
  "name": "MyLampThing",
  "interaction": [
    {
      "@type": [ "Property" ],
      "name": "status",
...
    }, {
      "@type": [ "Action" ],
      "name": "toggle",
...
    }, {
      "@type": [ "Event" ],
      "name": "overheating",
...
    }
  ],
  "link": [
    {
      "rel": "alternate",
      "href": "coaps://mylamp.example.com:5684/",
      "mediaType": "application/td+cbor"
    }, {
      "rel": "contains",
      "href": "https://mylamp.example.com:443/smart-meter/"
    }, {
      "rel": "locatedAt",
      "href": "https://myroom.example.com:443/"
    }
  ]
}

[mjkoster]

There is a new RFC for web linking which supersedes RFC5988 https://tools.ietf.org/html/rfc8288

In addition to location annotation, use case categories for links in TD include:

• links to TD modules in a modular TD system
• TD as an index with links associating thing interactions with Features of Interest (FoI)
• links to protocol binding components (forms, dataschema)

For the Prague plugfest, we would like to experiment with using links and link relations in TD to augment discovery by providing instance- and context- specific information, including incorporating Feature of Interest annotations for rooms, doors, etc.

[zolkis]

Is it intentional the array prop names are in singular, i.e. interaction and link instead of interactions and links?

[zolkis]

href is a link to the TD of the linked Things? That would be the only thing we could use in Scripting API to fetch and consume the linked instance.

[mkovatsc]

The link container is mainly meant for clarity for human consumers of the TD.

Since the TD is JSON-LD, it is already a construct of links that have defined predicates to express the relation. So, for more detailed relations that are of interest for machines, e.g., at Interaction level, the LD mechanism might be better.

[zolkis]

The link container is mainly meant for clarity for human consumers of the TD.

That didn't answer the question about naming :).

[mkovatsc]

Is it intentional the array prop names are in singular

Yes, we still use the convention of JSON-lD, where terms are singular to read out as triple statements, e.g., Thing (has)interaction status; Thing (has)name MyLampThing.

We aim at changing this for the simplified proposal, which will be the target after the Prague milestone. Then terms for arrays will be plural, also to align with properties, actions, events if the JSON-TD proposal.

href is a link to the TD of the linked Things?

href is part of a link and takes the target URI. Pointing to a TD document would be more useful than pointing to a Thing's @id (which might be different due to copies in Directories etc.); maybe another reason to not use LD predicates directly.

That didn't answer the question

I started typing the other comment while presenting, so it was in my write queue before your question.

[zolkis]

href is part of a link that takes the target URI. Pointing to a TD document would be more useful than pointing to a Thing's @id; maybe another reason to not use LD predicates directly.

If we are not sure what the link target is, we cannot use that directly in the Scripting API to provide the fetch() method with the link and fetch a Thing. Then we need an explicit API to fetch link content and trust it to the applications to parse and figure out what the links mean.

It would be just so much more usable to agree about one well defined semantics of href URLs in the "link" section, to point to a TD. Alternatively, use RFC 8288 relation types with the href to describe what the links are targeting.

[mkovatsc]

Works very well for me to define elements of href to point to fetchable resources, opposed to LD statements, which might point to an RDF IRI that is not fetchable.

This also builds another case why to have a link container instead of LD predicates.

[mkovatsc]

Transclusion would be enabled by well-defined rel values. Other rel values might define other handling. Unknown rel values would go unprocessed to the application.

[zolkis]

well-defined rel values.

Where are they well defined? Does the TD TF intend to define those values for WoT? I mean, which of the registered types is supposed to have special handling in WoT?

[mkovatsc]

In the TD vocabulary, but first things first. For the Prague target, the Scripting API only needs to pass them on to the application.

[zolkis]

OK, that is enough to decide the link API style.

[sebastiankb]

Based on today's TD call it makes sense to define an own Link class that contains the keys href, rel, target, and most likely anchor. Maybe it makes sense to define a superclass and sub-classes for the form/binding/endpoint and link.

[handrews]

to define an own Link class that contains the keys href, rel, target, and most likely anchor. Maybe it makes sense to define a superclass and sub-classes for the form/binding/endpoint and link.

Looking at the example above and these keywords, you are coming very close to hyper-schema's Link Description Object. Which also has additional keywords for forms on top of a link. I'm just saying...

[mjkoster]

From RFC8288 (Web Linking) Sec. 2:

In this specification, a link is a typed connection between two resources and is comprised of:

o a link context, o a link relation type (Section 2.1), o a link target, and o optionally, target attributes (Section 2.2).

Well known keywords are "href" for target, "rel" for relation type, "anchor" for context IRI. For target attributes, there are some well known keywords registered in various IANA documents.

"mediaType" that we define is a target attribute, for example. "type" is the IANA registered one for mediaType, but we already have that in 2 other places.

IETF CoRE WG has defined a few target attributes like "rt" for resource type and "if" for interface type

[handrews]

"type" is the IANA registered one for mediaType, but we already have that in 2 other places.

We used "targetMediaType" because other media types kept coming up (e.g. "submissionMediaType" for forms, "contentMediaType" for non-JSON content encoded as a JSON string).

[mjkoster]

Our use of "form" is to define the protocol methods and options that can be used for an instance of an interaction, so we are using vocabularies like http-in-rdf for the transport level terminology.

https://www.w3.org/TR/HTTP-in-RDF10/

We are re-using "href" and "rel" in this element to have roughly the same meaning as in links, where "rel" describes more of an type of "action" on the context resource as opposed to a type of relation. For example, rel=observe means that the target resource is used to do an observe on the context resource (loosely the interaction in a TD, so e.g. the property value being implied).

PS We're looking at renaming the "form" element

[mkovatsc]

I think the important point is that everyone in the discussion understands the difference between links and forms. It is true that within a form we have a link component that describes the relation between the context and the target. Yet a form has an additional interaction component where the server tells a client explicitly how to make a request, how to interact (method, request payload, protocol options/"header fields").

A rename of form should result in something clear, not in something wrong.

If the conclusion is that we primarily want to have a link where the interaction component comes from a default (like GET for Web Links) and we allow an optional interaction component on top of a link for when this component differs from the default, I am fine with that.

I understand this is the design in hyper-schema -- @handrews would you have the spec or an example of this? I could not find a good match in http://json-schema.org/latest/json-schema-hypermedia.html

[mkovatsc]

@handrews I think part of the answer is in https://github.com/w3c/wot-binding-templates/issues/13#issuecomment-368272278 :)

[sebastiankb]

I just updated the TD core model figure with the 'link' as top-level term. Its definition follows the RFC8288 (Web Linking).

[handrews]

If the conclusion is that we primarily want to have a link where the interaction component comes from a default (like GET for Web Links) and we allow an optional interaction component on top of a link

Yes, I think Hyper-Schema fits with this.

@mkovatsc I have more to write here but to start with did you look at the collections example? The "collection" link in an item (or the equivalent link from the entry schema with a custom link relation indicating what it's a collection of) is, I think, something like what you are looking for.

It has a targetSchema which describes what you will get back from a GET. I've implemented collections where you can do bulk changes by PUT-ing to the collection, and targetSchema also describes what you would send for a PUT (which could be thought of as a form of sorts).

It also has a submissionSchema which is a description of the input for the API equivalent of a POST form. I say "API equivalent" because in HTML forms, you either have this kind of form or URL query parameters as a form, but in Hyper-Schema these concepts are orthogonal and you can in fact use both at once.

While that collection example does not show it, you could add an hrefSchema as the equivalent of an HTML GET form to implement collection filtering. You could even PUT to a filtered collection, which would treat both targetSchema and hrefSchema as form input descriptions (whether you would want to do such a thing is a different question entirely).

As for header fields, these are addressed by headerSchema. It looks like we don't have an example of that, but there is some discussion of using it with HTTP that might be helpful, plus a bit about using it to guide content negotiation.

I'm not sure I'm explaining the right things here. Does this seem helpful? I can go into more detail, and any feedback on making the examples more clear would be very welcome.

I'm generally awful at writing examples, and the ones in the spec were a real struggle for me and only got this far based on feedback from other people.

[sebastiankb]

the main intention of this issue is compiled in the TD spec. Can we close it?

[mkovatsc]

@handrews Thanks for your explanation. I can see that you have submissionSchema, hrefSchema, and headerSchema to allow clients to build individual requests, including client-generated URIs, which would be a "no no" if the rule for generation didn't come from the server :)

These I would call a form for machines, because they do not describe the relation or the resource directly.

For that reason, we now stuck with the term form in the TD and use link only when pure relations to other resources are described.

I guess full closure for this issue could be reach, when we quickly hear how JSON Hyperschema sees these form extensions in the Link Description Object. Is it then still a link or does it become a form for you or do you say it is a link with additional form describers?

[handrews]

@mkovatsc link with additional form describers.

An LDO that has just targetSchema (no hrefSchema or submissionSchema) is a pure link. It may have a templatized URI, but that template is resolved only from instance data, not from client-supplied input.

You can treat such an LDO as a "form" for use with PUT or PATCH, and of course you can issue GET or DELETE on a link, but the LDO does's have an explicit form-ish mode for these operations. You can use targetHints to document the methods that may be usable (and to document the patch media type), but that is just a hint that you would otherwise discover through HEAD or OPTIONS.

submissionSchema and hrefSchema are directly for use as "forms", but their presence does not remove any of the pure link functionality already present in the LDO. They're an addition on top of that.

including client-generated URIs, which would be a "no no" if the rule for generation didn't come from the server :)

Yes, the hyper-schema should come from the "server" (either at runtime with some sort of same-origin policy, or logically in the form of pre-distributed schemas from a trusted source- we need to flesh out the security considerations section more).

[mkovatsc]

Thanks! And sorry for the following nit picking.. I just want to nail down the understanding of forms:

When submissionSchema and/or hrefSchema are present, the LDO becomes a "form"?

Maybe it is more an "also a form" because the the LDO can still be treated as just a link to follow by the client or, if the client wishes to, to submit data.

[mkovatsc]

In the latter case, the L in LDO might be a bit off, but still a good compromise for a single term...

[handrews]

@mkovatsc yes, "also a form" is correct- please continue to nitpick! Improving terminology and communication is always a good thing.

I don't know the history behind the LDO name and additional form functionality, but it hasn't seemed confusing enough to change.

But yes, the intention is that a link that also supports form semantics can be used as a link just as if the form semantics were not present. We did debate the possibility of having something either be a pure link or a form, but it produced a lot of duplication and no identifiable benefit. Every case we came up with for link + form could be expressed as a single LDO, so we settled on that.

The only case I can think of where an LDO cannot be used a pure link is when there is a required field in hrefSchema that cannot be resolved from the instance. That is the only scenario where client input is required to even resolve the URI. In all other scenarios (including hrefSchema with only optional fields, or required fields that can be resolved from the instance in the absence of client input), the LDO can be used as a plain link even if it also has form controls defined.

[handrews]

I tend to think of the "Description" in "Link Description Object" to not just be "this is a link" but also "this is what you can do with this link"

[mkovatsc]

Thanks, that really helped to fully understand your assumptions.

It also fits my empirical understanding of links and forms in HTML. I can express a link with a form (a click on the submit button takes me to the action URI with a mininal GET request), but not a form with a link.

Making form a superset of link brought me to the conclusion form is the right term in the TD, as also the exception of reading a Property is covered (it could be done with a pure link).

[sebastiankb]

Discussion seems to be terminated. Link is compiled in the TD spec.