Oasis.Spec.Document (oasis v0.7.0)

Copy Markdown View Source

Represents a loaded and prepared OpenAPI document.

This struct is the successful return value of Oasis.Spec.read/1. Consumers should pass the complete value through Oasis generation so its source and reference context remain available; :schema may be inspected as the normalized generation view.

Oasis.Spec.Document is responsible only for loading and tracking source metadata for YAML/JSON OpenAPI documents. It intentionally does not interpret OpenAPI structures or JSON Schema semantics.

The :source_path field is important because it becomes the base URI/path used by:

External loading returns JSONSchex-compatible loader metadata with :base_uri so loaded files can resolve their own relative refs correctly.

Summary

Types

load_external_error()

Structured error returned by load_external/1.

load_external_error_status()

String status code used in load_external_error().

pointer_path()
t()

Functions

load(path)

Loads a root OpenAPI document from a YAML/YML or JSON file.

load_external(path)

Loader callback for external OpenAPI and JSON Schema resources.

new(schema, opts \\ [])

Wraps a decoded OpenAPI map with source metadata.

Types

load_external_error()

@type load_external_error() ::
  {load_external_error_status(), String.t()}
  | {load_external_error_status(), String.t(), String.t()}
  | {load_external_error_status(), String.t(), term()}

Structured error returned by load_external/1.

The first tuple element is a fixed string status code rather than an atom. The remaining elements carry the offending file path plus any extra detail so callers (most importantly the JSONSchex loader pipeline and Oasis.Spec.OpenAPIRefResolver) can build precise diagnostics.

load_external_error_status()

@type load_external_error_status() :: String.t()

String status code used in load_external_error().

Allowed values are:

  • "missing_file"
  • "yaml_parse_error"
  • "json_parse_error"
  • "unsupported_format"
  • "invalid_document"

Elixir typespecs cannot enumerate string literals directly, so this remains String.t() at the type level and the fixed set is documented here.

pointer_path()

@type pointer_path() :: [String.t() | non_neg_integer()]

t()

@type t() :: %Oasis.Spec.Document{
  allow_normalized_parameters?: boolean(),
  format: String.t() | nil,
  normalized?: boolean(),
  reference_schema: map() | nil,
  schema: map(),
  schema_sources: %{optional(term()) => pointer_path()},
  source_path: String.t() | nil,
  url_aliases: %{optional(String.t()) => String.t()}
}

Functions

load(path)

@spec load(String.t()) :: {:ok, {map(), keyword()}} | {:error, Exception.t()}

Loads a root OpenAPI document from a YAML/YML or JSON file.

On success this returns the decoded document with options suitable for new/2. On failure it returns Oasis user-facing file/spec exceptions.

load_external(path)

@spec load_external(String.t()) ::
  {:ok, %{document: map() | boolean(), base_uri: String.t()}}
  | {:error, load_external_error()}

Loader callback for external OpenAPI and JSON Schema resources.

Contract

JSONSchex accepts either {:ok, document} or an atom-keyed metadata wrapper {:ok, %{document: document, base_uri: base_uri}}. This default Oasis loader always returns the wrapper form:

load_external(path :: String.t()) ::
    {:ok, %{document: map() | boolean(), base_uri: String.t()}}
  | {:error, load_external_error()}
  • :document — the decoded YAML/JSON document. OpenAPI resources are expected to be maps; JSON Schema resources may also be boolean schemas.
  • :base_uri — the resolved file path or file: URI. Used by JSONSchex (and by Oasis.Spec.OpenAPIRefResolver) to resolve relative refs that appear inside the loaded document against the right base.

Where it is used

Callers wanting in-memory or test-only loaders may override :loader with either valid JSONSchex success form, or pass loader: nil to opt out of external loading entirely (any unresolved external $ref then raises).

new(schema, opts \\ [])

@spec new(
  map(),
  keyword()
) :: t()

Wraps a decoded OpenAPI map with source metadata.

Options:

  • :source_path - file path the document was loaded from (used as base URI).
  • :format - "yaml", "yml", or "json".
  • :url_aliases - map of post-processed (Plug-style) URL key to the original OpenAPI URL key. Populated during path normalization and preserved here so downstream code can report locations using the user's original spec syntax.
  • :reference_schema - structurally resolved but otherwise unnormalized OpenAPI document used as JSONSchex's reference root.
  • :schema_sources - sidecar map from normalized generation inputs to their source JSON Pointer token paths in :reference_schema.
  • :normalized? - internal marker set during path preparation so repeated preparation is idempotent without inferring state from OpenAPI field shapes.
  • :allow_normalized_parameters? - compatibility flag for the legacy pre-normalized map form accepted by internal generation callers.