How to hint at previous versions of an annotation?

mk-pmb commented 2 years ago

Our annotation application allows authors to edit their annotations later. We have one URL that always points to the latest version, and each version also has its own specific URL so they can be referenced in citations and comments. Readers should be able to discover that there are older or newer versions available. We thus need a way to associate the various versions with each other. Is there a preferred way?

The obviously least interoperable way would be to create our own Anno Extension. Just mentioning it for completeness.

Better would be to reuse one of the vocabularies defined in the Anno-Vocab JSON-LD Context.

Possible candidates that I found:

dc/dcterms/dctypes: Dublin Core

dc:source could be used to reference the previous version, but it stretches the meaning of "derive". Should not be used because we have better (more specific) choices:
dcterms:replaces describes a related resource as "superseded" by the current resource – sounds like a perfect match to link the previous version, and its counterpart dcterms:isReplacedBy can point to the next version.
dcterms:isVersionOf can be used to link to the current version of the annotation.
dcterms:hasVersion can be used to link from the latest (or even any) version of the annotation to all (older) versions.

Possible problems:

The documentation linked in the anno vocab context required I solve a CAPTCHA even for mere read access. (The usual Cloudflare vs TOR paranoia.) For me, this seeds initial doubt about how much their governing org is committed to free exchange of information. As far as I understand the JSON-LD context, it is meant for being processed by automated agents, so a CAPTCHA in this context is even more counter-productive than usual.
- Fortunately, fellow librarians offer an archived version for unconditional public reading.

iana: Link relations

memento and timemap from RFC 7089 would probably be the most well-defined and thus machine-readable, but on first glance seem cumbersome to implement.
Simple Version Navigation (RFC 5829) seems to be an exact match for our purpose.
- version-history and latest-version in our case would happen to be the same.
- predecessor-version and successor-version by original definition seem to expect a version exactly one step apart. My idea to make the latest version carry an array of all prior versions as iana:predecessor-version might be too much of a stretch.
- Looks easier to implement than memento, and still as useful, because all relevant time/date information can be read indirectly from the annotations.
iana:current could denote the latest version.
- same for last and latest-version
- RFC 5005 specifies current together with next-archive/prev-archive, also first/last and next/previous, but they are meant for news feeds. Not sure how much of a stretch it would be.
iana:archives could denote a document that lists versions, which in our case would happen to be the latest version.
- same for index
item and collection are too generic.

skos: Simple Knowledge Organization System

skos:broader could be used to denote a URL that always points to latest version.
skos:narrower could be used in the latest version to link to specific (older) versions.

These sound valid solutions but are less specific than dcterms:*.

Other

Activity Streams: as:attributedTo could denote the latest version. However, we're less interested in documenting the activity of editing, but rather its results. Thus, AS don't seem appropriate.
FoaF: Knows about documents but doesn't care about their history.
RDF: maybe rdfs:member and rdfs:seeAlso but too generic.
XSD: purpose mismatch
Web Ontology Language (OWL): purpose mismatch
Schema.org: has isBasedOn but it would be misleading in cases where the new version is a full rewrite, or entirely unrelated if the previous version was the result of a copy-and-paste accient.

Treora commented 2 years ago

Great list of candidates. I did not know about or look at every candidate you mention, but some thoughts, hopefully of any help:

Versioning of web resources is such a generic problem, and as old as the web, that it would be awkward to make a versioning system that is specific to annotations.
The next-archive and previous-archive in RFC 5005 that you mention seem to mean something different than what is intended here.
RFC 5829 that you mention looks nice and succinct, and appears to provide exactly what you ask for. Unless either there is another approach that is more common, or this approach would somehow create conflicts with potential other usages of its relation types, I would consider going with this!
Memento is especially suitable for versioning another party’s resources using timestamped snapshots rather than e.g. sequential version numbers; I now see its spec actually suggests to use RFC 5829 for linking to next/previous snapshots:

“In addition, existing Relation Types may be used, for example, to support navigating among Mementos. Examples are "first", "last", "prev", "next", "predecessor-version", and "successor-version" as detailed in [RFC5988] and [RFC5829].”

Extra reason to go with 5829!

mk-pmb commented 3 months ago

A little update: Our current draft implementation is:

iana:version-history points to an AnnotationCollection that lists all versions, for each giving at least fields id and created. We order them chronologically but that is not an expectation.
dc:isVersionOf is a URL meant to address the annotation without any explicit version preference. In our implementation, that coincides with the URL that is meant as "always latest", which in our implementation always redirects to the version-specific URL of the latest version of the annotation.
iana:latest-version varies by use case and either points to "always latest" (thus coincidingly repeating dc:isVersionOf) or points to the version-specific URL of the latest version of the annotation (saving the client from having to follow a redirect, if the server can determine that without additional effort).
dc:replaces points to the version-specific URL of the exact previous version.
- In case of depublication, the resource at that URL is 410 Gone, but served with link relation headers at least rel=latest-version and rel=version-history.
All these fields may be given as absolute or relative URLs, relative to their sibling id field inside the same JSON object.
- Implementation detail unrelated to versioning: We also allow the id field to be relative:
- on annotations presented inside a collection, to their collection's id.
- otherwise (single anno or relative id of a collection) to the URL that was used to request the collection or single anno.

w3c / web-annotation