Update JSON-LD text, context doc and prefix registry?

[jonblower]

It is probably worth reviewing the text around the use of JSON-LD (see spec daily build), and consider whether we need to move the context doc and prefix registry to new homes in the OGC space?

Note that this relates to the issue about extracting building blocks from the CoverageJSON spec (see #139), as it would greatly help to have stable URIs.

What do you think, @letmaik?

[chris-little]

@jonblower @letmaik The OGC Schema Repository is not a GitHub repo, but just a hierarchical file system. Could we put everything into a single folder, called for example: CovJSON?

[letmaik]

I would roughly follow https://schemas.opengis.net/cis/, so there would be at minimum:

https://schemas.opengis.net/covjson/ https://schemas.opengis.net/covjson/ReadMe.txt https://schemas.opengis.net/covjson/1.0/ https://schemas.opengis.net/covjson/1.0/coveragejson.json (JSON Schema)

I'm not sure about the JSON-LD context doc and the prefix registry. They are a mix of schema and vocabulary. Maybe new vocabulary would go in https://defs.opengis.net/vocprez/vocab/ but then the JSON-LD context doc still has to live somewhere. Maybe it's ok for 1.0 to keep them at covjson.org and only host the JSON Schema on opengis.net.

[chris-little]

@ghobona @ogcscotts I think the structure of the CoverageJSON schema files from @letmaik is good. The question is where should the JSON-LD context files and prefix registry go? Am I correct in thinking that the vocprez branch is probably outdated legacy?

[chris-little]

Agreed on 25 Jan 2023 to put all the files (schemas, context files, prefixes) on the OGC Schema file repository under the URL http://schemas.opengis.net/covjson/ When @jonblower and @letmaik have copied the appropriate files to a folder on this repo, @ghobona will copy into the controlled OGC Schema repository.

[chris-little]

When schemas etc copied into OGC schema repo, and the Community Standard is published, the community needs to agree on a closing date for the community site. It could be a few years away.

[ghobona]

@chris-little Some additional considerations that we did not discuss on Wednesday.

Location of the Context document

Clause 3.1 of JSON-LD 1.1 implies that the context document should be accessible from the URL that is specified in documents that use the context document. Note that the section is non-normative.

Although some specifications (e.g. schema.org) do not appear to follow this principle, perhaps we should for CoverageJSON.

Clause 9.8 of CoverageJSON suggests that the context document will be accessible from https://covjson.org/context.jsonld

Example CoverageJSON documents encoded in JSON-LD should state the actual location of where the context document is going to be. Based on the discussion on Wednesday, if the context documents are to be placed on schemas.opengis.net, then the example documents should use the schemas.opengis.net URL that resolves to the actual document. For example, this could be http://schemas.opengis.net/covjson/1.0/context.jsonld

The same goes for if the context documents are to be placed at https://covjson.org/context.jsonld

Versioning

Another key consideration is versioning.

All of the schemas at schemas.opengis.net are versioned. Usually this is done by placing the schema files in a folder path that contains a segment that identifies the version number. For example, http://schemas.opengis.net/covjson/1.0/context.jsonld

So v1.1 of CoverageJSON would be placed at http://schemas.opengis.net/covjson/1.1/context.jsonld and so on.

Please factor this into your consideration of whether to place the context documents on schemas.opengis.net or covjson.org

Perhaps we should discuss these further during the next CoverageJSON team call?

[chris-little]

@ghobona I envisaged we would make an editorial change to Clause 9.8, and the examples, etc., to point to the OGC repository. I am happy with the OGC policy for schema versioning and paths, but perhaps @jonblower and @letmaik could express their views please? Perhaps schema in OGC repo and contexts and prefixes in community CovJSON repo, with perhaps defaults in the OGC repo?

[ghobona]

@chris-little and @ghobona discussed the topic during the 2023-02-08 CoverageJSON telecon and agreed that the context document should be placed at https://covjson.org/context.jsonld

There was also agreement to leave the prefix page at https://covjson.org/prefixes/

@jonblower @letmaik Do you have any objection to this resolution?

[jonblower]

Decision from telecon on 29th March 2023, with @jonblower, @chris-little, @ghobona and @letmaik:

• Put schemas under http://schemas.opengis.net, using versioned URLs, e.g. https://schemas.opengis.net/covjson/1.0/coveragejson.json. Use the tagged version of the existing repo
• Keep context document under https://covjson.org/context.jsonld (and the prefix document that it references)
• Changes to the JSON-LD context should be additive only (no vocabulary terms should ever be redefined), so versioning of this documents is not necessary
• Minor editorial edit to the spec to cover the above, and change URLs to the new locations (e.g. in Conformance section) - see #164
• Note: version numbers in URLs should be major.minor (i.e. two levels, not including a "patch" version)