Specification's version in the manifest #16
Comments
|
There is a version term in schema.org, but I do not think it is appropriate here. The manifest terms give metadata about the publication and we are talking about a metadata on the specification that governs it. We could come up with some special, publication specific term, something on the form: "governingSpecification" : {
"url" : "https://www.w3.org/TR/2019/WD-wpub-20190101/",
"name": "Web Publications",
"date": "2019-01-01"
}a bit verbose, but probably better than sticking to a version number; we never discussed the whole issue of versioning yet. There may be several specifications, and that could be listed: audiobook profile, packaging spec, etc. |
We had the same problem with the EPUB Accessibility specification. We ultimately had to make do with dcterms:conformsTo, which is appropriate but lacked the ability to specify additional information (in our case, what level of WCAG conformance was achieved). |
|
Since we support links, we have built in extensibility to handle that. We
simply need to use the right rel value ("profile" being a good example) and
point to a URI that identifies a version or a profile.
|
|
What was exactly the problem with (We can also use other dcterm values in the body instead of schema.org terms like in my example.) |
EPUB was more the problem, as we were limited to a URI because of the lack of nesting so had to hack values into the URL as parameters. I had it in my head that conformsTo also only supported a URI. |
|
If we stick to "dcterms:conformsTo" : {
"dcterms:identifier" : "https://www.w3.org/TR/2019/WD-wpub-20190101/",
"dcterms:title": "Web Publications",
"dcterms:date": "2019-01-01"
} |
|
Apart from the complexity of such a structure compared to a simple integer versioning (1, then 2 etc.) or an URL equivalent (seen as a Subject supporting RDF properties), it must be underlined that namespaces are unknown from the json world and colons are badly supported in most languages as object properties (json being an object serialization ...). |
|
Hm. I never heard complains using JSON-LD with short URL-s, ie, colons in the terms... There is no need for namespaces, b.t.w. The schema.org context file includes the dcterms prefix, so we can use it out of the box as is. Of course, if we want to define some sort of a versioning scheme, we can do that, and indeed it makes it simpler. But I am always a bit wary of just saying 'version 1'. We can then have happy discussion about whether some changes mean '1.1' '2.0', or possibly '1.0.1.'... We can also simply say: "dcterms:conformsTo" : "https://www.w3.org/TR/2019/WD-wpub-20190101" |
|
JSON-LD-based documents are more or less versions by their You can see this sort of usage in the Verifiable Claims Data Model's Their specification text requires that conforming documents use that specific (versioned) context reference and that the reference (identifier) always be equivalent to the context object published in the specific (so that it can be cached permanently after publication). Building the specifications this way also makes verification of conformance something that can be validated programmatically vs. the documentation-style references of |
|
There has been lots of discussions in the past whether it is a good idea to add version number into the URL of a file like a context file (though the discussion centered around the URL-s used for namespaces). One of the examples from the past is foaf which, up to today, uses the I do not have strong feelings about it; I am mildly more in favour of using a stable URL for our context and push the versioning information into the data if needed. |
|
@llemeurfr, per https://github.com/w3c/wpub/issues/404#issuecomment-464092661: actually, the example in https://github.com/w3c/wpub/issues/404#issuecomment-464087617 can be further simplified by: "conformsTo" : {
"identifier" : "https://www.w3.org/TR/2019/WD-wpub-20190101/",
"title": "Web Publications",
"date": "2019-01-01"
}if we want, by adding explicit URL-s into our context file. We have the absolute freedom to do so, although we have to be careful not to create a clash with schema.org terms. So really the question is whether we want to have such structures or we simply use a URL/literal as the value of If we go for the latter, we will have to define some sort of a versioning scheme that we stick to for the years to come. Great dinner table discussion:-) |
|
To illustrate my proposal based the "links": [
{
"url": "https://www.w3.org/TR/2019/WD-wpub-20190101/",
"rel": "profile"
}
]This information can also be expressed in HTTP headers, which could be quite useful. |
|
This issue was discussed in a meeting.
View the transcript5.1. Issue #16 Specification’s version in the manifestGarth Conboy: See Issue #16 Garth Conboy: One other wasn’t postponed, and hasn’t been addressed for some time - issue 16 - to do with version in the manifest. … is this obviated or are we still live? … we didn’t get to a satisfying conclusion… all: silence Wendy Reid: I do love the aspirational nature of the question Charles LaPierre: Looking at this, because it also goes in line with the accessibility specification, with the conforms-to suggestion, I like that you can specify the version number and have all the information right there… … we have that already as a basis for conformance to the a11y spec… … but we’re trying to avoid compatibility issues, if we have a version in the future which requires special handling, if we don’t put it in there now we could be in trouble… Dave Cramer: I hope we can avoid having version numbers on this. Wendy Reid: +1 Dave Cramer: it feels like a nightmare of incompatibility and writing special paths and code etc.… … we’ve managed to avoid it in HTML and CSS, let’s really try not to go there… Garth Conboy: One can also argue that even if we do choose to go there, we don’t have to go there at the first try… Ivan Herman: I agree - if we look back at the comments; if we want to express conformance with a version of the specification, there is a comment I made in Feb which said you can put this kind of information in the manifest… … there’s a way of using dc terms to do that… … if this information is necessary in the document, we can do that with the manifest… Proposed resolution: close #16 without action (not adding version numbering) (Garth Conboy) Wendy Reid: +1 Ivan Herman: +1 Dave Cramer: +1 Garth Conboy: +1 Nellie McKesson: +1 Geoff Jukes: +1 Charles LaPierre: +1 Benjamin Young: +1 Deborah Kaplan: +1 Simon Collinson: +1 Resolution #6: close #16 without action (not adding version numbering) Ivan Herman: I agree with this, maybe we can ask Matt to put in an example of how this would be provided as an information - if someone were to do that, how they would go about it Ivan Herman: … a full example with DC or a simpler version thereof Garth Conboy: This is with dc terms ‘conforms to’? Ivan Herman: Yes, conformsTo. Action #1: add an informational text on using dcterms (Matt Garrish) |
|
Closing this with #59 |
Since we created a first propotype of Web Publication based on the current specifications, I wondered how to indicate in the manifest that it refers to the current specifications alpha or beta version.
In general, if in a few years we will define Web Publication 2.0, how will a User Agent distinguish current Web Publications from future ones?
The text was updated successfully, but these errors were encountered: