Change include/exclude recommendations

[gadomski]

Related Issue(s):

• Closes Bump uvicorn from 0.11.5 to 0.11.7 stac-utils/stac-fastapi#4 (this PR supersedes)
• Discussions and related PRs:
  • PgSTAC: Fields extension includes links even if not listed in includes stac-utils/stac-fastapi-pgstac#27
  • Align fields extension behavior with extension suggestions stac-utils/stac-fastapi#527 (comment)
  • Remove links from default include list stac-utils/stac-fastapi#524

Proposed Changes:

1. Change the recommended include semantics to only return what's asked for. Previously, the recommendation was to return what was asked for AND the default fields.
2. Include stac_version in the default fields.
3. Clarify the wording around sub-keys.
4. Define behavior when a field is both included and excluded.
5. Update examples
6. Fix some formatting in the examples

PR Checklist:

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

[gadomski]

@philvarner re-requesting review, I've updated all the language to use "should", and to avoid "add" and "subtract" in favor of "included" and "exclude".

[philvarner]

apparently I didn't submit these comments? I guess I accidentally started a review and they were all added to that. I'll delete the ones that aren't relevant.

[philvarner]

At the risk of getting overly conceptual here, it might be useful to state that there are multiple levels of "modeling" of data in this. The image data is a model of the real world, and likewise the STAC Item is a model of the image data. Fields is sometimes causing the STAC Item metadata to be manipulated in a way that means it's not a exact copy of what's stored in the database, but a model of that. So, for example, if we choose to return a geometry=null and bbox value to return a valid STAC Item when geometry is excluded, we're modeling the metadata to conform to the fields restrictions.

[gadomski]

if we choose to return a geometry=null and bbox value to return a valid STAC Item when geometry is excluded, we're modeling the metadata to conform to the fields restrictions.

I guess? To me, it's simpler than that -- if someone says they don't want it, don't give it to them. IMO we can trust the client to know what it wants (i.e. a invalid STAC item).

[philvarner]

Yeah, that's probably not something the server should try to do, since the validity guardrails are off when you start using fields.

[philvarner]

comments inline. I think we're close to having this done.

[gadomski]

@philvarner sorry I squashed and force pushed and the repo requires a re-review, didn't realize that.