oaspec - v0.55.0

oaspec/openapi/parser

Values

parse_error_to_string

</> 
pub fn parse_error_to_string(
  error: diagnostic.Diagnostic,
) -> String

Parse a schema reference (either $ref or inline schema). Convert a parse error to a human-readable string.

parse_file

</> 
pub fn parse_file(
  path: String,
) -> Result(
  @internal OpenApiSpec(@internal Unresolved),
  diagnostic.Diagnostic,
)

Parse an OpenAPI spec from a file path. Supports both YAML (.yaml, .yml) and JSON (.json) files. After parsing, resolves relative-file $ref values across schemas, parameters, request bodies, responses, and path items — including nested object/array properties and composition branches — by loading the referenced files from disk and merging their definitions into the main spec. Cyclic external ref graphs (A.yaml → B.yaml → A.yaml) fail fast with a dedicated diagnostic. HTTP/HTTPS URLs are not followed.

parse_file_with_progress_and_locations

</> 
pub fn parse_file_with_progress_and_locations(
  path: String,
  reporter: @internal Reporter,
) -> Result(
  #(
    @internal OpenApiSpec(@internal Unresolved),
    @internal LocationIndex,
  ),
  diagnostic.Diagnostic,
)

Combined parse_file entry point that accepts a Reporter and also returns the top-level YAML LocationIndex. Issue #411 + #352. The CLI uses this so capability-check diagnostics surface path:line:column: and progress lines on big specs at the same time. Library callers that don’t need progress should pass progress.noop(); callers that don’t need locations can discard the second tuple element.

parse_json_string

</> 
pub fn parse_json_string(
  content: String,
) -> Result(
  @internal OpenApiSpec(@internal Unresolved),
  diagnostic.Diagnostic,
)

Parse an OpenAPI spec from a JSON string using OTP’s native JSON decoder instead of yamerl. Roughly two orders of magnitude faster than parse_string on large specs because the YAML pre-processing and constructor passes are skipped (issue #352). Behaves like parse_string once the tree is built — same OpenApiSpec shape, same downstream pipeline. Diagnostics from this path do not carry source line/column info because OTP json:decode/3 does not expose decoder positions; the caller still gets the path-prefixed error message that downstream tooling relies on.

parse_string

</> 
pub fn parse_string(
  content: String,
) -> Result(
  @internal OpenApiSpec(@internal Unresolved),
  diagnostic.Diagnostic,
)

Parse an OpenAPI spec from a YAML/JSON string. The default path runs the input through yamerl, which preserves YAML semantics and source locations but is too slow on large JSON specs (the GitHub REST OpenAPI is ~12 MB and yamerl effectively hangs — see issue #352). Use parse_json_string directly when the content is known to be JSON.

parse_string_with_locations

</> 
pub fn parse_string_with_locations(
  content: String,
) -> Result(
  #(
    @internal OpenApiSpec(@internal Unresolved),
    @internal LocationIndex,
  ),
  diagnostic.Diagnostic,
)

Same as parse_string but also returns the YAML LocationIndex built from the input. Caller-side companion to parse_file_with_locations (Issue #411).

✨ Search Document