casing rules for properties defined in schemas

[tomkralidis]

Across the OGC API specifications we have various casing patterns for schemas (as opposed to API endpoint names/query parameters). For example, should we call a property externalId, external-id, external_id?

Examples:

• lowerCamelCase
• kebab-case
• snake_case

In EDR API, as found in https://github.com/opengeospatial/ogcapi-environmental-data-retrieval/pull/261#issuecomment-808321663, we found that things like AWS gateway do not take too well to kebab-case in (JSON) schemas. We then asked the STAC group who provided valuable feedback.

Is there a guideline (or should there be) on schema property names (STAC is recommending snake_case, which works great for me)?

cc @pvretano @jerstlouis @cportele @chris-little @schpidi @cholmes

[jerstlouis]

@tomkralidis My own selfish preference, based on our development toolchain (and associated style conventions), is lowelCamelCase and avoiding identifiers which would not be valid identifiers in C or derived programming languages (as we typically directly parse JSON to native class instances). i.e. avoiding starting with a number, using non-alphanumeric+underscore characters, and these reserved keywords.

[cportele]

Features uses lowerCamelCase for property names in schemas, mainly because this is the convention that is mostly used in OGC and ISO/TC 211 (and also in many other environments).

For query parameters and path elements Features has been using all lower case just to avoid potential issues: while the path and query parameters of a URI are case sensitive, some software processes URIs case insensitive. So we either have just combined the words where the result is understood (e.g., datetime; I think this will typically work, if the words are separated by a hyphen) or use kebab case (e.g., bbox-crs for the CRS of the bounding box coordinates or filter-lang for the language used in the filter expression).

In cases like the external identifier example this gets a bit tricky, because it is used in Records both as a query parameter and as a JSON member key. I do not think it is intuitive to use external-id as the query parameter and externalId in the JSON encoding. I think we should either continue to use externalid (flat case) or also use externalId for the query parameter.

[tomkralidis]

Thanks for the feedback @jerstlouis @cportele. snake_case is my own selfish preference, and used by the STAC community. It looks like lowerCamelCase is preferred by OGC and already used in OAFeat.

How about the following as a recommendation:

• query parameters should be kebab-case
• schema property definitions should be lowerCamelCase
• when a query parameter is also a schema property, then the schema property definition takes precedence

[tomkralidis]

Other options:

• query parameters should be kebab-case
• schema property definitions should be lowerCamelCase OR snake_case
• when a query parameter is also a schema property, then the schema property definition takes precedence

OR

• query parameters should be kebab-case
• schema property definitions MUST NOT be kebab-case
• when a query parameter is also a schema property, then the schema property definition takes precedence

[cmheazel]

Related to #223

[cmheazel]

4/26/21 SWG resolution: This issue impacts all OGC JSON Schemas. Delegate this issue to the OAB to resolve.

[chris-little]

@cmheazel So, courtesy of @tomkralidis, the options are currently: Part A Option 1, most restrictive: query parameters should be kebab-case schema property definitions should be lowerCamelCase when a query parameter is also a schema property, then the schema property definition takes precedence

Option 2: query parameters should be kebab-case schema property definitions should be lowerCamelCase OR snake_case when a query parameter is also a schema property, then the schema property definition takes precedence

Option 3 least restrictive: query parameters should be kebab-case schema property definitions MUST NOT be kebab-case when a query parameter is also a schema property, then the schema property definition takes precedence

Part B datetime should be called: Option 1: datetime

Option 2: date-time

Other Options: ??

[ghobona]

Thanks @cmheazel for the heads up regarding this topic.

I propose we discuss the topic at an Architecture DWG Cross SWG telecon, before the next OGC Members Meeting.

Before the telecon however, we need to understand the impact of the different options on Code Generators. Remember that a key principle is to make OGC APIs as implementor-friendly as possible. So does anyone have insight into how the different options might affect popular Code Generators?

[jerstlouis]

We should clarify / resolve this issue.

In my view, query parameters and JSON schema properties are two completely different things, even if sometimes both type of building blocks occur for similar names and concepts.

So if that same name or concept occurs as both query parameter and schema property, each should follow the casing rule where it is used.

Suggesting that the guidance should be clarified to be:

• The casing rule for JSON schema properties is camelCase (or snake_case as an acceptable alternative), avoiding starting with a digit or other invalid identifiers in C-based languages.
• The casing rule for OGC API query parameters is all lower case kebab-case

This is particularly important for things intended to be common building blocks across multiple OGC API SWGs.

Using dashes inside JSON property schemas makes it more difficult to match them to data type members in several programming languages (including those all derived from C).

[jerstlouis]

Common-SWG 2024-03-21: There is a general agreement that this is the guideline approach.

There is mention of kebab case in Part 1 for query parameters, but nothing about camelCase for the schemas of JSON responses. Perhaps that should be clarified. We should also verify whether this guidance is written anywhere else.

Perhaps this could be added next to Recommendation 12 in Part 1.

/rec/core/json

[vincentsarago]

👋 sorry for spamming a slightly related topic of mine, but I'm looking for answer about the Query Parameter format.

In the specs it seems that query parameter like bbox-crs or filter-crs are using - hyphen but it's unclear to me if this is strictly required by the specification or if implementers could use _ underscore instead (e.g filter_crs, bbox_crs).

FYI in stac-fastapi we are hitting a problem where for some reason we cannot hyphen in our query parameter names for GET requests.

[jerstlouis]

@vincentsarago While the naming convention of parameters, in OGC API - Common are guidance, implementations of a particular OGC API Standard needs to conform to the requirements there.

For the sake of consistency, hopefully those different standard doing a very similar thing would use the exact same parameter following the same convention.

we are hitting a problem where for some reason we cannot hyphen in our query parameter

How much of a hard problem is that? That seems like a problem with the software stack at a particular level that could be addressed?

Which OGC standard(s) specifically are you implementing there? If the parameter is defined as bbox-crs, supporting bbox_crs instead will not work with clients passing bbox-crs. (It does not matter what the server API definition says -- the parameters name are actually fixed in the standard. Our OGC API client for example does not care at all about the API definition and will not even retrieve it. The API definition is not required to be in a particular API definition language either.)

[vincentsarago]

👍

How much of a hard problem is that? That seems like a problem with the software stack at a particular level that could be addressed?

pretty hard because we can't use hyphen in python variable names 😅, but this is specific to stac-fastapi (OGC Features API). I'm working on fixing this but before introducing an over complex solution I wanted to double check with the specification 😄

Our OGC API client for example does not care at all about the API definition and will not even retrieve it

makes sense!

[jerstlouis]

@vincentsarago

https://docs.ogc.org/is/18-058/18-058.html#_parameter_bbox_crs

Requirement 6 /req/crs/fc-bbox-crs-definition Each GET request on a 'features' resource SHALL support a query parameter bbox-crs with the following characteristics: name: bbox-crs in: query

[chris-little]

@vincentsarago When the recommended cases (kebab-case, UpperCamel, snake_case, etc) were adopted by the OGC APIs to clarify what functioned as what and to be consistent, there were constraints from various software stacks including passing data and URIs through to various cloud offerings. See https://github.com/opengeospatial/ogcapi-environmental-data-retrieval/issues/170 if you want to inspect how the sausages were made.