gnostic

gnostic is a Go command-line tool from Google that compiles OpenAPI v2 and v3 descriptions, plus Google Discovery documents, into Protocol Buffer representations. Instead of working with loosely-typed JSON or YAML, tooling built on gnostic gets validated, strongly-typed data structures, with internal references resolved and errors reported up front. Compiled models can also be re-exported back to normalized JSON or YAML.

Beyond the base compiler, gnostic exposes a protoc-style plugin interface: external executables named gnostic-<name> receive a protobuf-encoded request over stdin and can implement code generation, linting, or analysis in any language. Built-in plugins cover vocabulary extraction, complexity metrics, and API summaries, and the same model feeds companion projects like gnostic-grpc and gnostic-go-generator.

What You Get

• Protocol Buffer models for OpenAPI v2, OpenAPI v3, and Google Discovery documents
• A gnostic CLI that compiles JSON/YAML API descriptions to binary or text protobuf output
• A protoc-style plugin protocol for building custom API tooling in any language
• Built-in plugins: gnostic-analyze, gnostic-vocabulary, gnostic-summary, gnostic-complexity, gnostic-linter
• Companion command-line tools: protoc-gen-openapi, protoc-gen-jsonschema, disco, report

Common Use Cases

• Type-safe API tooling - Teams building generators or linters for OpenAPI specs use gnostic’s compiled protobuf models instead of hand-rolling a JSON/YAML parser.
• Cross-language plugin pipelines - API teams write plugins in any language that speaks gnostic’s protoc-style plugin protocol to add custom validation or generation steps.
• Converting Discovery documents - Projects consuming Google Discovery Documents compile them through gnostic’s discovery package into the same typed model used for OpenAPI.
• CI-time OpenAPI validation - Projects run gnostic with --resolve-refs in CI to catch malformed descriptions or broken internal references before they reach downstream consumers.

Under The Hood

Architecture The gnostic binary (gnostic.go) is a thin wrapper that hands os.Args to lib.NewGnostic, whose ~700-line lib/gnostic.go does the real orchestration: detecting the source format (OpenAPI v2, v3, or Discovery) via getOpenAPIVersionFromInfo, invoking the matching generated reader package (openapiv2, openapiv3, discovery), and dispatching to external plugins through a pluginCall.perform step that shells out via os/exec, writing a protobuf-encoded plugins.Request to stdin and reading a plugins.Response from stdout - a protoc-style plugin architecture. All the generated reader packages lean on shared helpers in compiler/ (context.go, reader.go, helpers.go) for YAML-node unpacking, so a change to those primitives ripples through every generated format reader at once, since they all originate from the same generate-gnostic code generator.

Tech Stack Built as a Go module (go 1.24) on google.golang.org/protobuf and github.com/golang/protobuf for the protobuf runtime, google.golang.org/genproto/googleapis/{api,rpc} for well-known types, go.yaml.in/yaml/v3 for YAML parsing, and github.com/docopt/docopt-go for CLI argument parsing. The code generator (generate-gnostic) additionally pulls in golang.org/x/tools and github.com/flowstack/go-jsonschema for schema-driven generation. There’s no database or web framework here - it’s a pure CLI/compiler toolchain, built via a Makefile plus COMPILE-PROTOS.sh invoking protoc, with GitHub Actions running make all && make test on every push and pull request, and distributed as standalone binaries via go install.

Code Quality The repo carries around twenty _test.go files, including root-level gnostic_test.go, which drives the actual compiled behavior end-to-end - it invokes lib.NewGnostic with real CLI arguments and diffs the output against reference fixtures under examples/ - an integration-style approach that suits a compiler more than isolated unit tests would. Errors are handled explicitly throughout, with a dedicated UsageError type distinguishing bad CLI usage from compilation errors written to a separate error stream; no panics were found in the files reviewed. Naming and formatting follow standard Go conventions consistently. CI runs the test suite on every push and PR, but there’s no dedicated lint step (no golangci-lint or similar configuration found in the repo).

API Design gnostic’s standout ergonomic choice is reusing protoc’s own plugin convention for OpenAPI tooling: a plugin is just an executable named gnostic-<name> that reads a protobuf request from stdin and writes a protobuf response to stdout, so contributors can implement gnostic plugins in any language without linking against gnostic’s Go internals. Combined with the abundant per-directory README files throughout the repo (compiler, discovery, plugins, each cmd/* tool, each linter), the barrier to understanding any one piece in isolation is low, even though the overall project spans many generated packages.