AshOaskit.Core.SchemaRef (AshOasKit v0.2.1)

Builds OpenAPI $ref objects pointing to component schemas.

JSON Schema references ($ref) are the standard mechanism for reusing schema definitions in OpenAPI specifications. Every resource, relationship, and error schema is defined once under components/schemas and referenced elsewhere via a $ref pointer.

Why string keys?

The Oaskit normalizer identifies references by checking for the "$ref" string key. Using an atom key (:$ref) would cause the normalizer to miss the reference entirely, resulting in broken specs. This module encapsulates that convention so callers never need to remember it.

Usage

Import or alias in any module that needs to emit $ref pointers:

import AshOaskit.Core.SchemaRef

# Inside a schema map
%{
  "data" => schema_ref("User"),
  "included" => %{"type" => "array", "items" => schema_ref("User")}
}

Callers

Used across the generator pipeline:

Module	Purpose
`Generator`	Top-level component wiring
`PathBuilder`	Request/response body refs
`ErrorSchemas`	Error source schema refs
`MultipartSupport`	File upload schema refs
`ResourceSchemas`	Resource data/attributes refs
`IncludedResources`	Polymorphic included refs
`RouteResponses`	Relationship route response refs

Examples

iex> AshOaskit.Core.SchemaRef.schema_ref("Post")
%{"$ref" => "#/components/schemas/Post"}

iex> AshOaskit.Core.SchemaRef.schema_ref_path("PostAttributes")
"#/components/schemas/PostAttributes"

Summary

Functions

schema_ref(name)

Builds a JSON Schema $ref object pointing to a component schema.

schema_ref_path(name)

Builds a $ref path string pointing to a component schema.

Functions

schema_ref(name)

@spec schema_ref(String.t()) :: map()

Builds a JSON Schema $ref object pointing to a component schema.

Returns a map with a single "$ref" string key. The key is intentionally a string — see the module documentation for why.

Parameters

name - The schema name as registered under components/schemas

Examples

iex> AshOaskit.Core.SchemaRef.schema_ref("User")
%{"$ref" => "#/components/schemas/User"}

iex> AshOaskit.Core.SchemaRef.schema_ref("PostRelationships")
%{"$ref" => "#/components/schemas/PostRelationships"}

schema_ref_path(name)

@spec schema_ref_path(String.t()) :: String.t()

Builds a $ref path string pointing to a component schema.

Returns the full JSON Pointer path for use in $ref values.

Parameters

name - The schema name as registered under components/schemas

Examples

iex> AshOaskit.Core.SchemaRef.schema_ref_path("User")
"#/components/schemas/User"

iex> AshOaskit.Core.SchemaRef.schema_ref_path("UserAttributes")
"#/components/schemas/UserAttributes"