Link parameter registry

[mnot]

Is it time to add a registry for the namespace of link parameters?

See:

• http://tools.ietf.org/html/draft-nottingham-link-hint
• http://tools.ietf.org/html/rfc6690

[jasnell]

+0 ... don't really see this as being critical at the moment. There really aren't a lot of extension link parameters being used just yet.

[dret]

it's kind of hard to say how many are used, right? one way to look at "link parameters" or "link hints" is to look at them as "unary links" that are associated with the target resource, i.e. they make a statement about the target resource and not one about the source. looking at it this way, they are "just links", and it would be useful to treat them similar to regular web links, i.e. to allow values to be registered and thus to allow people to find out which values are available for reuse.

[asbjornu]

Considering how this steps into the realm of API documentation formats such as Hydra, I'm not sure. If, by "registry", you mean "IANA registry", I actually see harm in defining a registry that will duplicate some of the efforts and semantics of schema.org and other vocabularies used in technologies built with, for example, RDF (such as the already mentioned Hydra).

[dret]

On 2016-03-29 14:28, Asbjørn Ulsberg wrote:

Considering how this steps into the realm of API documentation formats
such as Hydra http://www.hydra-cg.com/, I'm not sure. If, by
"registry", you mean "IANA registry", I actually see harm in defining a
registry that will duplicate some of the efforts and semantics of
schema.org http://schema.org/ and other vocabularies used in
technologies built with, for example, RDF (such as the already mentioned
Hydra).

if there are existing registries for standardized "link hints", then it
would be good to link to them from this issue so that we can find out
what's in there. i am not aware of any such registry, but if there were
one, then this certainly should be taken into account for any future
work on link hints.

one possible scenario we just discussed with @hvdsomp was the ability to
indicate the "schema" followed by a resource. using RFC 5988's "media"
hint, you can hint at a resource being JSON, but there's no way to
indicate which schema it is using (assuming that the JSON is not
described by a more expressive media type). currently there's no support
for this in web linking. with a new hint (and a registry so that the
available set can evolve), that would be possible. the very same
facility may be useful for RDF as well, btw.

it would be good if such a mechanism wasn't just specific for one single
representation, but instead would be reusable on the web. mark's draft
proposed such a thing and probably would be a good addition to what's
available in the web architecture toolbox.

[asbjornu]

@dret, I wouldn't say the registries (or ontologies) are "link hints" per se, but there's definitely some overlap between link hints and a full-fledged API documentation format such as Hydra.

I think the idea of pointing to a schema resource is a good one. What does @lanthaler, @elf-pavlik, @tpluscode, @RubenVerborgh and others involved with @HydraCG think of this?

[dret]

On 2016-03-30 09:01, Asbjørn Ulsberg wrote:

@dret https://github.com/dret, I wouldn't say the registries (or
ontologies) are "link hints" per se, but there's definitely some overlap
between link hints and a full-fledged API documentation format such as
Hydra.

that's what i wanted to say: in some of these models, "link hints" may
be used that would also be useful outside of that particular context.
having "links hints" as something external (just like link relations)
would help with that.

my main concern is how to differentiate link hints from links. in
essence, a link hint for a link from a to b is nothing but a statement
about resource b, so you might as well see it as an annotation (or in
fact, a link) for resource b. in this sense, a link hint is not all that
different from a regular link, it simply is serialized/delivered
differently.

https://github.com/dret/hyperpedia/blob/master/concepts.md#target-resource-hints
is an approach to put that into the bigger context of hypermedia models,
but i am sure there are different ways to see this as well.

I think the idea of pointing to a |schema| resource is a good one. What
does @lanthaler https://github.com/lanthaler, @elf-pavlik
https://github.com/elf-pavlik, @tpluscode
https://github.com/tpluscode, @RubenVerborgh
https://github.com/RubenVerborgh and others involved with @HydraCG
https://github.com/HydraCG think of this?

as with profiles, i'd rather frame that in terms of "identifying a
schema", but that's a detail to be discussed later.

[asbjornu]

Let's see if we can classify the different link types. I see the Link header as having two separate purposes:

1. Reference an external resource (loosely) related to the current resource. The related resource is usually an entirely self-contained entity in and of itself and may often have links back to the resource that referenced it.
2. Reference an external resource describing the current resource in one way or another. The external resource describes the current resource in terms of semantics, schema, documentation or some other form that wouldn't make much sense in and of itself.

The first purpose is what I assume you mean when saying "links" and the second is what "link hints", external schemas, profiles, etc. would do. Since an external resource can do everything "link hints" can do and more, I'm leaning towards favoring that approach over "link hints".

[mnot]

For me, the underlying issue is that right now, target attributes for a link are defined by:

• The link header
• HTML
• Atom
• individual link relations

in a pretty uncoordinated fashion. This is awkward, because it has the possibility of collision -- especially, a parameter that has different syntax or even semantics depending on what serialisation the link occurs within.

OTOH new serialisations are pretty rare, and we've got this far.

I'm inclined to leave them uncoordinated for now, but to add text advising those creating new link relations on how they should treat target attributes, and also reinforcing that those maintaining/creating serialisations should coordinate their efforts where possible.

[asbjornu]

add text advising those creating new link relations on how they should treat target attributes, and also reinforcing that those maintaining/creating serialisations should coordinate their efforts where possible.

👍 Some "best practice" guidance in an informative section would be good.