Sort Extension: simple format for GET

[philvarner]

1. added a slightly different, non-JSON format for the GET parameter case. @joshfix
2. changed the description so that field from the root of Item rather than properties. This is so that a user can provide a stable sort over properties.created ascending, id (ascending or descending). Without the id as the secondary sort, items with the same created timestamp would result in a non-stable sort, which may give users incorrect results with trying to page through an entire result set.

PR Checklist:

• This PR has no breaking changes.
• I have added my changes to the CHANGELOG or a CHANGELOG entry is not required.
• API only: I have run npm run generate-all. to update the generated OpenAPI files.

[joshfix]

I like the GET support! :)

I have no idea if this is a good idea or bad idea, but what about making the GET values use a similar syntax as the proposed fields values, where a + denotes ascending and a - denotes descending:

GET /stac/search?sort=+properties.created,-id&fields=+properties.created,+xxx

[philvarner]

As I wrote up Fields, it's only nothing or -, which I think is fine for sort also ==> ascending is the default, with - prefix meaning descending.

[cholmes]

Moving to 0.9.0 - as there's more thinking to do on this. Sean will sound in with some more thoughts on doing things in headers, and we want to try to align with WFS.

[tomkralidis]

What about replacing | with ; ? Like GET /stac/search?sort=eo:cloud_cover;desc. | may be ambiguous (expressing this or that property, say)

[tomkralidis]

Borrowing from OGC approaches, what about:

    "sort": [
        {
            "property": "created",
            "order": "asc"
        }

[philvarner]

@tomkralidis can you point me to the documentation for those OGC approaches?

[tomkralidis]

@philvarner

• from CSW 2.0.2: http://portal.opengeospatial.org/files/?artifact_id=20555 (Table 65)
• from CSW 3.0: http://docs.opengeospatial.org/is/12-176r7/12-176r7.html (Table 22)

[tomkralidis]

Note relevant conversation in opengeospatial/ogcapi-features#157

[matthewhanson]

@philvarner Looks like this might need some updates, thought colon was going to be avoided in favor of semi-colon?

[philvarner]

I think I have all the necessary changes in now @joshfix @tomkralidis @matthewhanson

[m-mohr]

Seems to be what we have discussed. 👍 Only thing to change is the endpoint path (see comment).

[m-mohr]

I'm just wondering whether we should use an approach that can be modeled in OpenAPI. We can't properly describe the current behavior except for textual descriptions. I went through the OpenAPI specification and found we could model it properly this way:

{
  "name": "sortby",
  "in": "query",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "style": "deepObject"
}

This would translate to the following GET query parameters:
sortby[properties.datetime]=desc&sortby[id]=asc

This translates to the following object, which could also be used in POST:

{
  "properties.datetime": "desc",
  "id": "asc"
}

I'm aware that this is maybe not as short as the other approach, but follows a well-defined behavior.