AshOaskit.ResponseLinks (AshOasKit v0.2.0)

Generates JSON:API response links schemas for OpenAPI specifications.

This module provides functions to build link objects for JSON:API responses, including self links, related links, and pagination links (first, last, prev, next). Links are essential for HATEOAS compliance and enable clients to navigate the API without hardcoding URLs.

Link Types

Self Links

Every resource and collection response should include a self link pointing to the canonical URL for that resource or collection.

Relationship objects include related links that point to the related resource collection endpoint.

Pagination Links

Collection responses include pagination links:

first - URL to the first page of results
last - URL to the last page of results
prev - URL to the previous page (null if on first page)
next - URL to the next page (null if on last page)

OpenAPI Version Differences

OpenAPI 3.1: Uses type: ["string", "null"] for nullable fields
OpenAPI 3.0: Uses type: "string" with nullable: true

Usage

# Build a resource links schema
AshOaskit.ResponseLinks.build_resource_links_schema(version: "3.1")

# Build pagination links schema
AshOaskit.ResponseLinks.build_pagination_links_schema(version: "3.1")

# Build relationship links schema
AshOaskit.ResponseLinks.build_relationship_links_schema(version: "3.1")

JSON:API Links Structure

{
  "links": {
    "self": "https://api.example.com/posts/1",
    "related": "https://api.example.com/posts/1/comments"
  }
}

For paginated collections:

{
  "links": {
    "self": "https://api.example.com/posts?page[offset]=20&page[limit]=10",
    "first": "https://api.example.com/posts?page[offset]=0&page[limit]=10",
    "last": "https://api.example.com/posts?page[offset]=90&page[limit]=10",
    "prev": "https://api.example.com/posts?page[offset]=10&page[limit]=10",
    "next": "https://api.example.com/posts?page[offset]=30&page[limit]=10"
  }
}

Summary

Functions

add_links_to_response(response_schema, opts \\ [])

Adds links schema to an existing response schema.

build_collection_links_schema(opts \\ [])

Builds a links schema for collection responses with pagination.

build_document_links_schema(opts \\ [])

Builds a top-level document links schema.

build_flexible_links_schema(opts \\ [])

Builds a comprehensive links schema that can contain any valid link type.

build_link_object_schema(_ \\ [])

Builds a link object schema (for when links themselves have objects as values).

build_links_component_schemas(opts \\ [])

Generates a named links schema reference for use in components.

build_nullable_link_object_schema(opts \\ [])

Builds a nullable link object schema.

build_pagination_links_schema(opts \\ [])

Builds a links schema specifically for pagination.

build_relationship_links_schema(_ \\ [])

Builds a links schema for relationship objects.

build_resource_links_schema(_ \\ [])

Builds a complete links schema for resource responses.

paginated_route?(route_type)

Checks if a route type should include pagination links.

Functions

add_links_to_response(response_schema, opts \\ [])

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

Adds links schema to an existing response schema.

Takes a response schema and adds the appropriate links property.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:link_type - Type of links to add (:resource, :collection, :relationship). Defaults to :resource.

Examples

response = %{type: :object, properties: %{data: %{}}}
AshOaskit.ResponseLinks.add_links_to_response(response, link_type: :collection)
# => %{
#      type: :object,
#      properties: %{
#        data: %{},
#        links: %{...collection_links_schema...}
#      }
#    }

build_collection_links_schema(opts \\ [])

@spec build_collection_links_schema(keyword()) :: map()

Builds a links schema for collection responses with pagination.

Returns a JSON Schema object describing the links that can appear in a collection response, including pagination links.

Options

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

Examples

iex> AshOaskit.ResponseLinks.build_collection_links_schema(version: "3.1")
%{
  type: :object,
  properties: %{
    self: %{type: :string, format: :uri},
    first: %{type: :string, format: :uri},
    last: %{type: :string, format: :uri},
    prev: %{type: [:string, :null], format: :uri},
    next: %{type: [:string, :null], format: :uri}
  }
}

build_document_links_schema(opts \\ [])

@spec build_document_links_schema(keyword()) :: map()

Builds a top-level document links schema.

This is used for the top-level links object in JSON:API responses, which can include both resource/collection self links and pagination.

Options

:version - OpenAPI version ("3.1" or "3.0"). Defaults to "3.1".
:paginated - Whether to include pagination links. Defaults to false.

Examples

iex> AshOaskit.ResponseLinks.build_document_links_schema(version: "3.1", paginated: true)
%{
  type: :object,
  properties: %{
    self: %{type: :string, format: :uri},
    first: %{type: :string, format: :uri},
    last: %{type: :string, format: :uri},
    prev: %{type: [:string, :null], format: :uri},
    next: %{type: [:string, :null], format: :uri}
  }
}

build_flexible_links_schema(opts \\ [])

@spec build_flexible_links_schema(keyword()) :: map()

Builds a comprehensive links schema that can contain any valid link type.

This flexible schema allows for self, related, and pagination links, useful when the exact link set isn't known at schema generation time.

Options

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

Examples

iex> AshOaskit.ResponseLinks.build_flexible_links_schema(version: "3.1")
%{
  type: :object,
  properties: %{
    self: %{type: :string, format: :uri},
    related: %{type: :string, format: :uri},
    first: %{type: :string, format: :uri},
    last: %{type: :string, format: :uri},
    prev: %{type: [:string, :null], format: :uri},
    next: %{type: [:string, :null], format: :uri}
  },
  additionalProperties: %{type: :string, format: :uri}
}

build_link_object_schema(_ \\ [])

@spec build_link_object_schema(keyword()) :: map()

Builds a link object schema (for when links themselves have objects as values).

Per JSON:API spec, a link can be either a string URL or a link object with href and optional meta.

Options

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

Examples

iex> AshOaskit.ResponseLinks.build_link_object_schema(version: "3.1")
%{
  oneOf: [
    %{type: :string, format: :uri},
    %{
      type: :object,
      required: ["href"],
      properties: %{
        href: %{type: :string, format: :uri},
        meta: %{type: :object, additionalProperties: true}
      }
    }
  ]
}

build_links_component_schemas(opts \\ [])

@spec build_links_component_schemas(keyword()) :: map()

Generates a named links schema reference for use in components.

Creates a schema definition 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.ResponseLinks.build_links_component_schemas(version: "3.1")
# => %{
#      "Links" => %{...resource_links_schema...},
#      "PaginationLinks" => %{...pagination_links_schema...},
#      "RelationshipLinks" => %{...relationship_links_schema...}
#    }

build_nullable_link_object_schema(opts \\ [])

@spec build_nullable_link_object_schema(keyword()) :: map()

Builds a nullable link object schema.

Used for links that may be null (like prev/next in pagination).

Options

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

Examples

AshOaskit.ResponseLinks.build_nullable_link_object_schema(version: "3.1")
# => %{
#      oneOf: [
#        %{type: :null},
#        %{type: :string, format: :uri},
#        %{...link_object...}
#      ]
#    }

build_pagination_links_schema(opts \\ [])

@spec build_pagination_links_schema(keyword()) :: map()

Builds a links schema specifically for pagination.

This is a subset of collection links focused only on pagination navigation.

Options

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

Examples

iex> AshOaskit.ResponseLinks.build_pagination_links_schema(version: "3.0")
%{
  type: :object,
  properties: %{
    first: %{type: :string, format: :uri},
    last: %{type: :string, format: :uri},
    prev: %{type: :string, format: :uri, nullable: true},
    next: %{type: :string, format: :uri, nullable: true}
  }
}

build_relationship_links_schema(_ \\ [])

@spec build_relationship_links_schema(keyword()) :: map()

Builds a links schema for relationship objects.

Relationship links include:

self - The URL for the relationship itself (for manipulation)
related - The URL for the related resource(s)

Options

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

Examples

iex> AshOaskit.ResponseLinks.build_relationship_links_schema(version: "3.1")
%{
  type: :object,
  properties: %{
    self: %{type: :string, format: :uri},
    related: %{type: :string, format: :uri}
  }
}

build_resource_links_schema(_ \\ [])

@spec build_resource_links_schema(keyword()) :: map()

Builds a complete links schema for resource responses.

Returns a JSON Schema object describing the links that can appear in a single resource response (self link only).

Options

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

Examples

iex> AshOaskit.ResponseLinks.build_resource_links_schema(version: "3.1")
%{
  type: :object,
  properties: %{
    self: %{type: :string, format: :uri}
  }
}

paginated_route?(route_type)

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

Checks if a route type should include pagination links.

Examples

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

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

AshOaskit.ResponseLinks (AshOasKit v0.2.0)

Link Types

Self Links

Related Links

Pagination Links

OpenAPI Version Differences

Usage

JSON:API Links Structure

Summary

Functions

Functions

add_links_to_response(response_schema, opts \\ [])

Options

Examples

build_collection_links_schema(opts \\ [])

Options

Examples

build_document_links_schema(opts \\ [])

Options

Examples

build_flexible_links_schema(opts \\ [])

Options

Examples

build_link_object_schema(_ \\ [])

Options

Examples

build_links_component_schemas(opts \\ [])

Options

Examples

build_nullable_link_object_schema(opts \\ [])

Options

Examples

build_pagination_links_schema(opts \\ [])

Options

Examples

build_relationship_links_schema(_ \\ [])

Options

Examples

build_resource_links_schema(_ \\ [])

Options

Examples

paginated_route?(route_type)

Examples