Content Negotiation for JSON-LD Context Documentation #43
Comments
|
The advantage of this approach is that... we have nothing to do:-). This is possible on today's Web and a number of sites do it already. That is good... However, I do want to understand our use cases, which is blurry for me. If we are considering more or less institutional publishers of context files, like schema.org, or W3C publishing, e.g., an (extra) context file to be used for Web Publication Manifests, then this is a good approach. However, I continue to question whether this is appropriate for individuals or organizations that do not have major expertise in Web site management, who may run everything via a cloud provider with some sort of a basic hosting service, etc. For all those, content negotiation is an unknown, un-understandable, and scary notion that they cannot control anyway. (Try to show that Apache reference to a layperson, and get that person to modify the httpd.config file if he/or she has even access to it. The person would run away screaming...) In other words, content negotiation should never be the solution, but only a (very elegant) solution imho. Ie: who is our target audience for this use case? |
Developers. 😃 Like the ones who would be publishing custom JSON-LD contexts and documentation. |
|
+1 to @iherman's concern about complexity. Content Negotiation is a sophisticated technique that cannot be implemented in all hosting environments easily, such as (for example) github pages. Recommending conneg seems like a good practice, but requiring it less so. |
|
I'm not sure we would be requiring it as much as offering it as a technique for those who can use it. (Developers!) |
|
Right. It would remain a best practice, not a requirement. |
|
WG consensus to close documentation issues, with a future action to consider best practices around documentation rather than syntax / normative requirements. Resolution: |
ghost
removed
the
This is one of the four documentation proposals discussed on August 3rd to answer questions/concerns in #32.
This approach is described in Best Practice Recipes for Publishing RDF Namespace Vocabularies. It is a popular approach currently in use by Schema.org as well as the W3C's ActivityStream's 2.0 Vocabulary.
The Schema.org approach matches Recipe 5. Extended configuration for a 'slash namespace', using multiple HTML documents described in the Best Practices document mentioned above. Browser requests to https://schema.org/ return the "promo" site for Schema.org which contains documentation for each term as well as community and process related content. Each individual term page also contains RDFa-encoded RDFS comments, labels, etc. Each of these URLs (the main site's URL and each term page's URL) may be content negotiated for a wide range of other RDF formats. See https://schema.org/docs/developers.html for more information.
The ActivityStreams 2.0 approach is a variation on Recipe 3. Extended configuration for a 'hash namespace' where the returned single-page HTML file contains links with
idattributes which match the term's name within the "hash namespace". So https://www.w3.org/ns/activitystreams#Activity is both the JSON-LD term's expanded IRI and also results in a link to the human-readable Activity class's documentation.The basics of Content Negotiation are below--but better, more complete examples are contained in the Best Practices documentation above.
Requesting Documentation
(or
Accept: */*in this case because HTML documentation is the default representation)Requesting the Context File
Setup
This setup can be done via Apache ships with mod_negotiation enabled--see their Content Negotiation pages for more information.
Configuration is also possible for Nginx.
Additionally, most modern server-building frameworks for JS, Python, etc, include simple Content Negotiation enabling functions such as Express.js'
res.format().The text was updated successfully, but these errors were encountered: