Builds OpenAPI filter schemas for Ash resources.

This module generates proper filter parameter schemas that describe the available filter operators for each resource attribute, matching the functionality provided by AshJsonApi.OpenApi.

Overview

JSON:API filtering uses the filter query parameter with a nested object structure. For example:

GET /posts?filter[status]=published&filter[title][contains]=hello

This module generates OpenAPI schemas that describe this structure.

Filter Schema Structure

The generated filter schema is a deepObject style query parameter:

%{
  name: "filter",
  in: :query,
  style: :deepObject,
  explode: true,
  schema: %{
    type: :object,
    properties: %{
      "title" => %{...},
      "status" => %{...},
      "and" => %{...},
      "or" => %{...},
      "not" => %{...}
    }
  }
}

Supported Filter Operators

Equality Operators

• Direct value: filter[field]=value
• eq: filter[field][eq]=value
• ne: filter[field][ne]=value

Comparison Operators

• gt: Greater than
• gte: Greater than or equal
• lt: Less than
• lte: Less than or equal

Set Operators

• in: filter[field][in][]=value1&filter[field][in][]=value2
• not_in: Negation of in

String Operators

• contains: Substring match
• starts_with: Prefix match
• ends_with: Suffix match
• icontains: Case-insensitive contains
• istarts_with: Case-insensitive starts_with
• iends_with: Case-insensitive ends_with

Null Check

• is_nil: filter[field][is_nil]=true

Boolean Operators

• and: Array of filter conditions (all must match)
• or: Array of filter conditions (any must match)
• not: Single filter condition (must not match)

Integration with Generators

This module is used by the V30 and V31 generators to create filter parameter schemas:

filter_param = FilterBuilder.build_filter_parameter(resource)

Configuration

Filtering can be disabled per-resource via AshJsonApi DSL:

json_api do
  derive_filter? false
end

This module respects that configuration when available.