cloudevents / cloudevents/spec
[Subscription API] Purpose of Filter schema object in OAS not clear
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 5.9k
- Forks
- 613
- Avg merge
- 2d 17h
- Merged PRs (30d)
- 3
Description
In the OAS for the Subscription API the Filter object is included:
Filter:
title: "Filter"
description: "A filter from a selection of multiple filter types and dialects"
type: object
additionalProperties: true
The Filter object is used in all the filter dialects as the basis of the allOf construction, for instance in the ExactFilter:
ExactFilter:
allOf:
- $ref: "#/components/schemas/Filter"
- type: object
title: "exact filter"
description: "This filter evaluates to 'true' if the 'value' exactly matches the value of the indicated CloudEvents context attribute"
properties:
exact:
$ref: "#/components/schemas/CloudEventsAttribute"
additionalProperties: false
It is not clear for me what the purpose is of this allOf construction with the Filter object as basis schema. It seems that the Filter object offers an extension mechanism to the standard filter dialects (All, Any, Not, Exact, Suffix, Prefix, etc.) because it contains the clause additionalProperties: true. Could somebody give me a concrete example of a JSON filter expression where this is used?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the Subscription API OAS definitions for Filter and ExactFilter, focusing on their allOf relationship and additionalProperties settings. Determine whether Filter is intended to provide an extension mechanism, then document the intended behavior with a concrete JSON filter example or clarify the schema design.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100