HTTP parameters for specifying context or frame

[gkellogg]

When requesting JSON-LD from an HTTP endpoint, it would be useful to provide a reference to a context or frame which should be used by the server to put the results into the proper format.

• Note that this could be an attack vector on the server, so some provision for white-listing may be in order.

Original issue is JSON-LD 1.1 Feature Request : define how to specify the json-ld profile in a request to a server and include framing as an option #491

[RubenVerborgh]

We should align this with the work in the W3C DXWG (e.g., w3c/dxwg#261)

[ajs6f]

Six kinds of +1. In the field this issue comes up for me at least every three months or so! 😁 The potential for DOS is real, but the need is pressing.

[azaroth42]

Propose to discuss this at TPAC in a joint session with DXWG.

[ajs6f]

@azaroth42 Is there a DXWG issue to which we can link this?

[azaroth42]

w3c/dxwg#261 :)

[iherman]

This issue was discussed in a meeting.

• RESOLVED: Add text to Iana Considerations explicitly allowing the request of a context or frame document, plus security consideration on whitelist, plus tests

View the transcript

Rob Sanderson: we can use space separated lists of URIs, so the profile=”” parameter can contain both the compaction, etc. defined URIs
… as well as a JSON-LD context or frame URI
… however, these URIs might collectively get quite long
Adam Soroka: if you specify a URI don’t you want it to be compacted?
Rob Sanderson: it could be a frame
Gregg Kellogg: or a bomb
Benjamin Young: or a cat photo
Adam Soroka: do we want to have a default use like it’s assumed it’s a context URI?
Ivan Herman: what would this look like in practice?
Rob Sanderson: I’ll write it up…one second…
Rob Sanderson: ACCEPT: application/ld+json;profile="http://w3.org/ns/anno.jsonld"
Rob Sanderson: this would say, “I want this request compacted according to this context”
Gregg Kellogg: if that JSON-LD URL returns a context
Benjamin Young: don’t dereferences things found in profile params
… because proxies
Gregg Kellogg: right, security concerns/needs should be expressed
Benjamin Young: we used the entire string as the “media type” for Web Annotation
… with no expressed intent or idea of dereferencing that context URI
Adam Soroka: I’m not too worried about big headers
… if you’re going to be this particular about it, then that’s a “cost” you’ll face
Rob Sanderson: and the multiple URIs in profile=”” is not a problem?
Adam Soroka: no, I think that’s fine
Rob Sanderson: if you don’t care if you’re flattened or compacted, then don’t state it and use the context for whichever you’re returning
Benjamin Young: is there priority among these strings?
… or do they just work as flags?
Rob Sanderson: they’re just flags
Adam Soroka: do we want q=”” parameters for this?
Rob Sanderson: I’d say it’s an error condition to have multiple contexts given
Benjamin Young: is the intent to continue–as Web Annotation did–as a single opaque string?
… or are we switching on each piece?
… mostly it’s a question for me about upgrading existing Web Annotation servers (and the like)
… so are they opaque “whole” strings? or are we taking them apart in some way?
Rob Sanderson: so, in the case of compaction at least, we could have a default that maps to compaction
… which is how profile=”” is used in the cases that we know
Gregg Kellogg: are you going to help write these tests?
Rob Sanderson: sure. I’ll help write those tests
… and the paragraph/dependencies
Gregg Kellogg: and at the moment we don’t have complete HTTP header tests…but need those
Rob Sanderson: I know someone (bigbluehat) who’s done this already
Benjamin Young: we’re continuing the Web Annotation validation/testing tooling work at http://annotator.apache.org/
Gregg Kellogg: so, there are a few HTTP tests now
… they were originally in an .htaccess file
… but right now it’s left up to the implementations to act as if the headers were expressed in the responses or not
… the test suite should ideally run off a W3C mirror that implement these .htaccess
Benjamin Young: curious which bits you needed in .htaccess
Gregg Kellogg: there’s a remote access manifest in the API
Gregg Kellogg: https://github.com/w3c/json-ld-api/blob/master/tests/remote-doc-manifest.jsonld
Gregg Kellogg: for example https://github.com/w3c/json-ld-api/blob/master/tests/remote-doc-manifest.jsonld#L34
… this one tests a application/jldTest content type
… which in this case should fail
… others here deal with redirects
… also, another for the Link header https://github.com/w3c/json-ld-api/blob/master/tests/remote-doc-manifest.jsonld#L84
… for all of these we’re analyzing the JSON-LD result
… so we probably want similar ones analyzing the HTTP headers themselves
Proposed resolution: Add text to Iana Considerations explicitly allowing the request of a context or frame document, plus security consideration on whitelist, plus tests (Rob Sanderson)
Rob Sanderson: +1
Gregg Kellogg: +1
Adam Soroka: +1
Benjamin Young: +1
Ivan Herman: +1
Resolution #5: Add text to Iana Considerations explicitly allowing the request of a context or frame document, plus security consideration on whitelist, plus tests

[gkellogg]

Something to resolve:

If the ACCEPT header includes a json-ld media type with a context or frame profile that the server won't support (e.g., black/white list) I presume it would skip that request and go to the next highest-priority media type it supports (possibly application/ld+json without a profile or without a specific context/frame) returning status 415 if none found.

This could mean not returning any JSON-LD if profile cannot be satisfied.

Alternatively, the server should satisfy the request as best it can without consideration of the profile parameter.

[ajs6f]

I'm not sure if I'm getting at your point, @gkellogg, but my understanding of HTTP (based on the old RFC and possibly out of date) is that the mediatype alone is what Accept selects on-- the profile can't change that choice. So once application/ld+json is the choice, whatever happens with the profile can't change that, and therefore we can select from various options, but tossing to the next mediatype should be the last. But I welcome correction!

[Conal-Tuohy]

I think it's correct that the server is supposed to consider the entire value of the Accept header, including any media type parameters (profiles, etc) in deciding which is the best representation of the resource. RFC7231 gives an analogous example of selecting among various kinds of plain text:

https://tools.ietf.org/html/rfc7231#page-39

I think it would be good practice for clients to specify both a profile and also "unprofiled" JSON-LD (if they can actually accept that), e.g. application/ld+json, application/ld+json;profile=foo. It' should not be necessary for a client to specify a lower q value for generic application/ld+json than for application/ld+json;profile=foo, because the server ought to prefer the "more specific" value anyway.

If a client sends Accept: application/ld+json;profile=foo without also application/ld+json, the server could either return a 406, or could return a 200 with its own "best guess" content type (as it would be entitled to do if the client had not sent an Accept header at all). In such a case, it would make sense, to me, to return JSON-LD rather than some other RDF media type.

[ajs6f]

Wow, I got that completely backwards! Thanks for the correction, @Conal-Tuohy.

Given that many clients will be expecting to use compacted JSON-LD as JSON, I think a 4xx is by far the best answer here. Non-compacted forms are going to be more surprising and troublesome than helpful to such clients.

[gkellogg]

Better than status 415 is status 406 "Not Acceptable":

The target resource does not have a current representation that would be acceptable to the user agent, according to the proactive negotiation header fields received in the request, and the server is unwilling to supply a default representation.