Substitute version/branch names in schema

[duncandewhurst]

Currently, links in the schema are hardcoded to the latest branch. OCDS has an approach to substituting version/branch names.

[odscjames]

156 is related.

I haven't looked at OCDS approach.

In BODS we took an approach of trying to move any such links out of description fields. Other tools may use the JSON Schema, and we can't be clear how that will work and whether it will break things there. (In particular, in BODS we previously had relative links but there were 2 places they became visibile in the standard and one worked and one didn't.)

Instead we tell the widgets drawing the docs to add links themselves eg see https://github.com/openownership/data-standard/blob/0.2.0/docs/schema/reference.rst#address and the :externallinks: key

In the docs this appears as a seperate link eg https://standard.openownership.org/en/0.2.0/schema/reference.html#address

[duncandewhurst]

OCDS's approach is to replace the language and version placeholders in the schema files in the GitHub repository as part of the build/deploy process (docs) and to push the canonical processed version to a folders on OCP's server, e.g. https://standard.open-contracting.org/schema/1__1__5/. Those are the schema files that should be used by other tools as described on https://standard.open-contracting.org/latest/en/schema/release/#release-schema. I think that is preferable because users get a direct link to the referenced codelist, for example, rather than needing to browse/search the codelist reference, and because those links are available to other tools/users.

For OFDS, we don't have a separate server, but maybe we can still do something as part of the docs build process on readthedocs, i.e. making substitutions and pushing the canonical versions to a sub-directory of the built docs folder.

[odscjames]

For OFDS, we don't have a separate server, but maybe we can still do something as part of the docs build process on readthedocs

Yes, we could. This is getting into a wider conversation of how we build standards, and I'm not definitely saying we should do it the BODS way, just thought it would be interesting to consider all the options we have.

[duncandewhurst]

Noting that I've got this working on Read the Docs in https://github.com/GFDRR/rdl-standard/pull/100