Skip to content
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

Put the linkset array inside an object #103

Open
BigBlueHat opened this Issue Aug 22, 2018 · 12 comments

Comments

Projects
None yet
4 participants
@BigBlueHat
Copy link

BigBlueHat commented Aug 22, 2018

Using an array as your top-level container cuts of the opportunity to add information about all the items in the array, it's provenance, extensions, etc. It greatly limits what's possible.

Consider reshaping:

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

to:

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

This opens the door to far more extensibility and clarity than the current "direct array" format.

Cheers!
🎩

@dret dret added the linkset label Aug 24, 2018

@dret

This comment has been minimized.

Copy link
Owner

dret commented Aug 25, 2018

@csarven

This comment has been minimized.

Copy link
Contributor

csarven commented Jan 27, 2019

Just jumping in to agree with @BigBlueHat 's proposal being a bit more useful - easier to create, manipulate.

@hvdsomp

This comment has been minimized.

Copy link
Collaborator

hvdsomp commented Jan 27, 2019

Yes, I am definitely in support of this too.

hvdsomp added a commit that referenced this issue Feb 27, 2019

Significant update, including introduction of new json serialization
A json serialization based on the approach proposed in #89, as well as the container approach proposed in #103 is specified in this revision.
@dret

This comment has been minimized.

Copy link
Owner

dret commented Mar 6, 2019

i agree in spirit, but i am hesitant about defining or even allowing other members in the top-level object. i do see use cases where this could be useful, but this would also make the two serializations not aligned anymore, as the native model does not have such a "top-level container".
the problem is that if applications add top-level metadata that change the semantics of the linkset, then it becomes implementation-dependent what the linkset represents. so we should mandate that any additional info in the top-level element cannot change the semantics of the linkset.

@BigBlueHat

This comment has been minimized.

Copy link
Author

BigBlueHat commented Mar 11, 2019

the native model does not have such a "top-level container".

Don't Link and <link> implicitly rely on their "top-level container"s? The surrounding context for much of their data and value typical comes from the surrounding HTTP message or HTML document: dictated by things like Request-URI or <base>.

Consequently, this linkset document has very little value currently because it's contextual use isn't knowable:

   [ { "href"   : "/foo",
       "anchor" : "/bar",
       "rel"    : [ "next" ] } ]

Accordingly the current linkset draft that should be valid, but relies on "baseURI"...which can't be expressed in the current format (afaict):

  The value of both the "href" and "anchor" members MUST be a URI-
  reference as defined in Section 4.1 of [RFC3986].  Note that for
  relative references, the baseURI is the URI of the link set
  resource.

So, if I wanted to state the baseURI of the document I'd extracted that linkset from where would I put it? I'd either have to absolutize all the URIs (which ultimately means there's a new requirement for linksets to only contain absolute URIs), or I need a place to encode it for the whole document...which is where the top-level object would come in real handy. 😁

FWIW, JSON-LD already has such a handy way to provide this specifically, so you could express the above as:

{
  "@context": {
    "@base": "http://example.com/page-i-pulled-links-from"
  },
  "linkset": [ { "href"   : "/foo",
       "anchor" : "/bar",
       "rel"    : [ "next" ] } ]
  }
}

Also, an extensibility provision could explain what should and should not be changed about the required terms and their usage. Since you have a dedicated media type for these documents, you could further enforce that processing and any extensibility requirements against the defined processing steps.

Anyhow. Extensible top-level objects are a Good Thing for all. 😸

@dret

This comment has been minimized.

Copy link
Owner

dret commented Mar 12, 2019

@BigBlueHat

This comment has been minimized.

Copy link
Author

BigBlueHat commented Mar 12, 2019

Link and <link> have no value outside of their contexts (afaict), so building a JSON format which encodes only their usage, but not their context seems insufficient. If the objective is to encode all of RFC 8288, then having the option (at least) to encode the contextual data (baseURI, etc), seems invaluable to this specification's purpose.

The JSON format seems to exist precisely to express things "out of context" (and link to that context via some other link with rel="linkset"), so if that JSON format does not encode the necessary contextual data won't that pragmatically make the JSON format's expression of the linkset model restricted to absolute URLs and ones that always include anchor? Otherwise, if a request were made for the linkset resource (or if that resource were just on disk somewhere) it would loose all its meaning and therefore value...would it not?

@dret

This comment has been minimized.

Copy link
Owner

dret commented Mar 12, 2019

@hvdsomp

This comment has been minimized.

Copy link
Collaborator

hvdsomp commented Mar 13, 2019

Note that in the most recent draft of the I-D, here in GitHub, a requirement was introduced to make all URIs absolute. That was basically an executive decision (by me), lacking input on #117 Obviously, the decision/proposal is open for discussion.

@dret

This comment has been minimized.

Copy link
Owner

dret commented Mar 13, 2019

@hvdsomp

This comment has been minimized.

Copy link
Collaborator

hvdsomp commented Mar 13, 2019

Could this just be done under #117? The problem statement over there lists expressing a baseURL as an option. Note that this option will not work for the application/linkset format. So, I am not sure I agree it is the better approach.

@dret

This comment has been minimized.

Copy link
Owner

dret commented Mar 13, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.