INSPIRE-MIF/gp-ogc-api-features

Singular vs plural collection ids

Closed this issue · 1 comments

heidivanparys commented

Introduction

Requirement /req/pre-defined/collection-naming says:

For each collection that provides data that is harmonised according to the IRs for ISDSS, the id of the collection SHALL be the lowercase version of the language-neutral name of the feature type as specified in the IRs for ISDSS.

The "language-neutral name of the feature type as specified in the IRs for ISDSS" refers to from https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:02010R1089-20141231&from=EN#tocId7

Article 5

Types

  1. For all types defined in this Regulation, a language-neutral name for computers is given between parentheses in the title of the section specifying the requirements for that type. This language-neutral name shall be used for referring to the corresponding type in the definition of an attribute or association role.

Examples of language-neutral names: Address, ProtectedSite.

That requirement is a consequence of https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:02009R0976-20141231&from=EN#tocId251 , which specifies the "Spatial Object Type parameter" of the "Describe Spatial Object Type" request:

8.1.2. Spatial Object Type parameter

The Spatial Object Type parameter shall contain the language-neutral name of the Spatial Object Type as specified in Regulation (EU) No 1089/2010. Where the parameter is not provided, it shall be assumed that all types of Spatial Objects have been selected.

So a link could look as follows: https://developer.my-org.eu/apis/addresses/collections/address, where https://developer.my-org.eu/apis/addresses is what is referred to as the root in the OGC API - Features specification, and address is the collectionId described at http://docs.opengeospatial.org/DRAFTS/17-069r4.html#_collection_.

Issue

I noticed the following recommendations (highlighting is mine):

2.2.1 What are resources?

A fundamental concept in every RESTful API is the resource. A resource is an object with a type, attributes, relation with other resources and a number of operations to modify them. Resources are referred to using nouns (not verbs) that are relevant from the perspective of the user of the API. Operations are actions applied to these resources. Operations are referred to using verbs that are relevant from the perspectie of the user of the API.

One can translate internal data models as-is to resources, but not by definition. The point is to not hide all relevant implementation details. Some example resources are: aanvragen (applications), activiteiten (activities), panden (buildings), rijksmonumenten (national monuments), and vergunningen (permits).

[...]

2.2.3 Interface nomenclature: singular or plural?

Here, the Keep It Simple Stupid (KISS) rule is applicable. Although grammatically, it may feel wrong to request a single resource using the plural of the resource, it is a pragmatic choice to refer to endpoints consistently using plural. For the user it is much easier to not have to keep in mind singular and plural (aanvraag/aanvragen, regel/regels). Furthermore, this implementation is much more straightforward as most development frameworks are able to resolve both a single resource (/aanvragen/12) and multiple resources (/aanvragen) using one controller.

[...]

API-05: Use plural nouns to indicate resources

Names of resources are nouns and always in the plural form, e.g. aanvragen , activiteiten, vergunningen, even when it applies to single resources.

[Geon20]

4.4. Collection

A collection resource is a server-managed list of document resources.
Rule 11: Collection name

A plural noun SHOULD be used for collection names, for example 'employers' or 'people'.
Example 13. Collection of employers

http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/employers

[Rest20]

Questions:

  1. Will some implementers run into problems with the INSPIRE requirements, when e.g. the national guidelines prescribe the use of plural nouns? More guidelines than the ones referred to here exist with similar requirements/recommendations.
  2. Should this be documented as an example of the fact that the implementing rules are too technology-specific on some points?
  3. Or perhaps the requirement is a too strict interpretation of the regulation??
    a. It actually reads "shall contain the language-neutral name" (hightlighting is mine).
    b. And not "shall equal the language-neutral name"...
    c. So perhaps "contain" could have the meaning of "have within" in the regulation? "addresses" has "address" within it...

[Geon20] Geonovum: API Designrules (Nederlandse API Strategie IIa). Geonovum Standard (2020), https://docs.geostandaarden.nl/api/API-Designrules/
[Rest20] REST design working group: REST Guidelines (2020), https://www.gcloud.belgium.be/rest/