[GH-ISSUE #8912] [Feature] Import OpenAPI and AsyncAPI documents as offline API contract Evidence #7787

New issue

Open

opened 2026-11-04 15:15:31 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-04 15:15:31 +00:00

Owner

Originally created by @jayykernel on GitHub (Nov 4, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/8912

Summary

Add offline import and analysis for OpenAPI and AsyncAPI documents, turning API specifications into structured Evidence that can be searched, compared, and correlated with captured network artifacts.

Motivation

API specifications describe intended endpoints, operations, schemas, authentication mechanisms, and event channels. Analysts often need to compare those contracts with observed HTTP traffic, WebSocket messages, or other retained artifacts without contacting the target service.

Proposed behavior

Accept OpenAPI 3.x documents in JSON or YAML and AsyncAPI documents in supported JSON/YAML versions.
Resolve local relative references within an explicitly supplied artifact set, while recording unresolved or cyclic references.
Extract servers, paths, methods, parameters, request/response media types, status codes, schemas, security schemes, tags, callbacks, and webhooks from OpenAPI.
Extract servers, channels, publish/subscribe operations, message payload schemas, bindings, and security schemes from AsyncAPI.
Build searchable operation/channel inventories and normalized schema graphs.
Compare two specification revisions and report added, removed, or changed operations, fields, constraints, security requirements, and message contracts.
Where matching captured traffic exists, provide an evidence-backed comparison between observed requests/responses and declared contracts; clearly distinguish observed facts from specification claims.

Safety and resource boundaries

Operate entirely offline; never probe declared server URLs or fetch remote references.
Do not resolve external $ref URLs. Report them as unresolved external references.
Treat YAML and JSON as untrusted input; use bounded parsing, recursion depth, document size, and reference-resolution limits.
Do not execute examples, callbacks, scripts, or vendor extensions.
Preserve source locations and reference chains for extracted operations and schema properties.

Acceptance criteria

Import representative OpenAPI 3.x JSON and YAML documents into structured Evidence.
Import supported AsyncAPI documents and expose channels, operations, and message schemas.
Resolve local references deterministically and diagnose missing, cyclic, and external references.
Generate stable operation and channel identifiers suitable for cross-version comparison.
Produce meaningful contract diffs for endpoint, parameter, schema, response, and security changes.
Correlate matching captured HTTP artifacts without treating the specification as proof of runtime behavior.
Include malformed, deeply nested, oversized, and reference-cycle fixtures.
Verify that importing a document performs no network access.

Out of scope

Live API discovery, endpoint fuzzing, active probing, authentication attempts, or server generation.
Claiming that a declared operation is implemented or reachable unless supported by separate runtime Evidence.

Suggested implementation

Use separate OpenAPI and AsyncAPI adapters that emit a shared normalized contract graph. Keep source-format details and diagnostics attached so comparisons remain explainable and reproducible.

Originally created by @jayykernel on GitHub (Nov 4, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/8912 ## Summary Add offline import and analysis for OpenAPI and AsyncAPI documents, turning API specifications into structured Evidence that can be searched, compared, and correlated with captured network artifacts. ## Motivation API specifications describe intended endpoints, operations, schemas, authentication mechanisms, and event channels. Analysts often need to compare those contracts with observed HTTP traffic, WebSocket messages, or other retained artifacts without contacting the target service. ## Proposed behavior - Accept OpenAPI 3.x documents in JSON or YAML and AsyncAPI documents in supported JSON/YAML versions. - Resolve local relative references within an explicitly supplied artifact set, while recording unresolved or cyclic references. - Extract servers, paths, methods, parameters, request/response media types, status codes, schemas, security schemes, tags, callbacks, and webhooks from OpenAPI. - Extract servers, channels, publish/subscribe operations, message payload schemas, bindings, and security schemes from AsyncAPI. - Build searchable operation/channel inventories and normalized schema graphs. - Compare two specification revisions and report added, removed, or changed operations, fields, constraints, security requirements, and message contracts. - Where matching captured traffic exists, provide an evidence-backed comparison between observed requests/responses and declared contracts; clearly distinguish observed facts from specification claims. ## Safety and resource boundaries - Operate entirely offline; never probe declared server URLs or fetch remote references. - Do not resolve external `$ref` URLs. Report them as unresolved external references. - Treat YAML and JSON as untrusted input; use bounded parsing, recursion depth, document size, and reference-resolution limits. - Do not execute examples, callbacks, scripts, or vendor extensions. - Preserve source locations and reference chains for extracted operations and schema properties. ## Acceptance criteria - [ ] Import representative OpenAPI 3.x JSON and YAML documents into structured Evidence. - [ ] Import supported AsyncAPI documents and expose channels, operations, and message schemas. - [ ] Resolve local references deterministically and diagnose missing, cyclic, and external references. - [ ] Generate stable operation and channel identifiers suitable for cross-version comparison. - [ ] Produce meaningful contract diffs for endpoint, parameter, schema, response, and security changes. - [ ] Correlate matching captured HTTP artifacts without treating the specification as proof of runtime behavior. - [ ] Include malformed, deeply nested, oversized, and reference-cycle fixtures. - [ ] Verify that importing a document performs no network access. ## Out of scope - Live API discovery, endpoint fuzzing, active probing, authentication attempts, or server generation. - Claiming that a declared operation is implemented or reachable unless supported by separate runtime Evidence. ## Suggested implementation Use separate OpenAPI and AsyncAPI adapters that emit a shared normalized contract graph. Keep source-format details and diagnostics attached so comparisons remain explainable and reproducible.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#7787

No description provided.

Rows
Columns