Can/should extended link relations resolve to resource objects?

[conzett]

I stumbled on json-home while looking for a way to describe extended link relations as part of a hypermedia API per RFC5988. It looks like the scope is just to describe the entire application structure at the root of the API (hence "home") however, it seems like parts of the specification could be very useful for providing documentation about relations deeper in the API.

For example, if I've navigated to URI http://example.org/foos/45 and I am presented with a link relation rel="http://example.org/rel/widgets" (either as a LINK header, HAL body, etc.) it seems pretty useful to be able to resolve that relation URI to a single resource object in order to provide "a definition of the semantics of the relation type."

Is this reasonable or totally beyond the scope of what json-home is trying to do? Describing the entire structure up front only seems a little at odds with "discoverability," but even if it's not is there any downside to providing additional contextual definitions in the form of resource objects?

[mnot]

I hadn't really considered using it in this manner; it feels like you're talking about a sort of a RESTish version of an EPR (which causes me to question some of my life choices).

/cc @dret

[dret]

i do not think that the idea of home is to "describe the entire structure". think of it rather than of a well-designed home page of a site: it has the most popular entry points to paths through the site, but is nowhere near to being a complete site map.

when it comes to the dereferencing extended link relations: i do not think that JSON home has anything to do with that. if that's a pattern you'd like to follow (some people do it, not very many, though), then you can do that. if you not only want to interpret extended link relation as URIs, but also make them discoverable as resources (if i am understanding correctly what you want to do), then i think neither RFC 5988 nor JSON home give you the expressivity you want.

if that is what you want to do, then isn't what you need a link relation that (and i am sorry for this confusing twist but it's unavoidable) would allow you to say "this link relation identifies links to resources which themselves are used as link relation types." i do not think i have seen such a link relation being defined or used, afaict the people interested in using link relation URIs as identifiers for resources describing the link relations simply tend to do so and then assume that clients know about this.

am i even close to understanding your question? if not, please rephrase a bit. thanks!

[asbjornu]

i do not think that the idea of home is to "describe the entire structure".

I also don't view json-home as a replacement for Sitemap.

this link relation identifies links to resources which themselves are used as link relation types

That's a way JSON-LD (RDF) is used, isn't it? Every property in your JSON is a word in a vocabulary such as schema.org, identifiable by its own URI. By using URIs to identify both the subject, the adjective and the verb of what you're modelling in your resources, you pretty much have the RDF triplet right there.

[conzett]

when it comes to the dereferencing extended link relations: i do not think that JSON home has anything to do with that.

I agree - sorry if I wasn't very clear in my original issue. I was referring only to the Resource Object concept discussed within the JSON Home draft spec.

isn't what you need a link relation that (and i am sorry for this confusing twist but it's unavoidable) would allow you to say "this link relation identifies links to resources which themselves are used as link relation types."

It took me a second, but that does make sense 😀 . In this case I'm working on a HAL-based API which encourages Custom link relation types to "be URIs that when dereferenced in a web browser provide relevant documentation". I'm looking to expand that documentation with additional media types beyond HTML to provide a more machine readable format and thought that the Resource Objects might be a good representation for that.

[dret]

On 2016-11-03 08:01, Graham Conzett wrote:

when it comes to the dereferencing extended link relations: i do not
think that JSON home has anything to do with that.

I agree - sorry if I wasn't very clear in my original issue. I was
referring only to the Resource Object
https://mnot.github.io/I-D/json-home/#rfc.section.3 concept discussed
within the JSON Home draft spec.

i'll leave the authoritative answer to @mnot. in the end, i wouldn't
read too much into the name or the concept. it's simply the name
associated to any resource made available through JSON home. i am not
sure it is even necessary to define this term, but that's simply how the
draft is currently doing it.

the main point behind the concept is that it allows these resource
objects to be one of two things: a resource, or a set of resources made
available through a URI template. in other words, anything that is not
a URI template is a "resource object", but keep in mind that the
"resource object" (as i have come to read the spec) simply refers to the
object in the JSON home structure that links to a resource. so in the
end, the term object here only refers to the fact that the resource
happens to be identified through a JSON object.

this terminology is a bit unfortunate for other ways of communicating
the JSON home model, such as in XML
(https://tools.ietf.org/html/draft-wilde-home-xml), because there the
"resource object" happens to be an XML element, and the object part of
the term just gets in the way.

regardless of these "spec engineering" issues: do not read too much into
the term resource object: it simply is JSON home's way of linking to a
resource.

isn't what you need a link relation that (and i am sorry for this
confusing twist but it's unavoidable) would allow you to say "this
link relation identifies links to resources which themselves are
used as link relation types."

It took me a second, but that does make sense 😀 . In this case I'm
working on a HAL-based API
https://tools.ietf.org/html/draft-kelly-json-hal-08 which encourages
Custom link relation types to "be URIs that when dereferenced in a web
browser provide relevant documentation"

i am glad i was on the right track!

https://tools.ietf.org/html/draft-kelly-json-hal-08#section-8.2. I'm
looking to expand that documentation with additional media types beyond
HTML to provide a more machine readable format and thought that the
Resource Objects might be a good representation for that.

i don't think that resource objects are what you think they are, as i
think that you are looking for something else entirely.

as @asbjornu pointed out, if you want to to RDF-ish kinds of things,
simply do it an run with it. neither RFC 5988 not JSON home are intended
or designed to help or interfere with that.

the important (and confusing) part of this is that true hypermedia
distinguishes between links and identifiers. links are typed and
navigable interrelations that are explicitly identified as such in
hypermedia formats.

RDF has no such concept: RDF has no concept of links, all URIs are
opaque identifiers. Linked Data (tm) then takes the other extreme and
says that all identifiers/URIs should be treated as links. again,
there is no ability to distinguish between identifiers and links. that's
what throws off many people, and maybe that's at the heart of your
scenario. if it is, then you first and foremost have to decide if you
want to do hypermedia, or RDF/LinkedData. these are two different ways
in which you can approach representing data and services.

[conzett]

@dret Thank you for the detailed reply! That clarifies terminology and focus of what JSON Home is trying to accomplish.

As a point of clarification (and I'm hopefully not drifting too far off topic here) when I mentioned RFC 5988 I was referencing section 4.2 specifically which says (emphasis added)

Applications that don't wish to register a relation type can use an
extension relation type, which is a URI [RFC3986] that uniquely
identifies the relation type. Although the URI can point to a
resource that contains a definition of the semantics of the relation
type, clients SHOULD NOT automatically access that resource to avoid
overburdening its server.

So while a custom link relation should be treated as an opaque identifier it seems to imply that optionally dereferencing the URI is acceptable on some level (I'm not using RDF currently).

I guess what I'm really looking for is an existing media type that can describe the relation when the URI is dereferenced.

[kidehen]

@dret --

RDF is a Language. It only prescribes the use of IRIs to identify the subject, predicate, and object (optionally) of RDF-Language sentences.

Linked Data is simply about the "best practice" of using HTTP URIs to identify the subject, predicate, and object (optionally) of RDF-Language sentences.

If you create a document containing RDF-Language sentences, that adheres to Linked Data principles, you end up with a hypermedia document (or resource). Note, that's achievable using a variety of sentence construction notations e.g., RDF-Turtle, JSON-LD, RDF-XML, CSV, and many others.

@conzett -- You are correct in your assumptions about a link relation i.e., a relation identified by a hyperlink (e.g., HTTP URI). When said hyperlink is de-referenced it will resolve to a document that describes its semantics (meaning).

Simple demonstration (best experienced via our Structured Data Sniffer Extension):

{
<#this>
a schema:WebPage ;
schema:name "Can/should extended link relations resolve to resource objects?" ;
schema:mainEntity <https://twitter.com/hashtag/Hypermedia#this>;
schema:mentions [
schema:mainEntityOf <http://linkeddata.uriburner.com/describe/?url=https%3A%2F%2Ftwitter.com%2Fhashtag%2FHypermedia%23this>], <https://twitter.com/hashtag/LinkedData#this>, <http://osds.openlinksw.com/#this> ;
schema:mainEntityOfPage <https://www.pinterest.com/pin/389561436502925516/> ;
schema:image <https://s-media-cache-ak0.pinimg.com/originals/8f/e6/09/8fe6098b72c1b2a88f89eaf178edbd8f.png> .

<https://twitter.com/hashtag/Hypermedia#this>
schema:name "Hypermedia" ;
schema:sameAs dbpedia:Hypermedia .
}

In the example above, you can look-up the semantics of relations such as schema:sameAs, schema:mentions, schema:mainEntity, schema:mainEntityOfPage, schema:name, or schema:image by simply clicking on the links by which they've identified.

[dret]

On 2016-11-03 09:21, Graham Conzett wrote:

As a point of clarification (and I'm hopefully not drifting too far off
topic here) when I mentioned RFC 5988 I was referencing section 4.2
https://tools.ietf.org/html/rfc5988#section-4.2 specifically which
says (emphasis added)

Applications that don't wish to register a relation type can use an
extension relation type, which is a URI [RFC3986] that uniquely
identifies the relation type. Although the URI /*can point to a
resource that contains a definition of the semantics of the relation
type*/, clients SHOULD NOT automatically access that resource to avoid
overburdening its server.

So while a custom link relation should be treated as an opaque
identifier it seems to imply that optionally dereferencing the URI is
acceptable on some level (I'm not using RDF currently).
I guess what I'm really looking for is an existing media type that can
describe the relation when the URI is dereferenced.

"describe the relation when the URI is dereferenced" is probably not
exactly what you want to say there (my apologies for trying to channel
you). i am guessing that you either want to describe the link relation
as a dereferencable one, and/or want to define which media type to
expect when you're dereferencing such a dereferencable link relation.

RFC 5988 says link relation identifiers are opaque. end of story. there
may be some context somewhere that goes beyond that and says that these
identifiers can be meaningfully dereferenced, and what to expect if you
do that, but that is simply acknowledged in the spec and simply out of
scope.

i think what you might be looking for (as mentioned in an earlier
comment) is a link relation that allows you to identify a link relation.
i am not aware of such a link relation, but if you find one, let us
know, and maybe it would be worth registering (unless it itself is a
URI-identified link relation in which case it is by definition an
extension link relation and cannot be registered).

one place worth looking might be the hydra vocabulary, but you probably
only want to go this route if you're doing something RDF-ish. if you do,
it may be worth a look.

[handrews]

RFC 5988 says link relation identifiers are opaque. end of story.

I'm not sure we're all interpreting "opaque" the same way, then, and I feel like I'm missing something.

Since the RFC specifically allows that the identifiers might be meaningfully dereferenced, that is not the same (to me) as saying that they are completely opaque tokens. It allows that you may be able to do something with them. It just doesn't impose any requirements on whoever created the URI to support any such thing. To me, "opaque" means that the identifier might as well be random gibberish.

There's some sort of subtle distinction here that I think I'm not quite getting.

[dret]

On 2016-11-03 11:01, Henry Andrews wrote:

RFC 5988 says link relation identifiers are opaque. end of story.

I'm not sure we're all interpreting "opaque" the same way, then, and I
feel like I'm missing something.
Since the RFC specifically allows that the identifiers might be
meaningfully dereferenced, that is not the same (to me) as saying that
they are completely opaque tokens. It allows that you may be able to do
something with them. It just doesn't impose any requirements on whoever
created the URI to support any such thing. To me, "opaque" means that
the identifier might as well be random gibberish.

the spec simply says it needs to be a URI, and that the only "meaning"
of that URI is its given value. so you can use "tag:42" as a link
identifier (not a great idea, i'd say, but perfectly fine in the context
given by RFC 5988). it's not completely random gibberish, but also not
something that has any meaning when looked at out of context.

There's some sort of subtle distinction here that I think I'm not quite
getting.

we have this tendency to think that a URI is something beyond its pure
value. that is not always the case. if you say (like RFC 5988 does) that
in some context you expect a URI, but all you need it to be is to be a
URI, then it simply is a "by value" identifier (i.e., the only
meaningful operation in that context is to compare identifier values),
and not a "by reference" identifier.

[handrews]

in some context you expect a URI, but all you need it to be is to be a
URI, then it simply is a "by value" identifier (i.e., the only
meaningful operation in that context is to compare identifier values),
and not a "by reference" identifier.

Then why talk about what it might reference?

[handrews]

To be clear, I'm not looking to assert that URIs used for identification purposes should be automatically dereferencable, that is clearly against the RFC. I'm trying to figure out the point of both saying "this is what it should point to if it points to anything" and then completely refusing to allow that it might point to something, which is what this feels like.

[dret]

On 2016-11-03 11:10, Henry Andrews wrote:

in some context you expect a URI, but all you need it to be is to be a
URI, then it simply is a "by value" identifier (i.e., the only
meaningful operation /in that context/ is to compare identifier values),
and not a "by reference" identifier.

Then why talk about what it might reference?

are you talking about the RFC 5988 text here? RFC 5988 simply
acknowledges the fact that somebody might be doing this, but itself
defines things so that you're not doing it. it does so just to say that
clients should not blindly attempt to dereference URIs. i think the main
pain point it addressed was the "HTML4 DTD" problem and similar
scenarios in which clients blindly dereferenced URIs, whether it was
necessary or not, and created problems for those hosting those URIs.

but we're drifting pretty far away from the original issue here.

[dret]

On 2016-11-03 11:13, Henry Andrews wrote:

To be clear, I'm not looking to assert that URIs used for identification
purposes should be automatically dereferencable, that is clearly against
the RFC. I'm trying to figure out the point of both saying "this is what
it should point to if it points to anything" and then completely
refusing to allow that it /might/ point to something, which is what this
feels like.

it does not refuse that at all. it simple is agnostic about that part,
and says that clients should be careful when making such an assumption.

[kidehen]

@conzett :

Excerpting what @dret stated in his comment i.e., ""describe the relation when the URI is dereferenced" is probably not
exactly what you want to say there (my apologies for trying to channel
you). i am guessing that you either want to describe the link relation
as a dereferencable one, and/or want to define which media type to
expect when you're dereferencing such a dereferencable link relation."

Do you want to achieve the following?
Identify a Relation (a/k/a Entity Relationship Type) using an HTTP URI such that any agent (machine or human) can lookup its description. The description in question, could take the form of a collection of RDF-Language sentences in a document.

Naturally, in regards to the statement above, the document content type (or media type) may vary e.g., JSON, JSON-LD, RDF-Turtle, RDF-XML, CSV, or many others (each has an IANA media type). If so, then you have a working example in the document identified by the HTTP URI: #202 (comment) :)

[kidehen]

@handrews : You are correct about identifier opacity. Confusion arises when HTTP URIs as used as Identifiers due to their implicit duality i.e., they serve two functions: 1) entity denotation 2) resolution to connotation (i.e., name->entity-description-document-address indirection).

Whenever you encounter Linked Data for instance, it simply boils down to exploiting the aforementioned duality combined with the ubiquity of HTTP en route to a Semantic Web -- where the meaning of relations (links) become discernible by way of dereference :)

[handrews]

@kidehen Yeah I think we're on the same page. @dret I don't think that the RFC refuses that, but your statement seemed to. It's clear to me at this point that that was not your intention. I still don't get why the RFC talks about what the referenced resource might be, but that's not a JSON Home issue so I'll go ponder it somewhere else :-)

[conzett]

Bringing this back around (after digesting everyone's comments) perhaps JSON home would help me here.

If the preference is to not dereference link extension URIs for documentation, I need some place where I can provide additional information about the link. Things like URL template parameters and general documentation. I'm struggling with where that information would reside currently.

[dret]

On Nov 3, 2016, at 11:41, Graham Conzett notifications@github.com wrote:
Bringing this back around (after digesting everyone's comments) perhaps JSON home would help me here. If the preference is to not dereference link extension URIs for documentation, I need some place where I can provide additional information about the link. Things like URL template parameters and general documentation. I'm struggling with where that information would reside currently.

maybe https://tools.ietf.org/html/draft-wilde-service-link-rel can help?

[kidehen]

@conzett : If you choose to follow Linked Data principles you will find that location becomes less of an issue for documents that describe entity relationship types (relations) that you identify using HTTP URIs (hyperlinks). For instance, using nanotation, you can even use a Github post to hold your relation descriptions .

SeeAlso: https://medium.com/openlink-software-blog/data-de-silo-fication-using-combined-power-of-rdf-language-nanotation-755f2e7a904d -- detailed examples of other notes-oriented data spaces as places to exploit Linked Data using nanotation.

[conzett]

@dret That looks promising, thank you! Now I just need to find a suitable media type for the machine consumable representation of the documentation resource.

@kidehen How can I use your example for say, describing a resource and various URI parameters that can be used with it?

[asbjornu]

@conzett: Have you looked at Hydra? It has the hypermedia (linked data) functionality you seem to be looking for as well as the ability to describe operations, expected input parameters, data types, etc.

[handrews]

@conzett JSON Schema / Hyper-Schema?

[kidehen]

@conzett : I have a few posts that describe the use of RDF-Language sentences to describes Web Service APIs and the Actions they provide:

[1] https://medium.com/virtuoso-blog/describing-web-services-using-a-linked-data-doc-using-schema-org-terms-6caa399fc97a -- Describing Web Services using terms from Schema.org vocabulary

[2] https://medium.com/virtuoso-blog/api-descriptions-for-humans-machines-ec04ce1d1a9a -- Here I demonstrate description of Uber APIs that were originally described using Swagger.

@conzett @handrews : If you follow the links that identify relations in my descriptions you will also see how integration with Hydra occurs. The key here is to be able to simply click on a link whenever you are curious about what an HTTP URI identifies.

[conzett]

@asbjornu I was very interested in Hydra before I started down this path but unfortunately I need to support some kind of XML format in addition to JSON. It looks like it could potentially be used with RDF/XML but I haven't seen any solid examples of that.

[kidehen]

@conzett -- You can transform content of an RDF-Turtle or JSON-LD document into RDF-XML. Those notations and document content types have no bearing on terms defined in an Ontology or Vocabulary such as Hydra. There are many tools that offer automatic content transformation circa., 2016 which means the document type used to publish an ontology or vocabulary shouldn't be an impediment to comprehension and use :)

[dret]

On 2016-11-04 11:06, Graham Conzett wrote:

@asbjornu https://github.com/asbjornu I was very interested in Hydra
before I started down this path but unfortunately I need to support some
kind of XML format in addition to JSON. It looks like it could
potentially be used with RDF/XML but I haven't seen any solid examples
of that.

don't fall into the trap of thinking that RDF/XML qualifies as an "XML
format". it makes sense to use it for RDF tool chains that support or
need RDF/XML as an RDF serialization. but RDF/XML is useless if you want
to support XML tool chains that need information to be readily available
at the XML level.

[mnot]

Closing because AFAICT there isn't any action for the spec here. But feel free to keep chatting :)

[kidehen]

@mnot : Yes, I agree.

Fundamentally, an IRI is an acceptable value. If the resource owner wants said IRI to resolve to a document that describes what it denotes (i.e., its referent) then an HTTP URI can be used, in line with the principles outlined in the "Linked Data" meme.

In a nutshell, "horses for courses" :)