Crate openapi_deref 

Lightweight OpenAPI / JSON Schema $ref resolver.

Recursively expands all $ref pointers in a serde_json::Value, producing a self-contained document with no unresolved references.

Features

• Resolves internal $ref via JSON Pointer (RFC 6901)
• Cycle detection with a visited-path set
• Typed error model: fatal ResolveError vs non-fatal RefError
• resolve_strict for zero-tolerance mode
• Zero dependencies beyond serde_json and thiserror

API levels

Function	Returns	Use when
resolve_strict	Result<Value, StrictResolveError>	Any unresolved ref is unacceptable
resolve	Result<ResolvedDoc, ResolveError>	You need to inspect partial results or diagnostics
resolve_with_root	Result<ResolvedDoc, ResolveError>	The ref lookup root differs from the target value

Quick start

use serde_json::json;

let value = openapi_deref::resolve_strict(&json!({
    "components": { "schemas": { "Id": { "type": "integer" } } },
    "field": { "$ref": "#/components/schemas/Id" }
})).unwrap();

assert_eq!(value["field"]["type"], "integer");

Detailed usage

use serde_json::json;
use openapi_deref::resolve;

let spec = json!({
    "components": {
        "schemas": {
            "User": {
                "type": "object",
                "properties": { "name": { "type": "string" } }
            }
        }
    },
    "paths": {
        "/users": {
            "get": {
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/User" }
                            }
                        }
                    }
                }
            }
        }
    }
});

let doc = resolve(&spec).unwrap();

// Inspect diagnostics without importing RefError
assert!(doc.is_complete());
assert_eq!(doc.cycles().count(), 0);
assert_eq!(doc.missing_refs().count(), 0);
assert_eq!(doc.external_refs().count(), 0);

Error handling

use serde_json::json;
use openapi_deref::{resolve_strict, StrictResolveError};

let spec = json!({ "ref": { "$ref": "#/missing" } });

match resolve_strict(&spec) {
    Ok(value) => { /* fully resolved */ }
    Err(StrictResolveError::Fatal(e)) => {
        eprintln!("fatal: {e}");
    }
    Err(StrictResolveError::Partial(e)) => {
        eprintln!("{e}"); // lists unresolved refs
        let _partial = &e.value; // still usable
    }
    Err(_) => { /* future variants */ }
}

Structs

PartialResolveError

Error returned by ResolvedDoc::into_value when unresolved refs remain.

ResolvedDoc

Result of resolving all $ref pointers in a JSON document.

Enums

RefError

Non-fatal error for a specific $ref pointer.

ResolveError

Fatal error that invalidates the entire resolution.

StrictResolveError

Unified error for resolve_strict.

Functions

resolve

Resolve all $ref pointers in a JSON document.

resolve_strict

Strict resolution — returns Ok(Value) only if all refs are resolved and no fatal errors occur.

resolve_with_root

Resolve $ref pointers in a subtree, using a separate root document for reference lookup.