AshOaskit.ResponseMeta (AshOasKit v0.2.0)

Generates JSON:API response meta schemas for OpenAPI specifications.

This module provides functions to build meta objects for JSON:API responses, including pagination metadata, record counts, and the JSON:API version object. Meta objects provide non-standard information that complements the primary data.

Meta Object Types

Pagination Meta

Pagination responses typically include meta information about:

count or total - Total number of records in the collection
page - Current pagination state (offset, limit, etc.)

Resource Meta

Individual resources may include custom meta information defined by the application.

JSON:API Version Object

Top-level document meta can include the JSON:API version being used:

{
  "jsonapi": {
    "version": "1.0"
  }
}

OpenAPI Version Differences

OpenAPI 3.1: Uses native JSON Schema features
OpenAPI 3.0: May require compatibility adjustments

Usage

# Build pagination meta schema
AshOaskit.ResponseMeta.build_pagination_meta_schema(version: "3.1")

# Build JSONAPI version object schema
AshOaskit.ResponseMeta.build_jsonapi_object_schema()

# Add meta to response schema
AshOaskit.ResponseMeta.add_meta_to_response(response, meta_type: :pagination)

JSON:API Meta Structure

{
  "meta": {
    "count": 100,
    "page": {
      "offset": 20,
      "limit": 10,
      "total": 100
    }
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Summary

Functions

add_jsonapi_object_to_response(response_schema, opts \\ [])

Adds the jsonapi version object to a response schema.

add_meta_to_response(response_schema, opts \\ [])

Adds meta schema to an existing response schema.

build_complete_meta_schema(opts \\ [])

Builds a complete top-level document meta section.

build_document_meta_schema(opts \\ [])

Builds a document-level meta schema.

build_jsonapi_object_schema(opts \\ [])

Builds the JSON:API version object schema.

build_meta_component_schemas(opts \\ [])

Generates named meta schema references for use in components.

build_page_info_schema(strategy \\ :both, version \\ "3.1")

Builds a page info schema based on pagination strategy.

build_pagination_meta_schema(opts \\ [])

Builds a meta schema for paginated collection responses.

build_resource_meta_schema(_ \\ [])

Builds a generic resource meta schema.

build_response_meta_schema(opts \\ [])

Builds a response meta schema for different response types.

paginated_route?(route_type)

Checks if a route type should include pagination meta.

Functions

add_jsonapi_object_to_response(response_schema, opts \\ [])

@spec add_jsonapi_object_to_response(
  map(),
  keyword()
) :: map()

Adds the jsonapi version object to a response schema.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:supported_versions - List of supported JSON:API versions. Defaults to ["1.0", "1.1"].

Examples

response = %{type: :object, properties: %{data: %{}}}
AshOaskit.ResponseMeta.add_jsonapi_object_to_response(response)
# => %{
#      type: :object,
#      properties: %{
#        data: %{},
#        jsonapi: %{...jsonapi_object_schema...}
#      }
#    }

add_meta_to_response(response_schema, opts \\ [])

@spec add_meta_to_response(
  map(),
  keyword()
) :: map()

Adds meta schema to an existing response schema.

Takes a response schema and adds the appropriate meta property.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:meta_type - Type of meta to add (:resource, :pagination, :document). Defaults to :resource.

Examples

response = %{type: :object, properties: %{data: %{}}}
AshOaskit.ResponseMeta.add_meta_to_response(response, meta_type: :pagination)
# => %{
#      type: :object,
#      properties: %{
#        data: %{},
#        meta: %{...pagination_meta_schema...}
#      }
#    }

build_complete_meta_schema(opts \\ [])

@spec build_complete_meta_schema(keyword()) :: map()

Builds a complete top-level document meta section.

This combines all top-level meta information: count, page info, and application-specific meta.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:include_count - Whether to include count. Defaults to true.
:include_page - Whether to include page info. Defaults to true.
:pagination_strategy - Pagination strategy. Defaults to :both.

Examples

iex> AshOaskit.ResponseMeta.build_complete_meta_schema(
...>   include_count: true,
...>   include_page: true
...> )
%{
  type: :object,
  properties: %{
    count: %{...},
    page: %{...}
  },
  additionalProperties: true
}

build_document_meta_schema(opts \\ [])

@spec build_document_meta_schema(keyword()) :: map()

Builds a document-level meta schema.

Top-level documents can include meta objects with application-specific information. This is typically used for pagination counts in collections.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:include_count - Whether to include count property. Defaults to true.
:include_page - Whether to include page info. Defaults to false.

Examples

iex> AshOaskit.ResponseMeta.build_document_meta_schema(include_count: true)
%{
  type: :object,
  properties: %{
    count: %{type: :integer}
  }
}

build_jsonapi_object_schema(opts \\ [])

@spec build_jsonapi_object_schema(keyword()) :: map()

Builds the JSON:API version object schema.

The jsonapi object describes the implementation's version of the JSON:API spec.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:supported_versions - List of supported JSON:API versions. Defaults to ["1.0", "1.1"].

Examples

iex> AshOaskit.ResponseMeta.build_jsonapi_object_schema()
%{
  type: :object,
  properties: %{
    version: %{type: :string, enum: ["1.0", "1.1"]}
  }
}

build_meta_component_schemas(opts \\ [])

@spec build_meta_component_schemas(keyword()) :: map()

Generates named meta schema references for use in components.

Creates schema definitions that can be added to the components/schemas section and referenced via $ref.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:name_prefix - Prefix for the schema name. Defaults to "".

Examples

AshOaskit.ResponseMeta.build_meta_component_schemas(version: "3.1")
# => %{
#      "Meta" => %{...resource_meta_schema...},
#      "PaginationMeta" => %{...pagination_meta_schema...},
#      "JsonApi" => %{...jsonapi_object_schema...}
#    }

build_page_info_schema(strategy \\ :both, version \\ "3.1")

@spec build_page_info_schema(atom(), String.t()) :: map()

Builds a page info schema based on pagination strategy.

Options

:strategy - One of :offset, :keyset, or :both. Defaults to :both.
:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".

Examples

iex> AshOaskit.ResponseMeta.build_page_info_schema(:offset)
%{
  type: :object,
  properties: %{
    offset: %{type: :integer},
    limit: %{type: :integer},
    total: %{type: :integer}
  }
}

build_pagination_meta_schema(opts \\ [])

@spec build_pagination_meta_schema(keyword()) :: map()

Builds a meta schema for paginated collection responses.

Returns a JSON Schema object describing the meta information that can appear in paginated responses.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:pagination_strategy - One of :offset, :keyset, or :both. Defaults to :both.

Examples

iex> AshOaskit.ResponseMeta.build_pagination_meta_schema(version: "3.1")
%{
  type: :object,
  properties: %{
    count: %{type: :integer},
    page: %{...}
  }
}

build_resource_meta_schema(_ \\ [])

@spec build_resource_meta_schema(keyword()) :: map()

Builds a generic resource meta schema.

Resources can include application-specific meta information. This schema allows any additional properties.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".

Examples

iex> AshOaskit.ResponseMeta.build_resource_meta_schema()
%{
  type: :object,
  additionalProperties: true
}

build_response_meta_schema(opts \\ [])

@spec build_response_meta_schema(keyword()) :: map()

Builds a response meta schema for different response types.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:response_type - One of :single, :collection, or :relationship. Defaults to :single.

Examples

AshOaskit.ResponseMeta.build_response_meta_schema(response_type: :collection)
# => %{...pagination_meta_schema...}

AshOaskit.ResponseMeta.build_response_meta_schema(response_type: :single)
# => %{...resource_meta_schema...}

paginated_route?(route_type)

@spec paginated_route?(atom()) :: boolean()

Checks if a route type should include pagination meta.

Examples

iex> AshOaskit.ResponseMeta.paginated_route?(:index)
true

iex> AshOaskit.ResponseMeta.paginated_route?(:get)
false