AshOaskit.SortBuilder (AshOasKit v0.2.0)

Builds OpenAPI sort parameter schemas for Ash resources.

This module generates proper sort parameter schemas that reflect the actual sortable fields available on an Ash resource, including attributes, calculations, and aggregates that support sorting.

Sort Parameter Format

The JSON:API specification allows sorting via a comma-separated list of field names. Fields can be prefixed with - for descending order or + (optional) for ascending.

Example

GET /posts?sort=-created_at,title

This sorts by created_at descending, then title ascending.

Generated Schema

The sort parameter schema includes:

An enum of all valid sort field values
Both ascending and descending variants for each field
A description listing available fields

Usage

# Build sort parameter for a resource
param = SortBuilder.build_sort_parameter(MyApp.Post)

# With options
param = SortBuilder.build_sort_parameter(MyApp.Post, version: "3.0")

Configuration

Sort derivation can be disabled via the derive_sort? configuration on the AshJsonApi resource DSL. When disabled, this module returns nil.

Summary

Functions

build_sort_array_schema(sortable_fields, opts)

Builds an array-based sort schema for multiple sort fields.

build_sort_enum_schema(sortable_fields, _)

Builds an enum-based sort schema with explicit field values.

build_sort_parameter(resource, opts \\ [])

Builds the sort query parameter schema for the given resource.

build_sort_schema(sortable_fields, _)

Builds the sort schema object.

get_sortable_fields(resource)

Gets all sortable fields for the given resource.

Functions

build_sort_array_schema(sortable_fields, opts)

@spec build_sort_array_schema(
  [atom()],
  keyword()
) :: map()

Builds an array-based sort schema for multiple sort fields.

This creates a schema for accepting an array of sort values, useful when the API accepts sort as repeated query parameters rather than a comma-separated string.

Parameters

sortable_fields - List of atom field names
opts - Options keyword list

Returns

A map with array type and items schema.

Examples

iex> SortBuilder.build_sort_array_schema([:title], [])
%{
  type: :array,
  items: %{
    type: :string,
    enum: ["title", "-title"]
  }
}

build_sort_enum_schema(sortable_fields, _)

@spec build_sort_enum_schema(
  [atom()],
  keyword()
) :: map()

Builds an enum-based sort schema with explicit field values.

This creates a more restrictive schema that explicitly enumerates all valid sort values, including both ascending and descending variants.

Parameters

sortable_fields - List of atom field names
opts - Options keyword list

Returns

A map with an enum array of valid sort values.

Examples

iex> SortBuilder.build_sort_enum_schema([:title, :created_at], [])
%{
  type: :string,
  enum: ["title", "-title", "created_at", "-created_at"]
}

build_sort_parameter(resource, opts \\ [])

@spec build_sort_parameter(
  module(),
  keyword()
) :: map() | nil

Builds the sort query parameter schema for the given resource.

Returns an OpenAPI parameter object with a schema that enumerates all valid sort field values (both ascending and descending variants).

Parameters

resource - The Ash resource module
opts - Options keyword list
- :version - OpenAPI version ("3.0" or "3.1", defaults to "3.1")

Returns

A map representing the OpenAPI parameter object, or
nil if sorting is disabled for the resource

Examples

iex> SortBuilder.build_sort_parameter(MyApp.Post)
%{
  name: "sort",
  in: :query,
  required: false,
  schema: %{
    type: :string,
    description: "..."
  },
  description: "Sort criteria for Post records"
}

build_sort_schema(sortable_fields, _)

@spec build_sort_schema(
  [atom()],
  keyword()
) :: map()

Builds the sort schema object.

Creates an OpenAPI schema that describes valid sort parameter values. The schema uses a string type with a description of available fields and their sort directions.

Parameters

sortable_fields - List of atom field names
opts - Options keyword list (version, etc.)

Returns

A map representing the OpenAPI schema object.

Examples

iex> SortBuilder.build_sort_schema([:title, :created_at], [])
%{
  type: :string,
  description: "Comma-separated list of fields. Prefix with '-' for descending."
}

get_sortable_fields(resource)

@spec get_sortable_fields(module()) :: [atom()]

Gets all sortable fields for the given resource.

Returns a list of field names (as atoms) that can be used in sort parameters. This includes:

Public attributes
Public calculations marked as sortable
Public aggregates

Parameters

resource - The Ash resource module

Returns

A list of atom field names.

Examples

iex> SortBuilder.get_sortable_fields(MyApp.Post)
[:title, :created_at, :view_count, :comment_count]