Crate roas_overlay

Expand description

OpenAPI Overlay Specification — parser, validator, and applier.

Implements the OpenAPI Overlay Specification (v1.0 / v1.1): a sidecar document format that transforms OpenAPI documents through an ordered list of JSONPath actions (update, remove, and v1.1’s copy).

§Modules

common — version-agnostic helpers: x- extensions serde helpers, RFC 9535 JSONPath wrapper, the §4.4.3.1 recursive merge.
validation — Validate trait, ValidationOptions flag set, Context / ValidationError types.
apply — Apply trait, ApplyOptions, ApplyReport, ApplyError.
v1_0 — Overlay v1.0 document model + Validate / Apply impls.
v1_1 — Overlay v1.1 document model + Validate / Apply impls.

§Applying an overlay

use enumset::EnumSet;
use roas_overlay::apply::Apply;
use roas_overlay::v1_1::Overlay;

// Parse the overlay document (JSON or YAML).
let overlay: Overlay = serde_json::from_str(r#"{
    "overlay": "1.1.0",
    "info": { "title": "Example", "version": "1.0.0" },
    "actions": [
        { "target": "$.info", "update": { "description": "Patched." } }
    ]
}"#).unwrap();

// Parse the target OpenAPI document as untyped JSON.
let mut target: serde_json::Value = serde_json::from_str(r#"{
    "openapi": "3.1.0",
    "info": { "title": "API", "version": "1.0.0" },
    "paths": {}
}"#).unwrap();

// Apply the overlay in-place.
let report = overlay.apply(&mut target, EnumSet::empty()).unwrap();
assert_eq!(report.actions.len(), 1);
assert_eq!(target["info"]["description"], "Patched.");

§Versions

v1.0.x (v1_0) and v1.1.x (v1_1, default feature) are both implemented; enable whichever you need. With both features enabled, an impl From<v1_0::Overlay> for v1_1::Overlay is available for upconverting an existing v1.0 document.

Modules§

apply: Public surface for applying an Overlay to a target JSON document.
common: Version-agnostic helpers shared across overlay versions.
v1_0: OpenAPI Overlay v1.0 — see https://spec.openapis.org/overlay/v1.0.0.html.
v1_1: OpenAPI Overlay v1.1 — see https://spec.openapis.org/overlay/v1.1.0.html.
validation: Validation framework for Overlay documents.