search

w3c / json-ld-framing

JSON-LD 1.1 Framing Specification
https://w3c.github.io/json-ld-framing/
Other
24 stars 20 forks source link

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

Open VladimirAlexiev opened 1 year ago

VladimirAlexiev commented 1 year ago

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

gkellogg commented 1 year ago

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 https://github.com/w3c/json-ld-framing/issues/21#issuecomment-462051253 to a degree and in https://github.com/w3c/json-ld-syntax/issues/8#issuecomment-433597582. 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".

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 commented 1 year ago

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.

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 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 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 commented 1 year ago

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 https://github.com/RDFLib/rdflib/pull/1836) - IMHO this would gain some impetus with a couple of examples how to use context and frames in pyld.

RubenVerborgh commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

https://github.com/w3c/json-ld-syntax/issues/402 is a bit related

lisp commented 1 year ago

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 commented 1 month ago

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 :

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