Adding Recipe for Versioning

[PonteIneptique]

Fixes #282

I think this addresses how I would do that, and how I talked about it.
One thing I am not sure I like is that if you are linking to version outside of DTS, it becomes unclear. I am wondering if we should allow in 1.0 typed URIs, aka: {'@id': URI, '@type': 'Resource'}, but I would generally think it's a bad idea.

[monotasker]

This looks good to me. I think we should merge this while we decide what to do about the case of external version links.

[monotasker]

On the question of external links, I might suggest that we just allow external URIs in the hasVersion array, in which case those external versions don't have a corresponding member object on the Resource. We reserve member for versions accessible via a dts endpoint, but encourage hasVersion to include any other external versions as well.

[hcayless]

I think I'd do this a little bit differently (maybe slightly simpler?)

• The root Resource represents the current work, with a series of previous versions as members. This is the same as Thibault's proposal except I'm assuming version info in the id URI. Maybe a less opaque version identifier, like "v1" etc. would be better for explanatory purposes.
• The members property is basically a linked list of previous versions of the work, linked via the hasVersion and isVersionOf properties in the Dublin Core metadata. It is also (presumably) in reverse version order, latest to earliest.

{
  "@context": "https://distributed-text-services.github.io/specifications/context/1.0rc1.json",
  "dtsVersion": "1.0rc1",
  "@id": "https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_9a18bc",
  "@type": "Resource",
  "title": "Bucolica",
  "totalParents": 1,
  "totalChildren": 2,
  "collection": "/api/dts/collection/?id=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_9a18bc(&nav}",
  "document": "/api/dts/document?resource=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_9a18bc{&ref,start,end,tree,mediaType}",
  "navigation": "/api/dts/navigation?resource=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_9a18bc{&ref,start,end,tree}",
  "dublinCore": {
    "creator": [
      "Calpurnius Siculus"
    ],
    "isVersionOf": [
      "/api/dts/collection/?id=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_8c36a8"
    ]
  },
  "citationTrees": [
    {
      /* ... */
    }
  ],
  "member": [
    {
      "@id": "https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_8c36a8",
      "@type": "Resource",
      "title": "Bucolica",
      "totalParents": 1,
      "totalChildren": 0,
      "collection": "/api/dts/collection/?id=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_8c36a8(&nav}",
      "document": "/api/dts/document?resource=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_8c36a8{&ref,start,end,tree,mediaType}",
      "navigation": "/api/dts/navigation?resource=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_8c36a8{&ref,start,end,tree}",
      "dublinCore": {
        "isVersionOf": [
          "/api/dts/collection/?id=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_2fe456"
        ],
        "hasVersion": [
          "/api/dts/collection/?id=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_9a18bc"
        ]
      },
      "citationTrees": [
        {
          /* ... */
        }
      ]
    },
    {
      "@id": "https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_2fe456",
      "@type": "Resource",
      "title": "Bucolica",
      "totalParents": 1,
      "totalChildren": 0,
      "collection": "/api/dts/collection/?id=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_2fe456(&nav}",
      "document": "/api/dts/document?resource=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_2fe456{&ref,start,end,tree,mediaType}",
      "navigation": "/api/dts/navigation?resource=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_2fe456{&ref,start,end,tree}",
      "dublinCore": {
        "hasVersion": [
          "/api/dts/collection/?id=https://digitallatin.org/ids/Calpurnius_Siculus-Bucolica_8c36a8"
        ]
      },
      "citationTrees": [
        {
          /* ... */
        }
      ]
    }
  ]
}

[monotasker]

@hcayless, so the isVersionOf and hasVersion function like genetic descent pointers? With the isVersionOf on the top-level Resource pointing back to the prior version? I suppose this would work even if we don't have a neat linear descent chain. If a number of parallel versions are made from one ancestor, it could have multiple hasVersion links? And if a later version consolidated a number of earlier ones together it could have multiple isVersionOf links?

My question then would be how someone would handle looser relationships between "editions" of a work--e.g. different translations or alternate manuscripts--where there isn't simple genetic descent. In this case, would someone create a parent Collection representing the notional work, and then create separate Resources representing the different editions? If that's our model, I think we should be very clear about when versioning is appropriate. And we should include a separate recipe for handling multiple editions.

[hcayless]

I think the answer is that what you describe is outside the scope of "versioning" where the versions are basically releases. We could recommend dc:replaces and dc:isReplacedBy instead of the slightly fuzzier 'version' relationships and I'd be happy with that. If what you've got is a group of interrelated Resources, I think it's fine to group them in a Collection by conceptual work and then use metadata to link them. But I think that's a different beast entirely.

[monotasker]

Agreed. We'll just have to make it clear because people will likely confuse them.