how to use the `frame` and `framed` profiles?

[VladimirAlexiev]

#132 cites the text of two specs regarding frame and framed profiles:

https://www.w3.org/TR/json-ld11-framing/#iana-considerations:

http://www.w3.org/ns/json-ld#framed
To specify a JSON-LD Frame.
The http://www.w3.org/ns/json-ld#framed SHOULD be used when serving and requesting a JSON-LD frame document.

https://w3c.github.io/json-ld-syntax/#application-ld-json

This specification defines six values for the profile parameter.
http://www.w3.org/ns/json-ld#frame
To request or specify a JSON-LD frame document.
http://www.w3.org/ns/json-ld#framed
To request or specify framed JSON-LD document form.

The third spec https://w3c.github.io/json-ld-api/, as far as I can see, does not specify where the frame and context parameters come from in HTTP exchange.

---

So it would be nice to give some examples on correct use of HTTP headers regarding the use of specific context and frame.
From what I could glean by googling (please comment whether that's correct!)

REQUEST

I1. To request a particular profile/context for jsonld,
according to https://www.rubydoc.info/gems/triannon#get-a-particular-anno:

Accept: application/ld+json; profile="http://www.w3.org/ns/oa-context-20130208.json"
Accept: application/ld+json; profile="http://iiif.io/api/presentation/2/context.json"

I2. To request a particular context for "jsonld as json" (note: type pertains to the context document, not the payload document):

Accept: application/json
Link: http://www.w3.org/ns/oa.json; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

I3. To request jsonld with a particular context and frame

Accept: application/ld+json; profile="http://www.w3.org/ns/json-ld#framed"
Link: http://example.org/context.jsonld; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
Link: http://example.org/frame.jsonld;   rel="http://www.w3.org/ns/json-ld#frame";   type="application/ld+json"

RESPONSE

O1. jsonld as json with a particular context:

Content-Type: application/json
Link: https://example.org/context.jsonld; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

O2. jsonld that is framed and uses a particular context (the Links are redundant)

Content-Type: application/ld+json; profile="http://www.w3.org/ns/json-ld#framed"
Link: http://example.org/context.jsonld; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
Link: http://example.org/frame.jsonld;   rel="http://www.w3.org/ns/json-ld#frame";   type="application/ld+json"

O3. jsonld that uses a particular context,
according to https://iiif.io/api/presentation/3.0/#63-responses:

Content-Type: application/ld+json;profile="http://iiif.io/api/presentation/3/context.json"

Questions

• Q1. Is profile used to specify the kind of jsonld (eg framed, compacted, expanded),
  • or the context (i.e. are the iiif and triannon examples wrong?)
• Q2. Can one use multiple Link headers as per I3, O2?
• Q3. (!) How can one specify which version to fetch, 1.0 or 1.1? The version may have significant performance impact, at least for Java-based repos, because jsonld-java (old) supports only 1.0 but is 4.6x faster than titanium (new) that supports 1.1: JSON-LD 1.1 support eclipse-rdf4j/rdf4j#3654

[gkellogg]

IIRC, the WG determined that it was outside scope to actually define how to specify a frame to use when requesting framed document form.

This is discussed in the transcript part of #21 (comment) to a degree and in w3c/json-ld-syntax#8 (comment). We rejected defining a specific way to identify a particular context or frame due to security concerns. The notion was that a white-list of specific frames and contexts might be acceptable, but arbitrary documents was not something we could do.

Note the specifying both a context and a frame would be redundant, as framing compacts using the context contained within the frame document.

• Q1. Is profile used to specify the kind of jsonld (eg framed, compacted, expanded),
  • or the context (i.e. are the iiif and triannon examples wrong?)

No, they just specify that you'd like the document returned in compacted or framed form, without specifying a way to define the specific context of frame to use. Applications may define their own profiles for doing this. Note that section 6.1 Interpreting JSON as JSON-LD does provide a way to specify a document, but in our infinite wisdom, it does not apply to application/ld+json.

• Q2. Can one use multiple Link headers as per I3, O2?

Yes, for example "compacted and framed".

• Q3. (!) How can one specify which version to fetch, 1.0 or 1.1? The version may have significant performance impact, at least for Java-based repos, because jsonld-java (old) supports only 1.0 but is 4.6x faster than titanium (new) that supports 1.1: JSON-LD 1.1 support, switch to titanium-jsonld? eclipse/rdf4j#3654

The version can be specified through the API; there isn't a way to do it using HTTP headers that I can recall. Generally, JSON-LD 1.1 is forward compatible with 1.0, so the emphasis was on ensuring that a 1.0 processor wouldn't incorrectly process a 1.1 document.

[VladimirAlexiev]

hi @gkellogg !

a white-list of specific frames and contexts might be acceptable, but arbitrary documents was not something we could do.

Seems a reasonable concern, and advising servers to only allow whitelisted frame docs is sound advise.

• However, if several frames are applicable to some data, how would the client select one? It seems to me that in following the security consideration, the WG has thrown out the baby with the bathing water.
• Is the work on "profile negotiation" https://www.w3.org/TR/dx-prof-conneg/ relevant here?
  In contrast to the examples above (Accept: ... profile and Content-Type: ... profile), this uses dedicated headers Accept-Profile and Content-Profile:

During 2018, DXWG members had a longer discussion with the JSON-LD WG at the annual forum TPAC in Lyon, France and it was concluded that the "profile” parameter in the Accept and Content-Type headers should be seen to convey profiles that are specific to the Media Type, such as JSON-LD's "expanded" (http://www.w3.org/ns/json-ld#expanded) or "flattened" (http://www.w3.org/ns/json-ld#flattened). In order to signal the use of Media Type-independent profiles, the http header fields Accept-Profile and Content-Profile are to be used.

Requesting 1.0 vs 1.1: can I raise such an issue, and which would be the appropriate project?
As mentioned above, that has significant performance impact in all Java-based sem web servers.
And because 1.1 is significantly more complex to process than 1.0, the same performance consideration probably applies to other implementations?

[VladimirAlexiev]

No way to request a particular Frame, nor to request 1.0 vs 1.1.
Seems to me JSON-LD needs Profile Negotiation? @msporny @larsgsvensson @rob-metalinkage @RubenVerborgh @nicholascar

[gkellogg]

You can request 1.0 via the API, but there's no CN way to do it that I can think of. The rationale was that 1.1 was forwards compatible with 1.0, and some of the differences (e.g., use of @graph at the top) could be configured through either options or framing keys.

The best we could probably do on specifying a particular frame to use would be some group Note, due to the security concerns noted. Of course, such a note can always be drafted and be a WG Note if it is approved by the WG. (Getting a quorum is probably the hardest part, right now). It may be that the best place would be to add it to the current Best Practices Note. Contributions to this note are encouraged.

As an aside, I see that the permanent location of that note (https://www.w3.org/TR/json-ld-bp/), which may not even be correct for a Note, is 404 not found, so the group needs to do something to address that. Also, the top result on Google is the old CG Draft, which is obsolete, and should redirect to the WG Note, once it's properly published. Maybe @iherman, @azaroth42, or @BigBlueHat remembers something about the publication history of this note.

[iherman]

As an aside, I see that the permanent location of that note (https://www.w3.org/TR/json-ld-bp/ <https://www.w3.org/TR/json-ld-bp/>), which may not even be correct for a Note, is 404 not found, so the group needs to do something to address that. Also, the top result on Google is the old CG Draft <https://json-ld.org/spec/latest/json-ld-api-best-practices/>, which is obsolete, and should redirect to the WG Note, once it's properly published. Maybe @iherman <https://github.com/iherman>, @azaroth42 <https://github.com/azaroth42>, or @BigBlueHat <https://github.com/BigBlueHat> remembers something about the publication history of this note.

Per the [official list of publications](https://www.w3.org/groups/wg/json-ld/publications) this document was never published as a Working Group Note (although it was planned). I presume the group simply ran out of steam by the end. The [editor's draft of the document](https://w3c.github.io/json-ld-bp/) does exist, but it should not refer to the /TR URLs (actually, it should not say WG Note either). The respec settings should be updated...

[rob-metalinkage]

Hi

apropos of this discussion, the OGC also needs to land on a way to offer and advertise different frames for the same object - for example many different possible ways of geometrically representing objects - points, polygons, 3D objects, 4D moving object tracks etc. This was a motivation behind work on dx-prof-conneg. Whilst this conversation is not terribly mature due to unfamiliarity with JSON-LD and tooling availability, the use of JSON-LD and framing in conjunction with OGC API (OpenAPI based) is being explored in innovation activities.

A tool chain based on this in the RDFLib world has implemented https://www.w3.org/TR/dx-prof-conneg/ - what we lack is good JSON-LD serialisation tooling.

A PR to update RDFLib to use the PyLD implementation of JSON-LD looks a promising way forward (see RDFLib/rdflib#1836) - IMHO this would gain some impetus with a couple of examples how to use context and frames in pyld.

[RubenVerborgh]

Very happy to have my team examine the frame link with profile-based conneg; let me know if we can help.
We will be doing such work in the near future anyway, so better to be connected.

[gkellogg]

The original person asking to be able to specify a frame as part of a request was @lisp, who may have done something based on the WG discussions.

[rob-metalinkage]

ps - I dont think JSON-LD needs profile negotiation - profiles (i.e. frames) need a URI and ideally a token, and ideally the URI resolve to a description using the PROF vocab in JSON-LD (with normal content negotiation :-) )

we need a BP described for this - but its not normative for JSON-LD itself IMHO.

[VladimirAlexiev]

@RubenVerborgh @rob-metalinkage @lisp @gkellogg any news on this?

w3c/json-ld-syntax#402 is a bit related

[lisp]

i do not think it news.
we added support two years ago for ld+json metadata which combined the "I2" context source from your initial description with a media type profile for compact/expand/flatten.

i have not seen use of the context link, but then, we are primarily concerned with generating ld+json for sparql responses, in which case the query already provides ample opportunity for aliasing and we do not incorporate a context (reference) in the response. there has been some interest in the latter but it seems perverse to send and reflect back to the client something which is, in that case, entirely a client matter.

[VladimirAlexiev]

https://graphdb.ontotext.com/documentation/10.5/exporting-data.html#fetch-statements-from-repository and the next section state that in GraphDB 10.5 you can use :

• Accept: application/ld+json;profile=http://www.w3.org/ns/json-ld#<type-of-mode>' where mode is compacted, expanded, flattened, framed (we'll make this more explicit)
• Link: <link_to_the_context_location>; rel="http://www.w3.org/ns/json-ld#context" to specify the context

Hopefully in GraphDB 10.6 (https://ontotext.atlassian.net/browse/GDB-10236) one will be able to use

• Link: <link_to_the_frame_location>; rel="http://www.w3.org/ns/json-ld#frame" specify the frame