wip: filter documentation

[toumorokoshi]

🍱 Types of changes

What types of changes does your code introduce to AEP? Put an x in the boxes that apply

• [ ] Enhancement
• [ ] New proposal
• [ ] Migrated from google.aip.dev
• [ ] Chore / Quick Fix

📋 Your checklist for this pull request

Please review the AEP Style and Guidance for contributing to this repository.

General

• [ ] Basic Guidance is met.
• [ ] Ensure that your PR references AEPs correctly.
• [ ] My code has been formatted (usually prettier -w .)

💝 Thank you!

[thegagne]

Do we need the operations to be per field?

For example, you might want RelOp for create_time but not for description.

[toumorokoshi]

Do we need the operations to be per field?

For example, you might want RelOp for create_time but not for description.

we might want it - I was trying to simplify somewhat, but I suppose we should allow for full flexibility.

How about accepting both global and per-field ops?

x-aep-filter:
  fields: # this field describes the fields that can be operated upon
    path: {}
    description: {}
    create_time:
      ops: 
        RelOp: {} # rel ops are supported just for create_time.
  # these are operations that are supported by the API. They match the
  # name of the elements in the grammar.
  # https://github.com/google/cel-spec/blob/master/doc/langdef.md#name-resolution
  operations: # globally supported ops
  - 'ConditionalOr'
  - 'ConditionalANd'

Although that might end up being a bit cumbersome, because it's probably more common for the opposite case: ops support N fields, not a single field support N ops.

So perhaps something like:

x-aep-filter:
  fields: # this field describes the fields that can be operated upon. use a map to attach metadata as needed.
    path: {}
    description: {}
    create_time: {}
  # these are operations that are supported by the API. They match the
  # name of the elements in the grammar.
  # https://github.com/google/cel-spec/blob/master/doc/langdef.md#name-resolution
operations: # globally supported ops
  ConditionalOr: {}
  ConditionalANd: {}
  RelOp:
    fields: ["create_time"] # the existence of `fields` implies that not all fields are supported and the op is scoped.

The latter seems fairly flexibile?

[toumorokoshi]

some thoughts from live discussion:

• with odata, this was supported via documentation on a separate page.
• LLMs would find this documentation helpful.
• if we don't have a standard way to document it, then the ecosystem will bifurcate.
• documentation generation won't be able to generate high-quality docs with only textual descriptions.
• is a simple list going to be sufficient? e.g. for parentheses.

[toumorokoshi]

After discussion in the weekly, we've agreed that we should try to tackle this further in the 2027 edition of AEPs, rather than rush an untested solution.