Use versioning and tag versions within repository

[ryanchristo]

Summary

It would be nice if each schema had a regen registry standard version specified within the schema and versions were tagged within the repository so that specific version could be referenced.

This may require retroactively tagging a version initially used for classes and batches (a version that does not include the regen registry standard version within the schemas and which was previously used for metadata on Regen Ledger).

This would also require finalizing the class, project, and batch schemas that will be used with any new classes, projects, and batches (including adding a regen registry standard version), and then tagging a new version.

Using versions will allow projects to choose a specific version and migrate to a new version when a new version is finalized. Currently we are using the latest changes and would like to commit to using an explicit version knowing we may need to update to a new version in the future and that we would make changes when a new version has been finalized.

[ryanchristo]

cc @clevinson @S4mmyb

[wgwz]

@ryanchristo i think this makes sense, because then we would know which schema we expect to validate successfully against a given piece of metadata. given a piece of remote metadata you know which schema must be applied to it by this version number. and you have the ability to find the schema corresponding to this version number.

so we would add a field named something like regen:standardsVersion to the batch, class and project schema. i guess we would just have to figure out precisely what type of versioning scheme to use, and figure out how we want to track it. i.e. would the regen:standardsVersion be something that we can increment independently for credit, batch and project? (i think the answer is probably no but it's a detail to sort through). and would we use a git tag or just add versions to filenames?

i.e. using regen:standardsVersion field and adding versions to filenames with the assumption that regen:standardsVersion must be incremented uniformly:

{
  "@context": {
    "schema": "http://schema.org/",
    "regen": "http://regen.network/",
    "regen:additionalCertifications": { "@container": "@list" }
  },
  "@type": "regen:C01-CreditBatch",
  "regen:standardsVersion": "v0.0.1",
  "regen:vcsRetirementSerialNumber": "",
  "regen:vcsProjectId": "",
  "regen:additionalCertifications": [
    {
      "schema:name": "",
      "schema:url": {
        "@type": "schema:URL",
        "@value": ""
      }
    },
    {
      "schema:name": "",
      "schema:url": {
        "@type": "schema:URL",
        "@value": ""
      }
    }
  ]
}

❯ ls -l shacl/credit-batches 
total 16
C01-verified-carbon-standard-batch.v0.0.1.ttl
C01-verified-carbon-standard-batch.v0.0.2.ttl
C01-verified-carbon-standard-batch.v0.1.0.ttl

❯ ls -l shacl/credit-classes
total 16
C01-verified-carbon-standard-class.v0.0.1.ttl
C01-verified-carbon-standard-class.v0.0.2.ttl
C01-verified-carbon-standard-class.v0.1.0.ttl

❯ ls -l shacl/projects
total 16
C01-verified-carbon-standard-project.v0.0.1.ttl
C01-verified-carbon-standard-project.v0.0.2.ttl
C01-verified-carbon-standard-project.v0.1.0.ttl

[ryanchristo]

would the regen:standardsVersion be something that we can increment independently for credit, batch and project? (i think the answer is probably no but it's a detail to sort through).

Yea, independent tags for each might be a bit much to manage although I could see a case where a field is changed the project schema and then the version would need to be bumped for the class and batch as well. Maybe best to start simple though.

and would we use a git tag or just add versions to filenames?

I was thinking git tags when I wrote this, which would allow for linking to a specific version and then the main branch would always be the latest (i.e. the development branch). This would ensure a schema is not changed after the fact and reduce clutter but if you think we should version each directory, that works too.