Add a requirement about query parameters consisting of lists

[ghobona]

This should be derived from Section 11.5.3 of the OWS Common 2.0 standard (OGC 06-121r9).

This came up during the OGC API - Maps Sprint in July 2020.

[cmheazel]

11.5.3 Parameter value lists
Parameters values containing lists (for example, AcceptVersions and AcceptFormats in the GetCapabilities operation request) shall use the comma (",") as the separator between items in the list. Additional white space shall not be used to delimit list items. If a list item value includes a space or comma, it shall be escaped using the URL encoding rules [IETF RFC 2396].In some lists, individual entries may be empty, and shall be represented by the empty string (""). Thus, two successive commas indicates an empty item, as does a leading comma or a trailing comma. An empty list ("") can either be interpreted as a list containing no items or as a list containing a single empty item, depending on the context.

[cmheazel]

@ghobona How would this impact using WKT in a parameter? For example:
‘LINESTRING ( 10 10, 20 20, 30 40)’
(from 99-049 - Simple Features for SQL)?

[cportele]

The main driver should be that parameters that have arrays or objects as values are represented consistent with OpenAPI. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#style-examples.

Regarding WKT, the line string parameter value would be LINESTRING(10%2010%2C%2020%2020%2C%2030%2040).

[cmheazel]

Added a section to the General Requirements covering parameter encoding. It addresses:

• Capitalization
• Value Lists
• Numeric and Boolean values

[cportele]

@cmheazel - I had a quick look at the changes and have some comments (in general, it would be better, if changes would be pull requests that remain in review for a while, that would make it easier to comment and discuss comments in the context of the proposed change):

• "Parameter names SHOULD be in Upper Camel Case"
  • I assume this should be "Parameter names SHOULD be in Lower Camel Case"?
  • Using a dash to separate words should be included in the recommendation as another option, too.
• "In order to maintain commonality between OGC Web Services and OGC Web APIs, an OGC Web API should expose the Service Metadata defined in OWS-Common"
  • I understand that we want to link to service metadata in a consistent way, but to recommend that the service metadata should be the old OWS Common service metadata aka capabilities? I don't think core should recommend any particular service metadata standard. That should be left to separate requirements classes and it would probably be best to specify this outside of part 1.
• Some of the requirements seem redundant and could be dropped. For example, /req/core/query-param-capitalization or /req/core/query-param-list-escape seem to be about a subset of the rules that apply to HTTP URIs. This is misleading as it could be understood that the other rules of that RFC do not apply.
• /req/core/query-param-list-delimiter implies that one cannot use explode=true or objects as parameter values. Is there a reason for that restriction, which seems limiting and unnecessary?
• Consistent with the general preference for using lowercase, I would greatly prefer true and false over TRUE and FALSE as in the current draft.

[cportele]

Since it was decided to close this issue, if no additional comment is added until the next SWG meeting, I would just like to point out that the points in my previous comment have not yet been discussed/resolved.

[jerstlouis]

@cmheazel
I believe @cportele 's first point has been resolved in #42 to recommend kebab-case, is there a discrepency elsewhere recommending camel case?

The second point about service metadata has proposed solution in #38 but is not yet implemented.

+1 for discussing/addressing the other points as well.

[cportele]

@jerstlouis - Yes, the first point is covered by the kebab-case commendation and should no longer be in the current draft. But I still find surprising text in the current draft that I do not understand, e.g.:

All parameter value strings should have the first word and any subsequent words in the name capitalized. All other letters should be lower case.

[cmheazel]

January 25 SWG - make sure all query values are not restrict by case (requirement 8).
Query parameter names are kebob case. Verify that this is implemented consistently across the standard.
Section 8.1.7 - only allow a negative sign. Since a plus is implied, there is no need to include it.
Section 8.1.7 - add more text to make it clear that we are talking about the consistent encoding of computer science numeric values in the URI string.
Provide more info on when each numeric data type should be used.
See if we can reference the applicable IEEE standards for numerics rather than XML schema.
Consider allowing the API definition to override the list delimiter. - make a recommendation not a requirement.
Also add a discussion of exploded (repeating the parameter name) vs delimited list approaches to parameter values which are a list.
Implement as a separate pull request, but not merged.

[cmheazel]

January 22 pull request:
All parameter names are kebob case unless their case is defined by the target resource.
Parameter values are recommended to be kebob case unless their case is defined by the target resource.
Positive signs are no longer allowed
List value delimiter shall be defined in the API definition. "," is the default.
Added a short description of exploded (repeated) vs delimited list parameters
Added a short explanation as to why encoding rules for numerics are required and cited K&R as the source.

[cmheazel]

February 1 - close NOTUC