roas

Rust OpenAPI Specification — parser, validator, and loader for v2.0 / v3.0.x / v3.1.x / v3.2.x.

A typed, serde-based model of every supported OpenAPI version, with a collecting validator, cross-version conversion, document merging / collapsing, and optional external-$ref loading. JSON and YAML round-trip through the same model.

Versions

Each version lives behind its own feature, so you compile only what you need. With two adjacent versions enabled, a From impl upconverts a spec to the newer one.

Install

cargo add roas

Quick start

cargo add roas serde_json

use roas::v3_2::spec::Spec;
use roas::validation::{Options, Validate};

let raw_json = r#"{ "openapi": "3.2.0", "info": { "title": "demo", "version": "1" }, "paths": {} }"#;
let spec: Spec = serde_json::from_str(raw_json).unwrap();
spec.validate(
    Options::IgnoreMissingTags | Options::IgnoreExternalReferences,
    None,
).unwrap();

Resolving external references

By default, external $refs are reported rather than followed. Register a fetcher on a Loader and pass it to validate to resolve them. Fetchers ship as their own crates — roas-file-fetcher for file:// and roas-http-fetcher for http(s)://:

cargo add roas roas-file-fetcher serde_json

use roas::loader::Loader;
use roas::v3_2::spec::Spec;
use roas::validation::{Options, Validate};
use roas_file_fetcher::FileFetcher;

let raw = std::fs::read_to_string("openapi.json").unwrap();
let spec: Spec = serde_json::from_str(&raw).unwrap();

// Register a fetcher so `file://` $refs resolve during validation.
let mut loader = Loader::new();
loader.register_fetcher("file://", FileFetcher::new());

// Without `IgnoreExternalReferences`, external refs are now followed
// through the loader instead of being reported as unresolved.
spec.validate(Options::IgnoreMissingTags.into(), Some(&mut loader)).unwrap();

For http(s):// refs, register a roas_http_fetcher::HttpFetcher on the http:// and https:// prefixes the same way (it's Clone, so one client can serve both).

Unchanged documents and retrieval metadata

Loader::load_document and load_document_async return a LoadedDocument: the complete parsed value without $ref rewriting, plus its actual retrieval URI. This is useful for consumers that implement their own document identity/base rules, such as Arazzo $self. Both APIs use only explicitly registered fetchers.

Existing fetchers need no changes: the new fetch_document trait methods default to fetch and report the requested URI. Redirect-aware fetchers can override them. roas-http-fetcher 0.2.5 supplies the final response URL.

Raw and existing reference-loading APIs share fetched resources across sync/async cache hits. The legacy load_resource / resolve_reference APIs still return references rewritten against the requested resource URI. Legacy-only callers retain one value plus a compact journal of changed $ref strings, not another full document. A raw view is reconstructed from that journal only when requested, without another fetch. Using both views retains both values. preload_resource replaces the cache entry, invalidates its raw view and clears the typed cache as before.

load_document_shared / load_document_shared_async return Arc<LoadedDocument> handles to the same raw cache entry, so a source registry and its execution options can share the value without cloning it. Existing handles remain valid after cache replacement or loader drop. Loader types/traits are exported at the crate root; their existing roas::loader paths also remain valid.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.