morphic

Idiomatic SDKs and docs from any API spec. One spec-agnostic IR, many targets.

Morphic is a spec-to-SDK compiler. It reads an API specification in any supported source format, lowers it into one spec-agnostic intermediate representation (IR), and generates idiomatic SDKs and documentation from that IR. The IR is the contract: a compiler's only output is an IR document, and an emitter's only input is an IR document — the two never see each other, so a new source format and a new target language are independent pieces of work.

The design goal is lossless by default. Compilers preserve source semantics — composition (allOf/oneOf/anyOf), unions, discriminators, visibility, encodings, streaming — rather than flattening them early. Lowering to what a target language can express happens late, in emitter refiners, so no target's limitations leak backward into the shared representation.

Status: early development. The ir package and the OpenAPI 3.x compiler (Milestone 1) are implemented and exercised end-to-end by the morphic compile CLI; emitters are not built yet. There is no released version — the IR schema and the CLI surface are unstable and may change between commits. The full IR capability surface is fixed from day one, so later compilers land without reshaping it.

Contents

Pipeline · Status · Install · Usage · Package layout · Design docs · Building · License

Pipeline

spec ──▶ compiler ──▶ IR ──▶ passes ──▶ IR ──▶ emitter ──▶ SDK / docs
        (spec → IR)         (IR → IR)          (IR → artifacts)

• Compilers (compilers/*) turn one source format into an IR document plus diagnostics. OpenAPI 3.x ships first; Swagger 2.0, TypeSpec, Smithy, GraphQL, AsyncAPI, Protobuf, and Erlang/OTP are planned against the same IR.
• Passes (pass/) are small, order-explicit IR → IR transforms (validate, dedup, filter, version-slice, overlay). validate — referential integrity — runs by default.
• Emitters (emitters/*, future) turn an IR document into artifacts for one target. SDK runtime policy (retry, timeout, telemetry, error taxonomy) is a separate emitter input, not part of the IR.

Every stage is a pure function f(input, options) → (output, diagnostics) with no package-level state. Stages never write to stderr or log; they return typed ir.Diagnostic values and the engine (or CLI) decides what is fatal.

Status

Install

Requires the Go release named by the go directive in go.mod, or newer. Under the default GOTOOLCHAIN=auto, an older go command from Go 1.21 on downloads that release itself.

go install github.com/dexpace/morphic/cmd/morphic@latest

Or build the CLI from a checkout:

go build -o morphic ./cmd/morphic

Usage

CLI

morphic compile lowers one OpenAPI 3.x spec into Morphic IR JSON on stdout, and writes diagnostics to stderr. Stdout is indented for reading; a file written with -o is compact, which is about half the bytes, unless --pretty asks for the indented form. morphic validate runs the same pipeline over the same spec for the diagnostics and the exit code alone, writing no IR anywhere.

morphic compile openapi.yaml                 # IR JSON to stdout
morphic compile openapi.yaml -o api.ir.json  # ...or to a file
morphic validate openapi.yaml                # diagnostics and exit code only

usage:
  morphic <command> [flags]
  morphic compile <spec-file> [flags]
  morphic validate <spec-file> [flags]

morphic, morphic help, and morphic with a help flag (-h, --help or -help) print the command list. morphic help <command> and morphic <command> --help print a command's flags. Help always prints to stdout and exits 0.

Diagnostics print one per line as <severity> <code> <location>: <message>, where <location> is <path>#<pointer> for a finding at a pointer in a spec file, <path>:<line>:<column> for one found before it had a pointer (<path>:<line> when the column is unknown), <path> alone for one about the file as a whole, the IR location bare for one an IR pass made about the document, and absent for one raised before any document existed. A spec the compiler refused produces no document to name the file from, so its locations print bare.

Both commands use the same exit codes: 0 clean (and for any help request); 1 the spec has problems — a diagnostic reached the --fail-on threshold, or it could not be lowered at all, which covers an undecodable file, an unrecognized or unsupported format, and a version no compiler claims; 2 the invocation or the filesystem was wrong — a bad flag or argument, a spec that could not be read, an output that could not be written. Nothing about the spec's own contents reaches 2.

Compiler options

--opt names an option in the vocabulary of whichever compiler recognizes the spec — morphic itself knows none of them, and an unknown name is refused by the compiler rather than ignored. The OpenAPI compiler accepts:

morphic compile openapi.yaml --opt grouping=path-prefix --opt overlay=patch.yaml

1 and 2 can both be earned by one run — a spec that reached the threshold whose -o destination then refused the write. The verdict on the spec wins, so 1 means what it says whatever -o pointed at, and 2 means the run failed for a reason outside the spec. The write error is printed on stderr either way. Note that -o publishes by rename, so a destination whose directory will not take a temp file — /dev/null, a read-only directory — cannot be written to at all.

Library

The same pipeline is available as a package. engine.New builds the default registry (OpenAPI compiler + validate pass); Run asks the registered compilers which of them recognizes the source, compiles, and runs passes. A Go caller can set compiler options as a typed value through RunOptions.FormatOptions instead of as text through RunOptions.CompilerOptions.

eng, err := engine.New()
if err != nil {
    return err
}

res, err := eng.Run(context.Background(), "openapi.yaml", engine.RunOptions{})
if err != nil {
    return err
}

for _, d := range res.Diagnostics {
    // res.Diagnostics are typed ir.Diagnostic values, not log lines.
}
doc := res.Document // *ir.Document — round-trips through JSON deterministically

Package layout

The import graph is layered and enforced by an architecture test (internal/archtest): each package may import only the packages one layer below it.

Compilers and emitters never import each other; the IR is the only thing that crosses between them. A compiler's own internal/ packages each carry their own entry rather than inheriting the compiler's, so the ordering among them is enforced too — and none may reach the compiler above it.

This table is prose; internal/archtest's rules map is the source of truth. To read the layout off the tree: git ls-files '*/*.go' | xargs -n1 dirname | sort -u.

Design docs

The design documents are normative — read them before proposing changes to the IR or pipeline.

Building

One command, and it must pass before a change lands:

make gate

That is not a summary of CI — it is what CI runs. Every check in .github/workflows/gate.yml runs a Makefile target bar lint, which the golangci-lint action runs at the version the Makefile pins, so the local command and the job are the same commands in the same order. Read the Makefile for the step list rather than a copy here; make coverage, make fuzz, make bench and the rest are individually runnable while iterating.

Run a single test with go test ./ir -run TestName. Golden IR snapshots are regenerated with the corpus test's -update flag after an intentional change.

License

Licensed under the MIT License. Copyright © 2026 dexpace.