New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Why yet another link relation format? #89

Open
stain opened this Issue Oct 18, 2017 · 31 comments

Comments

Projects
None yet
8 participants
@stain
Copy link
Contributor

stain commented Oct 18, 2017

Responding to draft-wilde-linkset-01

I wonder about what is the purpose of inventing a new media type application/linkset+json, when it is basically just a restricted form of RDF triples, where anchor ~= subject, rel ~= predicate and href ~= object - the set of which form a linkset or - if you like - a graph. (You didn't say they all needed to have the same anchor)

I am particularly worried as this draft seems to re-invent RDF Literal with language tags. Yes, these are important issues - which is why they have already been addressed.

See also how to describe RDF linksets - this would be the metadata about the linkset itself.

(I'm less ambivalent about application/linkset as it directly reflects the HTTP headers, I can see that as useful)

What this InternetDraft could instead do is to refer to existing RDF formats N-Triples -- which is flat and easy to parse -- and JSON-LD -- and give examples of how to represent HTTP links in those.

The main missing bit is to add a @vocab to more easily refer to the "non-absolute" link relations like "alternate" (See also mnot/I-D#39 and mnot/I-D#140)

Perhaps application/linkset+json should simply be tweaked to be a subset of JSON-LD by having an appropriate @context -- then you can reuse the Link header terminology.

@dret dret added the linkset label Oct 18, 2017

@dret

This comment has been minimized.

Copy link
Owner

dret commented Oct 18, 2017

@asbjornu

This comment has been minimized.

Copy link

asbjornu commented Oct 18, 2017

Here's a thought experiment: Can the linkset specification be made JSON-LD compatible with little or not changes to the linkset format itself? Can a JSON-LD @context document define everything required for linkset documents to be interpreted as RDF?

If such a thing is possible, would having an official linkset.jsonld that can be references with @context or within the Link header be something that can be baked into the linkset RFC?

@handrews

This comment has been minimized.

Copy link

handrews commented Oct 18, 2017

@asbjornu I think that having this media type does not prevent people from using JSON-LD for the same purpose. The fact that some people prefer a different approach is not a reason to drop this one. Other people will prefer this approach. Or they won't, and it will go unimplemented. None of that impacts those who would rather use JSON-LD.

@asbjornu

This comment has been minimized.

Copy link

asbjornu commented Oct 18, 2017

@handrews: I haven't argued for dropping linksets, I've argued for making linksets JSON-LD compatible out of the box, instead of tagging that on later. If it's easy to do, is there any good reason not to do it?

@handrews

This comment has been minimized.

Copy link

handrews commented Oct 18, 2017

@asbjornu as long as it does not make things awkward for non-users of JSON-LD then I have no problem with it, but it's up to @dret. While I'm a fan of semantic web technologies, many projects avoid them, so there are use cases where tying something to JSON-LD/RDF (as opposed to optionally supporting it) are problematic.

@asbjornu

This comment has been minimized.

Copy link

asbjornu commented Oct 18, 2017

Seeing how the JSON-LD context would just be a URI that can optionally be added via @context or Link header, I don't really see the harm. But yea, it's up to @dret to decide and @stain to hopefully help out defining such a context document.

@dret

This comment has been minimized.

Copy link
Owner

dret commented Oct 19, 2017

@dret

This comment has been minimized.

Copy link
Owner

dret commented Oct 19, 2017

@asbjornu

This comment has been minimized.

Copy link

asbjornu commented Oct 19, 2017

that would require everybody to reference that context, and for the vast majority of users, it has no effect or utility.

I wouldn't make it required. It wouldn't have any other effect on linksets for non-RDF people than this suggestion:

define an RDF model, and then come up with media types for the preferred serializations, JSON-LD and possible others as well.

What I would like is just that this is done normatively in the RFC instead of bolted on externally by possibly many different contexts defined by many different parties.

if you supported JSON-LD with a content, wouldn't making it optional defeat the purpose of allowing all linksets to be consumed as RDF?

Yes. I suppose it's possible to inject a context on consumption, but since it's opt-in, people would have to opt-in at the producer side, just as with a non-normative, externally defined context.

and that's not even looking at the extension issue: linksets can represent extensions that are not defined in web links. the JSON syntax allows those to be represented. would those need to be covered by additional contexts?

I don't know enough about RDF to say anything concrete about this, but I'm sure there's ways to represent something alike xsd:any in RDF. Ideas, @tpluscode?

@tpluscode

This comment has been minimized.

Copy link

tpluscode commented Oct 19, 2017

As for the initial comment by @stain, would a single link relation within a link set be equivalent to a triple? So that this snippet from the spec

{ 
  "href"   : "http://example.com/foo",
  "anchor" : "http://example.net/bar",
  "rel"    : [ "next" ] 
}

would become <http://example.com/foo> :next <http://example.net/bar> ?

If that is the intention then it looks like linkset+json and RDF are not as compatible as it superficially seems. At least without some processing it won't be as simple as slapping a @context to make this represent a triple.

From what I can tell, the linkset+json is closer in its structure to reification. This is what you get by applying rdf (the vocabulary) terms to the above:

_:b0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#object> "http://example.com/foo" .
_:b0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#predicate> <https://json-ld.org/playground/next> .
_:b0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#subject> "http://example.net/bar" .

Notice how the "next" becomes based under playground. For consumers it would be a necessity to either provide a base URI (in parser or context) or add custom contexts. Published could do that easily by array-ing multiple:

{
  "@context": [
    "linkset.jsonld",
    {
      "next": "http://my-link/next"
    }
  ]
{

Is this we're talking about here? Am I missing something?

@dret

This comment has been minimized.

Copy link
Owner

dret commented Oct 21, 2017

@tpluscode

This comment has been minimized.

Copy link

tpluscode commented Oct 21, 2017

To be clear. I'd have nothing against providing the JSON-LD context for linkset+json as long as it's clear that the resulting RDF is not what people might expect. Reified statements would be just as useful

@dret

This comment has been minimized.

Copy link
Owner

dret commented Oct 21, 2017

@tpluscode

This comment has been minimized.

Copy link

tpluscode commented Oct 21, 2017

the start of this thread suggested to drop the JSON media type and use some RDF serialization instead

I agree. IMO reification is that representation in RDF model. Actually it seems to fit perfectly with minimal effort which keeping the same JSON structure you currently have

@dret

This comment has been minimized.

Copy link
Owner

dret commented Oct 21, 2017

@stain

This comment has been minimized.

Copy link
Contributor

stain commented Oct 26, 2017

I am glad this discussion showed some thoughts on overlaps or not with RDF!

As for the relations like next, they can be made absolute under http://www.iana.org/assignments/link-relations/ using the JSON-LD @vocab mechanism as discussed in mnot/I-D#140

I prefer the idea of restructuring the application/linkset+json, JSON so it is also valid as JSON-LD, using the suggested context Link header, content negotiation to application/ld+json or this RFC could even say a @context that is implied if no Link header is present.

What makes http links not-straightforward as RDF is that the link relation itself can have additional properties, and it can be unclear if those properties relate to the subject, object or the link relation itself. In most of the cases they seem to describe the object.

If you want to keep the concept of a Link, then you would need to "reify" it somehow; RDF modelling would typically put those additional attributes on either subject, object or on a new intermediate N-ary relationship resource.

Agree with @dret that pure RDF reification is not generally desirable; it is meant for statements about statements - @tpluscode example works - but does not actually imply those statements.

So then it might be just as well to make a new RDF representation of RFC8288 links; either using a new "links" vocabulary (with 1:1 mapping of #rel, #href etc); or re-using an existing model - Web Annotation Model comes to mind; which already have a specified JSON representation that addresses almost exactly the same things as this RFC:

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "motivation": "describing",
  "body": {
    "id": "http://example.org/analysis1.mp3",
    "format": "audio/mpeg",
    "language": "fr"
  },
  "target": {
    "id": "http://example.gov/patent1.pdf",
    "format": "application/pdf",
    "language": ["en", "ar"],
  }
}

(This says that the French audio analysis1.mp3 is describing patent1.pdf which is in English and Arabic - admittedly it is more verbose, but also more extensible)

Here we just need to add our link relations under motivation.

I played a bit with how you would rather do the "expected" RDF statements in JSON-LD -- you would then turn the linkset upside-down and make the rel links primary as keys, and the href secondary; allowing any extra attributes there:

[
    {"anchor" : "http://example.net/bar",
     "next": { 
          "href"   : "http://example.com/foo",    
          "type": "application/pdf", 
          "title": "Santa Claus",
          "title*": { "@value": "Weihnachtsmann", "@language": "de" }
     },    
     "license": {
       "href": "https://creativecommons.org/licenses/by/4.0/"
     },
     "author": [ 
         {"href": "http://orcid.org/0000-0001-9842-9718"},
         {"href": "http://orcid.org/0000-0002-1267-0234"}
     ],
     "http://example.com/relations/baz": { 
       "href"   : "http://example.com/foo"
     }
   },
   {"anchor": "https://datatracker.ietf.org/doc/rfc8288/",
    "describes": {
      "href": "https://tools.ietf.org/html/rfc8288"
    }
   }
]

Here we have outgoing links for http://example.net/bar with rel values of next, license, author and the custom http://example.com/relations/baz. author shows example of multiple href link targets - allowing each of them to have their own title and so on.

Above I also used the JSON-LD syntax for language tags - I don't see any additional benefit of saving bytes of the shorter ["Weihnachtsmann", "de"] syntax as the whole point of this separate linkset file is that it was too big to include in the HTTP headers.

I parsed it with this JSON-LD syntax:

{ "@context": {
  "@vocab": "https://www.iana.org/assignments/link-relations/",
  "anchor": "@id",
  "href": "@id",
  "dct": "http://purl.org/dc/terms/",
  "link": "https://www.iana.org/assignments/link-relations#",  
  "title": {
      "@id": "http://purl.org/dc/terms/title"
   },
  "title*": {
      "@id": "http://purl.org/dc/terms/title"
   },
  "type": {
    "@id": "dct:format",
    "@type": "@vocab",
    "@context": {"@vocab": "https://www.iana.org/assignments/link-relations/"}
  }
 }

(Tip: to fake the JSON-LD context header you can paste the [ .. ] into a @graph attribute added to the above)

Using http://rdf.greggkellogg.net/distiller (which supports the recently introduced JSON-LD 1.1 scoped context) I got the RDF statements (in Turtle):

@prefix dc: <http://purl.org/dc/terms/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<http://example.net/bar> <http://example.com/relations/baz> <http://example.com/foo>;
   <http://www.iana.org/assignments/link-relations/author> <http://orcid.org/0000-0002-1267-0234>,
     <http://orcid.org/0000-0001-9842-9718>;
   <http://www.iana.org/assignments/link-relations/license> <https://creativecommons.org/licenses/by/4.0/>;
   <http://www.iana.org/assignments/link-relations/next> <http://example.com/foo> .

<https://datatracker.ietf.org/doc/rfc8288/> <http://www.iana.org/assignments/link-relations/describes> <https://tools.ietf.org/html/rfc8288> .

<http://example.com/foo> dc:title "Weihnachtsmann"@de,
     "Santa Claus";
   dc:format <http://www.iana.org/assignments/media-types/application/pdf> .

Now that I think this is much more like what you would expect in RDF land -- the license and author data is given directly just like with http://schema.org/license and http://schema.org/author; relations between the two rfc8288 pages are shown directly, and format links to an actual IANA registration.

So that would have been my preferred solution -- just modify the JSON structure slightly so that such a context could be applied. No more wheel reinvention..

@asbjornu

This comment has been minimized.

Copy link

asbjornu commented Oct 27, 2017

I have to say, I like @stain's proposal very much. Both the bare JSON structure and its out of the box JSON-LD compatibility.

@hvdsomp

This comment has been minimized.

Copy link
Collaborator

hvdsomp commented Apr 26, 2018

Irrespective of the JSON-LD issue, @stain's proposed JSON syntax is elegant indeed. It would probably good to evaluate how/whether it can handle all the cases summarized in #80

@dret

This comment has been minimized.

Copy link
Owner

dret commented Jul 31, 2018

@BigBlueHat

This comment has been minimized.

Copy link

BigBlueHat commented Aug 22, 2018

Hi friends. 😁

i've had some discussions with herbert and the one thing i want to avoid is to create mandatory behavior as a result of JSON-LD support that seems odd for the vast majority of plain JSON users.

@dret could you elaborate on what you see as "mandatory behavior as a result of JSON-LD support"?

Given that both specs are serializations of a graph model, it'd be great to harmonize them in some way.

Additionally, the title* property might benefit from using a structure similar to JSON-LD's language map approach:

{
  "title": "unknown language",
  "title*": {
    "en": "the english language value",
    "jp": "...if I knew Japanese...this would be in kanji..."  
   }
}

Checkout ActivityStreams JSON format (based on JSON-LD and in use in Mastodon and friends) for a similar approach: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name

Let me know how I can help!
🎩

@dret

This comment has been minimized.

Copy link
Owner

dret commented Aug 22, 2018

@BigBlueHat

This comment has been minimized.

Copy link

BigBlueHat commented Aug 22, 2018

requiring a context. afaict, JSON-LD requires you to specify a context, because without it, it's not defined at all what RDF the JSON represents, right? for JSON users, that context serves no purpose, and they shouldn't get into trouble for ignoring it.

Developers will have to understand the JSON somehow the context in JSON-LD is that "how."

For instance, to properly understand/utilize/process an application/linkset+json file, you have to know what the terms anchor, rel, href (etc) mean in that context (see where this is headed? 😉).

The simplest, no-additional-parsing-needed JSON-LD @context looks like:

{
  "@context": {
    "@vocab": "https://tools.ietf.org/html/draft-wilde-linkset-02#"
  }
}

If that were (or could be) added to an application/linkset+json file or (more likely right now) served as a Link header-based context (see Interpreting JSON as JSON-LD), then href would have the globally unique identifier https://tools.ietf.org/html/draft-wilde-linkset-02#href (based on the @context above)--i.e. the value of @vocab is string concatenated to the terms used throughout the document.

Even if the developer receiving the data doesn't yet know what the terms mean--or even that the @vocab concatenation happens in a JSON-LD processor, they still have the benefit of receiving an absolute URL (or even just a more verbose/meaningful identifier) to use in figuring out what things mean in the document.

The other things expressible via the @context object (or file) build on that to provide even clearer "meaning" to the data included--what things are strings, what things are language values, what things are URLs, etc.

Here's an article I wrote awhile back that explains a bit more of the value proposition (even if you don't do RDF): https://blog.codeship.com/json-ld-building-meaningful-data-apis/

@dret

This comment has been minimized.

Copy link
Owner

dret commented Aug 24, 2018

@dret

This comment has been minimized.

Copy link
Owner

dret commented Sep 12, 2018

one very simple question for the proponents of supporting JSON-LD: does the recently published JSON-LD 1.1 still mandate that a context must always be specified? i am not quite sure how to make things work otherwise, but i simply don't know enough about 1.1 to know the answer. thanks!

@BigBlueHat

This comment has been minimized.

Copy link

BigBlueHat commented Sep 12, 2018

@dret it isn't JSON-LD without a context specified. 😃 However, you can specify a context in either the content (via @context) or in a Link header (see Interpreting JSON as JSON-LD).

However, picking up from where we were earlier:

Developers will have to understand the JSON /somehow/ the context in JSON-LD is that "how."

that's true for JSON-LD users, which is a tiny subset. the usual way is to read the spec. it may not be what you like of prefer, but it's the reality of today's API space.

In the JSON linkset spec, the "how" JSON developers understand what's in the JSON is via a unique media type for linksets and looking up that meaning by finding the RFC for the linkset media type.

In a JSON-LD document, the context provides that "how". JSON-LD processors can use that context to create full URLs to each term--which can (at the discretion of the vocabulary owner) load documentation for each term (see https://schema.org/Article and https://schema.org/articleBody etc). This can be accomplished completely without knowing about RDF.

Additionally, with a very minimal understanding of the intention of @context and @vocab a developer can create such dereference-able term URLs using a context as simple as:

{
  "@context": {
    "@vocab": "https://tools.ietf.org/html/draft-wilde-linkset-02#"
  }
}

The @vocab value can be concatenated with any term (key name) found in the document resulting in URLs like: https://tools.ietf.org/html/draft-wilde-linkset-02#anchor Those URLs could be page anchors within the RFC, and you'd have provided in context references to documentation as well as globally unique identifiers for the key names used within the format.

To accommodate this sort of "value add", the current linkset spec would first need to be reshaped as an object containing an array--as arrays provide nearly no extensibility mechanism...if any, really...

So, something like...

{
  "linkset": [
    {
      "href"   : "http://example.com/foo",
      "anchor" : "http://example.net/bar",
      "rel": [ "next" ]
    }
  ]
}

With that in place adding some contextualization is a trivial addition:

{
  "@context": {
    "@vocab": "https://tools.ietf.org/html/draft-wilde-linkset-02#"
  },
  "linkset": [
    {
      "href"   : "http://example.com/foo",
      "anchor" : "http://example.net/bar",
      "rel": [ "next" ]
    }
  ]
}

Even if you don't (yet? 😉) see the value of what JSON-LD provides, reshaping the linkset data into top-level JSON objects (instead of arrays), give JSON-LD folks (and many others...including your future self), the opportunity to extend the format further. So I'd start there at least. 😁

@dret

This comment has been minimized.

Copy link
Owner

dret commented Sep 12, 2018

@BigBlueHat

This comment has been minimized.

Copy link

BigBlueHat commented Sep 12, 2018

i know all of the mechanics. we just disagree on how to balance mandating those mechanics, and the subset of people actually using them.

I know you know the mechanics, of course. 😃 Just restating them for clarity (for others) and for my own rethinking value. Every media type presumes a similar set of required understanding, parsing, and intended use. JSON-LD just happens to be a widely used and quickly growing flexible overlay on top of "raw JSON" and the plethora of on-off +json media types each with their own semantics and intentions and use cases.

It's ground to build up from vs. unique, one-off media type "house." Any option out there will require additional parsing/processing/understanding, JSON-LD is just an increasingly common foundation for building JSON-based things.

/me gets off soapbox. 😉

I've filed #105 which should help everyone. Do let me know if you need/want anything from the JSON-LD WG or the in-progress 1.1 spec. Help welcome! https://www.w3.org/2018/json-ld-wg/

@csarven

This comment has been minimized.

Copy link
Contributor

csarven commented Jan 27, 2019

I'd also like to show support for @stain 's proposal re closer alignment with JSON-LD.

The only thing I'd like to raise here is whether there is a possibility to rename the "anchor" term to "id". I don't know if I'm overlooking anything, so let me know. I personally find "anchor" and "href" too close semantically at first glance.

To build on the JSON-LD-readable approach, while still being JSON-readable, I'd propose to use the term "@id" or ("id" with context) replacing "anchor". Using id may be more clear in terms of fixing the primary subject of the expression in which everything else is in relation to. So, "right away" we know that next or license is about that id. With "anchor" and "href" it is not particularly intuitive (IMHO!) .. and if rev is used anywhere, it gets confusing.

In the case where anchor is optional as per:

Each link object MAY have an "anchor" member with a value that
represents the link context. If this member is not provided, the
link context is the link set resource

( also mentioned in #80 (comment) )

"@id" value can be empty: "@id": ""

@dret

This comment has been minimized.

Copy link
Owner

dret commented Jan 28, 2019

@csarven

This comment has been minimized.

Copy link
Contributor

csarven commented Jan 28, 2019

@dret Got it. I agree.

@hvdsomp

This comment has been minimized.

Copy link
Collaborator

hvdsomp commented Jan 30, 2019

I was wondering whether, in the proposal by @Stian, it would not make things easier if the hrefs would always be expressed in an array, instead of only using an array when there's more than 1 href. E.g. (adding linkset as per #103):

{
  "linkset":
  [
    {"anchor" : "http://example.net/bar",   
     "license": [
         {"href": "https://creativecommons.org/licenses/by/4.0/“}
     ],
     "author": [ 
         {"href": "http://orcid.org/0000-0001-9842-9718"},
         {"href": "http://orcid.org/0000-0002-1267-0234"}
     ]
    }
  ]
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment