AshOaskit.SchemaBuilder.ResourceSchemas (AshOasKit v0.2.0)

Resource schema generation for JSON:API responses and inputs.

This module handles the generation of OpenAPI schemas for Ash resources, including response wrappers, attribute schemas, and input schemas for create/update operations.

Schema Types Generated

For each resource, this module can generate:

Schema	Purpose	Example Name
Attributes	Object containing all public attributes	`PostAttributes`
Response	JSON:API response wrapper with data object	`PostResponse`
Relationships	Object containing relationship linkages	`PostRelationships`
Action input	Input schema derived from one action	`PostCreateInput`, `PostPublishInput`

Attributes Schema

The attributes schema includes:

Public attributes (excluding the sole primary key)
Public calculations (computed values, always nullable)
Public aggregates (summary values, always nullable)

Response Schema

Follows JSON:API structure:

{
  "data": {
    "id": "string",
    "type": "resource_type",
    "attributes": { "$ref": "#/components/schemas/PostAttributes" },
    "relationships": { "$ref": "#/components/schemas/PostRelationships" }
  }
}

Input Schemas

Input schemas are derived per action (see add_action_input_schema/5): the attributes the action accepts plus its public arguments, with required computed from the action's semantics — create-type actions require non-nil attributes without defaults; update-type actions only require require_attributes (partial updates).

Usage

builder = ResourceSchemas.add_resource_schemas(builder, MyApp.Post)

Summary

Functions

action_input_schema_name(schema_name, action_name)

Returns the component schema name for an action's input.

add_action_input_schema(builder, resource, action_name, schema_name, opts)

Adds the input schema for a single action.

add_attributes_schema(builder, resource, schema_name, opts)

Adds the attributes schema for a resource.

add_input_schemas(builder, resource, schema_name, opts)

Adds action-derived input schemas.

add_resource_schemas(builder, resource, opts)

Adds all schemas for a resource to the builder.

add_response_schema(builder, resource, schema_name, add_schema_fn)

Adds the response wrapper schema for a resource.

create_required_attribute?(attr)

Checks if an attribute is required for create operations.

get_public_aggregates(resource)

Gets public aggregates from a resource.

get_public_attributes(resource)

Gets public attributes, excluding the sole primary key.

get_public_calculations(resource)

Gets public calculations from a resource.

get_writable_attributes(resource)

Gets writable attributes for input schemas.

resource_schema_name(resource)

Generates the schema name for a resource.

Functions

action_input_schema_name(schema_name, action_name)

@spec action_input_schema_name(String.t(), atom()) :: String.t()

Returns the component schema name for an action's input.

Examples

iex> ResourceSchemas.action_input_schema_name("Post", :create)
"PostCreateInput"

iex> ResourceSchemas.action_input_schema_name("Post", :bulk_archive)
"PostBulkArchiveInput"

add_action_input_schema(builder, resource, action_name, schema_name, opts)

@spec add_action_input_schema(map(), module(), atom(), String.t(), keyword()) :: map()

Adds the input schema for a single action.

The schema is derived from the action the way AshJsonApi derives request bodies:

properties: the attributes in the action's accept list that are writable, plus the action's public arguments (minus path params, query_params, and relationship_arguments of the given route)
required (create-type actions): accepted attributes with allow_nil?: false, no default, not generated?, and not in allow_nil_input; plus non-nil arguments; plus require_attributes
required (update-type actions): require_attributes plus non-nil arguments — updates are otherwise partial
generic actions document their arguments only

Unknown action names are skipped.

Parameters

builder - The SchemaBuilder accumulator
resource - The Ash resource module
action_name - The action to derive the input from
schema_name - Base name for the schema
opts - Options including :add_schema_fn and :route (the route the action is exposed under, or nil)

Returns

Updated builder with the action input schema added.

add_attributes_schema(builder, resource, schema_name, opts)

@spec add_attributes_schema(map(), module(), String.t(), keyword()) :: map()

Adds the attributes schema for a resource.

Includes regular attributes, calculations, and aggregates. Also generates embedded resource schemas as needed.

Parameters

builder - The SchemaBuilder accumulator
resource - The Ash resource module
schema_name - Base name for the schema
opts - Options with callback functions

Returns

Updated builder with attributes schema added.

add_input_schemas(builder, resource, schema_name, opts)

@spec add_input_schemas(map(), module(), String.t(), keyword()) :: map()

Adds action-derived input schemas.

One input schema is generated per entry in the :input_actions option, named {Resource}{ActionCamelized}Input — for the conventional create/update action names this yields the familiar {Resource}CreateInput/{Resource}UpdateInput.

Each entry is an {action_name, route} tuple (route may be nil). When :input_actions is omitted, the resource's primary create and update actions are used.

Parameters

builder - The SchemaBuilder accumulator
resource - The Ash resource module
schema_name - Base name for the schema
opts - Options including :add_schema_fn and :input_actions

Returns

Updated builder with input schemas added.

add_resource_schemas(builder, resource, opts)

@spec add_resource_schemas(map(), module(), keyword()) :: map()

Adds all schemas for a resource to the builder.

This is the main entry point that generates:

Attributes schema
Response schema
Relationships schema (if resource has relationships)
Action-derived input schemas (see add_input_schemas/4)

Parameters

builder - The SchemaBuilder accumulator
resource - The Ash resource module
opts - Options including callback functions for builder operations

Returns

Updated builder with all resource schemas added.

add_response_schema(builder, resource, schema_name, add_schema_fn)

@spec add_response_schema(map(), module(), String.t(), function()) :: map()

Adds the response wrapper schema for a resource.

Creates a JSON:API compliant response structure with data object containing id, type, attributes, and optionally relationships.

Parameters

builder - The SchemaBuilder accumulator
resource - The Ash resource module
schema_name - Base name for the schema
add_schema_fn - Function to add schemas

Returns

Updated builder with response schema added.

create_required_attribute?(attr)

@spec create_required_attribute?(map()) :: boolean()

Checks if an attribute is required for create operations.

Required for create if: not nullable AND no default value.

Parameters

attr - The attribute struct

Returns

true if required for create, false otherwise.

get_public_aggregates(resource)

@spec get_public_aggregates(module()) :: [map()]

Gets public aggregates from a resource.

Only aggregates marked public? true are included.

Parameters

resource - The Ash resource module

Returns

List of public aggregate structs.

get_public_attributes(resource)

@spec get_public_attributes(module()) :: [map()]

Gets public attributes, excluding the sole primary key.

Only attributes marked public? true are included, matching what AshJsonApi actually serializes. The primary key is excluded only when it is the resource's single primary key — JSON:API carries it as the top-level id member, never inside attributes. Composite primary keys keep their parts as regular attributes. Public timestamps are included.

Parameters

resource - The Ash resource module

Returns

List of public attribute structs.

get_public_calculations(resource)

@spec get_public_calculations(module()) :: [map()]

Gets public calculations from a resource.

Only calculations marked public? true are included.

Parameters

resource - The Ash resource module

Returns

List of public calculation structs.

get_writable_attributes(resource)

@spec get_writable_attributes(module()) :: [map()]

Gets writable attributes for input schemas.

Excludes generated and non-writable attributes from the base public attributes.

Parameters

resource - The Ash resource module

Returns

List of writable attribute structs.

resource_schema_name(resource)

@spec resource_schema_name(module()) :: String.t()

Generates the schema name for a resource.

Extracts the last part of the module name.

Parameters

resource - The Ash resource module

Returns

The schema name string.

Examples

iex> ResourceSchemas.resource_schema_name(MyApp.Blog.Post)
"Post"