Infusion.Ref (infusion v0.1.0)

Copy Markdown View Source

Resolves $refs in an OpenAPI document.

References to schemas (#/components/schemas/...) are kept: each named schema becomes its own struct, and keeping the reference is what lets a schema refer to itself. Every other reference (parameters, responses, request bodies, headers, examples, ...) is replaced by what it points to.

Rules, from measuring real specs:

  • fields next to a $ref (OpenAPI 3.1 allows a summary and description there; OpenAI's spec has 624) override the target's
  • only a $ref whose value is a string is a reference: Cloudflare's spec has a schema with a property named $ref
  • literal data is never read for references: example, default, enum, const, an example's value, a 3.1 schema's examples list, and x- extensions
  • references to other files or URLs are not supported yet (none of the surveyed specs use them)

Summary

Functions

fetch(document, arg2)

Returns what a local reference points to, following the JSON Pointer rules (~1 is /, ~0 is ~, and percent-encoding is decoded).

resolve(document)

Resolves every non-schema reference. Returns an error listing references that point nowhere, point to another document, or form a loop.

schema_name(arg)

Returns the schema name of a schema reference: "#/components/schemas/Pet" -> "Pet".

schema_ref?(ref)

Whether ref points at a named schema.

Functions

fetch(document, arg2)

@spec fetch(map(), String.t()) :: {:ok, term()} | :error

Returns what a local reference points to, following the JSON Pointer rules (~1 is /, ~0 is ~, and percent-encoding is decoded).

resolve(document)

@spec resolve(map()) :: {:ok, map()} | {:error, String.t()}

Resolves every non-schema reference. Returns an error listing references that point nowhere, point to another document, or form a loop.

schema_name(arg)

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

Returns the schema name of a schema reference: "#/components/schemas/Pet" -> "Pet".

schema_ref?(ref)

@spec schema_ref?(String.t()) :: boolean()

Whether ref points at a named schema.