Repository navigation
Description
Extend or clarify CRUD Causality to describe collections whose membership is selected by query parameters, and how those selectors relate to parent resources.
Moneybird lists subscriptions through GET /{administration_id}/subscriptions.json with a required contact_id query parameter. This is the API's contact-scoped collection semantics. Other APIs express the equivalent relationship as /contacts/{contact_id}/subscriptions. Generic consumers should understand both without provider-name checks.
The current Collection Object describes a URL template and an envelope; identity bindings concern variables in canonical object URLs. It does not explicitly describe parent-derived query selectors. Reusing a global parameter named id for unrelated parent types is also ambiguous.
Questions to resolve
- How is a query-selected collection's identity and membership described, including a selector's relationship to a specific parent resource field?
- How are literal selectors that define a named collection distinguished from caller-selected filters? For example, archived versus active collections are API semantics; choosing what to import is client policy.
- Can OpenAPI Link Objects/runtime expressions provide the relationship? Identify the exact remaining gap for relationships starting from each item in a collection response before adding new syntax.
- How are request context, parent identity and namespaces preserved without accidental Cartesian products or global parameter-name collisions?
- How do these relationships compose with pagination and encoding? Query values must use the normal OpenAPI serialization rules, not path-string substitution followed by double encoding.
Do not specify an import traversal algorithm or require a client to enumerate every parent. Describe which records each API request returns. Singleton responses can already be described as resource reads; any inability of a particular importer to consume them is not, by itself, an extension gap.
Local implementation experiments named listQuery/listQueryBindings are unpublished and are not established syntax for this specification.
Outcome: API-facing collection/selector examples, validation rules and a decision about reuse of standard Links versus a CRUD Causality addition. Related to #7.
References:
Activity
michielbdejong commentedon Sep 10, 2026
A lot of API end points support filtering. we should support that functionality, but essentially the Collection we see through the API is the entire set without filtering. so we don't want to describe each subset separately. maybe we need a Filtering extension to express how some query parameters and URL templates variable will change the resulting response?
There are also situations where an endpoint has a built in filter, such as a 'my issues' endpoint that only returns issues where the author matches the currently logged in user. in fact, in many situations it might be more descriptive if we explicitly say that a certain endpoint will be scoped to what is authed, and in many cases this can be linked to an explicit 'owner' field.
OTOH there are also situations where a filter is required, for instance I once saw an API where the endpoint requires that you either add
direction=incomingordirection=outgoing. This is a rare case so we can postpone handling it until we need it.yeah, in many cases the filter will refer to a field that occurs in the returned objects. please investigate this in some examples and come up with a proposal about how to express this relation in the spec.
I don't think we need to express this. it's fine to model the collection as one big collection where each item has an enum field describing its archived/active status, even if this field is not returned in the results maybe?
Awesome! Yes, use Link objects as much as possible. Also review the current CRUD Causality spec and see if some if it could be simplified by using more Link objects.
I don't understand this question, can you give an example?
Yes, I think you already answered this one there.