Confusing disparity between names in data model and vocabulary

[gklyne]

I've just been burned by a disparity between names used in the data model document and the vocabulary document - it just hadn't occurred to me that they might be different, though looking at the published JSON-LD context they clearly are. E.g. the data model document uses "target" and "body", where the vocabulary context maps these to "hasBody" and "hasTarget".

It's clearly too late to change this now, but I think it might help to draw attention to this difference in http://www.w3.org/TR/annotation-model/#serialization-of-the-model, http://www.w3.org/TR/annotation-vocab/#diagrams-and-examples and http://www.w3.org/TR/annotation-vocab/#json-ld-context

For context here, I am using annotation vocabulary terms in JSON-LD, along with a number of other vocabularies, as part of wider linked data information models. (All terms used are namespace-qualified, so it doesn't conform to the JSON-LD examples.) In this context, I find the divergence between the JSON-LD nomenclature suggested and the RDF vocabulary terms to be pretty confusing.

I'm also wondering at the context given in http://www.w3.org/TR/annotation-vocab/#json-ld-context being non-normative. This seems to suggest that the suggested JSON representation (using "body", "target", etc.) is non-normative, but that seems to go against recommendations elsewhere in the specifications - e.g. "The examples throughout the document are serialized as [JSON-LD] using the Context given in Appendix A of the Annotation Vocabulary [annotation-vocab], which is the preferred serialization format" -- http://www.w3.org/TR/annotation-model/#serialization-of-the-model

I also just noticed the link in "declarations given in Appendix A. " (section 1.2 vocabulary doc) is incorrect - links to the namespaces section not Appendix A.

[BigBlueHat]

That section should've been much clearer... How do we handle improving things like this post-publication @iherman?

The discrepancy seems to be around audience for the vocab spec vs. the data model spec. One focuses on folks who "traffic" in vocabulary infused data (RDF formats), and the other focuses on JSON-focused development providing the JSON-LD goodness to bridge those too worlds.

@gklyne tnx for reporting this! If you have specific text advice, I do agree this needs to be clarified from at least the vocab document.

[gklyne]

I don't think this is fully solved simply by addition of text, but it maybe would help to add something like the following to https://www.w3.org/TR/annotation-model/#serialization-of-the-model:

NOTE that the terms used in JSON-LD serialization assumed by the JSON-LD context may differ from the linked data URI local names; e.g., the JSON-LD serialization uses target and body, where the vocabulary context maps these to oa:hasBody and oa:hasTarget. Using the linked data URIs (or CURIEs) in JSON-LD data files should result in an equivalent RDF graph, but the JSON data may fail to be correctly processed by software that expects the specific JSON serialization indicated by the context file.

(I feel that for applications that combine OA terms with other RDF vocabularies, where processing as linked data is assumed, it makes more sense to use the RDF vocabulary terms than the JSON format.)

[RinkeHoekstra]

Adding to this, why does the JSON-LD version of the ontology not use the anno.jsonld context?