Remove recommendation to use fully-qualified property names as queryables

[philvarner]

Related Issue(s):

• Unclear on conventions/best practices for property names #29

Proposed Changes:

1. Remove recommendation to use fully-qualified property names as queryables. I'm not sure why the spec ever said that, because in practice just the field names used in the properties are set as the queryables terms.

PR Checklist:

• This PR has no breaking changes.
• I have added my changes to the CHANGELOG or a CHANGELOG entry is not required.

[gadomski]

Big 👍🏼 on this, I've bumped in to inconsistencies in implementations w.r.t. properties..

[m-mohr]

Yeah, it should be custom queryables always, no properties.
This probably caried over from the other specs, e.g. fields, sort or query. (We should also add sortables to the sort extension).

[fmigneault]

Good thing for the removal of contradictory text. At least it is clear about the expectation.

However, I'm concerned about usability from a user's perspective. I believe the properties. prefix comes from other places that need it, such as shown in https://github.com/stac-api-extensions/fields?tab=readme-ov-file#explicitly-get-a-valid-stac-item and https://github.com/stac-api-extensions/sort?tab=readme-ov-file#http-get

It is very confusing to have a mixture of query parameters that do not operate "at the same root level" of the JSON document within the same request, although referring to the same properties position within the document. For example, filtering by eo:cloud_cover, sorting them, and removing raster:bands to reduce the content of the response is done with ?filter=eo:cloud_cover<=0.5&&sortby=+properties.eo:cloud_cover&fields=-properties.raster:bands.

Another point that is also problematic is regarding the use of filter by STAC vs OGC API - Features. In OAF, it is obvious that properties. is redundant, since all the queryable content is expected within properties, and therefore the prefix can be dropped. However, STAC's representation is somewhat different. There are assets, bands, and other "metadata containers" that could be relevant or of interest for filtering (although not currently supported by the extension). Are there plans to support such capabilities? It seems to me that using a properties. prefix would facilitate their combination in a single CQL2 filter if the capabilities were extended at a later time, rather than introducing more query parameters.

[m-mohr]

filter only works on queryables. Those queryable names can be chosen to be aligned with the other extensions or not, but it's up to the implementor to decide that. Sort get's something similar, sortables.

Fields is a bit different in that you need to directly tell the location of the propertes, so it's expected to be slightly different. I don't see much of an issue here, I think.

[fmigneault]

Those queryable names can be chosen to be aligned with the other extensions or not, but it's up to the implementor to decide that.

Wouldn't that make the removed recommendation "It is recommended to use fully-qualified property names (e.g., properties.eo:cloud_cover)." actually valid, provided that it is amended with an extra explanation that they should be defined as such in queryables as well?

As it stands, even unqualified properties would be invalid if they are not in queryables.

Regardless of what the recommendation says, the choice remains in the hands of the implementer, but it seems a pretty convenient approach to facilitate usage across extensions if they are fully-qualified. I don't think most users would be aware of the subtlety of fields by location vs sortby/filter by sortable/queryables when seeing similar property names within the request.