search

opengeospatial / ogcapi-records

An open standard for the discovery of geospatial resources on the Web.
https://ogcapi.ogc.org/records
Other
58 stars 27 forks source link

Editorial issues #270

Closed m-mohr closed 1 year ago

m-mohr commented 1 year ago

When reading through the docs for a STAC comparison, I found some editorial issues.

  1. 7.2.7. has the chapter title: "Type and Licenses", but it just describes types and licenses is actually a separate chapter following afterwards (7.2.8)
  2. Do I read the license field description correctly as such: It is either a SPDX identifier, a SPDX expression, other or basically anything (e.g. free-text or a URL)? I read it as such because SPDX identifier, a SPDX expression and other are all just "should".
  3. The sumamry for the license field in the table is: "A legal document under which the resource is made available." - This sounds like it should be a URL to a document, but that sounds misleading to me (see above). I'd not talk about a "document" here.
  4. From the spec it's not clear whether next and prev links are only allowed in an API context or also in static/crawlable deployments. (I'd hope it's allowed only in an API context.)
pvretano commented 1 year ago
  1. 7.2.7. has the chapter title: "Type and Licenses", but it just describes types and licenses is actually a separate chapter following afterwards (7.2.8)

Yup. Will update the title to be more indicative of the content.

  1. Do I read the license field description correctly as such: It is either a SPDX identifier, a SPDX expression, other or basically anything (e.g. free-text or a URL)? I read it as such because SPDX identifier, a SPDX expression and other are all just "should".

Not correct. SPDX identifier, SPDX expression or other. In the case of other, one or more links (rel="licence") must be included in the links section.

  1. The sumamry for the license field in the table is: "A legal document under which the resource is made available." - This sounds like it should be a URL to a document, but that sounds misleading to me (see above). I'd not talk about a "document" here.

Changed all reference to read "The legal provisions under which ...".

  1. From the spec it's not clear whether next and prev links are only allowed in an API context or also in static/crawlable deployments. (I'd hope it's allowed only in an API context.)

The specification is not that prescriptive about links but just to be clear anywhere I talk about prev and next I prepend the comment with "In the context of an API, blah, blah, blah" since prev and next mostly make sense in relation to an API.

m-mohr commented 1 year ago

Thanks, Peter.

Not correct. SPDX identifier, SPDX expression or other. In the case of other, one or more links (rel="licence") must be included in the links section.

Okay, good that this is the intention. Where does it say this? I think Recommendation 6 C must be changed from "SHOULD" to "SHALL" to ensure this is also reflected in the written language. This should be enough:

If the resource is being made available under one or more licenses that haven’t been assigned an SPDX license identifier then the value of the license member SHALL be the value other and one or more links (relation: license) SHALL be included in the links section of the record pointing to the file(s) that contain the text of the licenses.

pvretano commented 1 year ago

Not correct. SPDX identifier, SPDX expression or other. In the case of other, one or more links (rel="licence") must be included in the links section.

Okay, good that this is the intention. Where does it say this? I think Recommendation 6 C must be changed from "SHOULD" to "SHALL" to ensure this is also reflected in the written language. This should be enough:

Recommendation 6 says what I previous mentioned ... that is that license is either a SPDX identifier, a SPDX expression or other. If it is other then links should exist in the links section pointing to the "other" license text.

If the resource is being made available under one or more licenses that haven’t been assigned an SPDX license identifier then the value of the license member SHALL be the value other and one or more links (relation: license) SHALL be included in the links section of the record pointing to the file(s) that contain the text of the licenses.

Right now how license is populated is a recommendation, hence the use of "SHOULD". If we change that to "SHALL" then it needs to become a requirement which means we also need to write an ATS for it, etc. I am not sure we want to restrict the use of license that strongly ... do we?

m-mohr commented 1 year ago

I think we do. If you operate on recommendations only, you allow e.g. someone embedding the full license text in "license". It can be anything, which conflicts with the pre-defined values to some extent. You said above that it's not intended to allow everything in license, right?

pvretano commented 1 year ago

Hmm ... ok, I'll change it to a requirement then.