resolver

$ref resolution engine for OpenAPI specifications.

Operates on raw YamlValue trees (before typed decoding) to resolve $ref pointers across files. Supports:

Local refs: #/components/schemas/User
File refs: ./components/schemas/user.yaml
File refs with pointer: ./schemas.yaml#/User

Values

parse_json_pointer

pub fn parse_json_pointer(pointer: String) -> List(String)

Parses a JSON pointer string into path segments. E.g., “/components/schemas/User” → [“components”, “schemas”, “User”] Handles ~0 (→ ~) and ~1 (→ /) escaping.

parse_ref

</>

pub fn parse_ref(
  ref_str: String,
) -> Result(types.ParsedRef, types.RefError)

Parses a $ref string into its components.

resolve

</>

pub fn resolve(
  value: value.YamlValue,
  ctx: types.RefContext,
) -> Result(#(value.YamlValue, types.RefContext), types.RefError)

Resolves all $ref pointers in a YamlValue tree.

Walks the tree recursively. When a mapping contains a “$ref” key, the ref is resolved (loading files as needed) and the mapping is replaced with the resolved value.

resolve_file

</>

pub fn resolve_file(
  entry_path: String,
) -> Result(#(value.YamlValue, types.RefContext), types.RefError)

Convenience entry point: load a file and resolve all its $refs.