Language-agnostic intermediate representation and type graph for the Ploidy OpenAPI compiler.

ploidy-core transforms a parsed OpenAPI document into a typed dependency graph that codegen backends traverse to emit code.

Pipeline

use ploidy_core::{arena::Arena, ir::{RawGraph, Spec}, parse::Document};

let doc = Document::from_yaml(&source)?;

let arena = Arena::new();
let spec = Spec::from_doc(&arena, &doc)?;
let mut raw = RawGraph::new(&arena, &spec);
raw.collapse_trivial_inlines();
raw.inline_tagged_variants();
raw.inline_untagged_variants();
let graph = raw.cook();

for view in graph.schemas() { /* ... */ }
for view in graph.operations() { /* ... */ }

Arena

An Arena is a bump allocator that owns all long-lived data. Types throughout the pipeline hold borrowed references to other arena-allocated types, making them cheaply copyable. Callers create an arena at the start, and pass it to each constructor.

Named vs. inline types

The IR distinguishes two kinds of types:

• Named schema types originate from components/schemas in the OpenAPI document. Each carries a SchemaTypeInfo with the schema name and additional metadata.
• Inline types are anonymous schemas nested inside other types. Each carries an InlineTypeId for identity, and a canonical path.

The two kinds carry different metadata, but share the same structural shapes: any, containers, enums, primitives, structs, tagged unions, and untagged unions.

Using the graph

A RawGraph represents types and references as they exist in the OpenAPI document. Transformations on this graph rewrite it in-place. The transformed graph is then "cooked" into a CookedGraph that's ready for codegen.

CookedGraph::schemas() yields SchemaTypeViews. Match on the variant to get the specific shape (e.g., SchemaTypeView::Struct) for generating type models.

CookedGraph::operations() yields OperationViews. Use these to access paths, methods, query parameters, and request and response types for generating client endpoints.

See the ir::views module for all view types and traversal methods.

ploidy-core

This crate is the core of the Ploidy OpenAPI compiler. It exposes structures for constructing a language-agnostic intermediate representation of an OpenAPI spec, which codegen backends then use to target different languages.

⚠️ The ploidy-core API isn't stable yet.