fix(api): API multiple filters

[tothandras]

Summary by CodeRabbit

Release Notes

• New Features

  • Field filtering now supports applying multiple comparison operators simultaneously on the same field (e.g., date fields can accept both lower and upper bounds in a single request).

• Tests

  • Added test coverage for multi-operator filtering scenarios across numeric, datetime, and string field types.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors field filter schemas from a @oneOf pattern with multiple named sub-models into a unified union pattern with a single object containing optional comparison properties. TypeSpec definitions are consolidated, generated API specs and OpenAPI test schemas are updated to use anyOf instead of oneOf, and tests are extended to validate multiple operators on the same field.

Changes

Field Filter Schema Refactoring

Layer / File(s)	Summary
TypeSpec Schema Refactoring api/spec/packages/aip/src/common/parameters.tsp	BooleanFieldFilter, NumericFieldFilter, StringFieldFilter, StringFieldFilterExact, ULIDFieldFilter, and DateTimeFieldFilter are consolidated from @oneOf chains into single union objects with optional comparison properties (eq?, neq?, contains?, lt?, lte?, gt?, gte?, exists?), preserving comma-delimited encoding for multi-value operators.
OpenAPI Test Schema api/v3/test/openapi.test.yaml	Field filter schemas transition from oneOf to anyOf combinators, remove per-variant required constraints, and restructure object variants to rely on optional property presence.
Generated API Specification api/v3/api.gen.go	Embedded Swagger/OpenAPI spec is regenerated from refactored TypeSpec schemas, updating base64-encoded chunks to reflect the new union-object structure and anyOf semantics.
Validator Test Updates api/v3/test/filters_test.go	ULID and DateTime validation tests assert anyOf instead of oneOf in error rule expectations while maintaining the same validation field and reason assertions.
Parser and Multiple-Operator Tests api/v3/test/filters_test.go, api/v3/filters/parse_test.go	Tests are extended to verify that multiple operators on the same field (DateTime gte+lte, Numeric gte+lt, String neq+contains) populate all corresponding fields on the same filter struct with AND semantics.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• openmeterio/openmeter#4170: Touches the same filter schema types and generated parsing behavior.
• openmeterio/openmeter#4223: Also simplifies ULIDFieldFilter to keep only eq/oeq/neq operators.
• openmeterio/openmeter#4301: Directly related but opposing changes to the same AIP field filter models—consolidates vs. expands per-comparison variants.

Suggested labels

release-note/misc

Suggested reviewers

• borosr
• turip

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(api): API multiple filters' directly summarizes the core change—refactoring field filter schemas to support multiple filter operators on the same field, enabling proper handling of combined filters like gte+lte.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/v3-api-filters

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

api/spec/packages/aip/src/common/parameters.tsp (1)

38-39: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Misleading "provide exactly one" doc text — update across all filter types.

The descriptions for NumericFieldFilter, StringFieldFilter, StringFieldFilterExact, ULIDFieldFilter, and DateTimeFieldFilter all say:

"All properties are optional; provide exactly one to specify the comparison."

But the entire point of this PR is to allow multiple operators simultaneously (e.g. gte + lte for a range). The text now actively contradicts the intended behavior, which is going to confuse API consumers reading the generated docs.

✏️ Suggested doc update (shown for NumericFieldFilter, same pattern for the others)

 /**
  * Filter by a numeric value.
- * All properties are optional; provide exactly one to specify the comparison.
+ * All properties are optional; operators can be combined (e.g. gte + lte for a range).
  */

And the same one-line fix in StringFieldFilter, StringFieldFilterExact, ULIDFieldFilter, and DateTimeFieldFilter. The generated openapi.test.yaml descriptions will then update automatically on the next codegen run.

Also applies to: 76-77, 124-125, 150-151, 175-176

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api/spec/packages/aip/src/common/parameters.tsp` around lines 38 - 39, Update
the misleading docstrings for NumericFieldFilter, StringFieldFilter,
StringFieldFilterExact, ULIDFieldFilter, and DateTimeFieldFilter: replace the
line "All properties are optional; provide exactly one to specify the
comparison." with a sentence that states multiple operators may be provided
(e.g. "All properties are optional; one or more operators may be provided to
combine comparisons (for example, gte and lte to express a range).") so the docs
reflect that filters can accept multiple operators simultaneously.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@api/spec/packages/aip/src/common/parameters.tsp`:
- Around line 38-39: Update the misleading docstrings for NumericFieldFilter,
StringFieldFilter, StringFieldFilterExact, ULIDFieldFilter, and
DateTimeFieldFilter: replace the line "All properties are optional; provide
exactly one to specify the comparison." with a sentence that states multiple
operators may be provided (e.g. "All properties are optional; one or more
operators may be provided to combine comparisons (for example, gte and lte to
express a range).") so the docs reflect that filters can accept multiple
operators simultaneously.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6aafb01b-9401-42da-9479-f4149ec66fde

📥 Commits

Reviewing files that changed from the base of the PR and between 8d3a5a0 and 477781c.

⛔ Files ignored due to path filters (1)

• api/v3/openapi.yaml is excluded by !**/openapi.yaml

📒 Files selected for processing (5)

• api/spec/packages/aip/src/common/parameters.tsp
• api/v3/api.gen.go
• api/v3/filters/parse_test.go
• api/v3/test/filters_test.go
• api/v3/test/openapi.test.yaml