getkin/kin-openapi: parsing, converting and validating OpenAPI in Go

What kin-openapi solves for Go services that own a spec

Most OpenAPI tooling assumes you want to generate code from a document. kin-openapi assumes the opposite: you have a document, and you want to do something with it at runtime. The README frames the project as "A Go project for handling OpenAPI files" and lists four targets, OpenAPI v2.0 (formerly Swagger), v3.0, v3.1, and v3.2 partially.

The audience is narrower than the target list suggests. This is a library for Go engineers: people writing an HTTP handler that should reject a request body that does not match the schema, people building a linter or diff tool that needs to know where in the file a field lives, people converting a legacy Swagger 2 document into OpenAPI 3. The repository layout reflects that. There are separate packages for each concern (openapi2, openapi2conv, openapi3, openapi3filter, openapi3gen), plus a cmd directory holding the validate command and a routers directory holding a gorilla/mux router for OpenAPI operations.

If you are not writing Go, nothing here applies to you. If you are writing Go but you want generated clients, kin-openapi is not the tool, and the README says so by listing oapi-codegen and goa among its dependents rather than its features.

The loader, reference resolution and the Origin mechanism

The central object is openapi3.Loader. The README's recipe is short: create a loader with openapi3.NewLoader(), then call LoadFromFile on a local JSON or YAML document. The important claim in that recipe is that the loader "resolves all references", so once loading returns, a $ref in your document has been followed and the resulting object graph is what you traverse.

A second mechanism is more interesting for tooling authors. Setting loader.IncludeOrigin = true makes the loader record the file, line and column of each element, described in the README as useful for linters, diff tools and editors that must report precise source locations. The Origin struct has three parts. Key is the location of the object itself. Fields holds the locations of scalar fields inside the object, so origin.Fields["description"] gives the line of that field. Sequences holds the locations of items in sequence-valued fields, and the README names enum, required and servers as examples, explaining that those items are scalars without their own Origin field.

One detail worth noting for anyone building on this: the README states that Origin data is populated by an internal post-processing step after YAML decoding. That means the line numbers come from the YAML layer, not from a generic tokenizer, and anything you build on top of Origin inherits that dependency.

Installing the validate command and validating your first document

There is no separate installer. kin-openapi is a Go module, github.com/getkin/kin-openapi, and the README's validate recipe runs the command straight from the module path, which fetches it without a permanent install:

go run github.com/getkin/kin-openapi/cmd/validate@latest -- <local YAML or JSON file>

The README documents four optional flags before the double dash: --defaults, --examples, --ext and --patterns. Passing --defaults makes the validator apply default values, --examples additionally validates the examples in the document, and --ext and --patterns relax or tighten specific checks. The double dash separates those flags from the file path, so the path is the last argument. On success the command produces no complaint about the document; a schema violation in the file is what produces output.

Using the library directly follows the same shape. This is the README's loading recipe:

loader := openapi3.NewLoader()
doc, err := loader.LoadFromFile("my-openapi-spec.json")

After that call, doc is an *openapi3.T you can walk. If you want source positions, set loader.IncludeOrigin = true before loading, and read doc.Info.Origin.Key.File, .Line and .Column as the README's example does (it prints "my-openapi-spec.json", 2 and 1 for its sample file).

For runtime validation rather than document validation, the openapi3filter package is the entry point: the README describes it as validating HTTP requests and responses, and as providing a gorilla/mux router for OpenAPI operations. The README does not give a full request-validation example, so read the package documentation on pkg.go.dev before wiring it into a handler.

OpenAPI 3.2 is partial, and the README is explicit about how partial

The target list is the clearest limitation in the project. OpenAPI 3.2 support covers three things: the Media Type Object's itemSchema, the Path Item Object's query field for the HTTP QUERY method, and additionalOperations for custom HTTP methods. Everything else in 3.2 is outside what the README claims.

That is a deliberate boundary rather than an accident, and it has a practical consequence: if your document leans on 3.2 features that are not those three, you cannot assume the loader understands them, and the validate command will not be checking them. The same caution applies at the other end of the range. Swagger 2 documents are handled by a separate package, openapi2, and conversion to OpenAPI 3 goes through openapi2conv, so a 2.0 document takes a different path through the library than a 3.x one.

The README is also silent on several things a production user would ask about. There is no documented rollback or migration guidance, no statement about backwards compatibility between the v0.x releases, and no error-handling section. The releases are frequent (v0.147.0, v0.148.0 and v0.149.0 all landed within August 2026), and the last push to the repository was on 2026-09-20, so the code moves. The pre-1.0 version number is the honest signal here: treat the API surface as something that can shift between minor releases and pin a version in go.mod.

kin-openapi against libopenapi and go-swagger

The README lists its own alternatives, which is more useful than a comparison written by a third party. libopenapi is described there as "a fully featured, high performance OpenAPI 3.1, 3.0 and Swagger parser, library, validator and toolkit". The overlap is large, and the difference in approach is partly about the object model: kin-openapi exposes typed Go structs (openapi3.T and its children) that you traverse directly, while libopenapi's description as a toolkit suggests a broader set of entry points around the same parsing job. If you need a low-level document model with source positions, kin-openapi's Origin mechanism is a concrete feature to weigh; if you need a wider toolkit, libopenapi is the one the README points at.

go-swagger is a different case. The README notes that it stated OpenAPI v3 will not be supported, which makes it a non-starter for 3.x documents rather than a competitor on features. swaggo has an open issue on OpenAPI v3, so it is in a similar position for 3.x work.

The dependents list is the better signal of what kin-openapi is actually for. oapi-codegen generates Go client and server boilerplate from OpenAPI 3 specifications, and it uses kin-openapi to do the parsing. goa is a design-based framework. Tufin's oasdiff is a diff tool. httptest-openapi is contract verification for net/http. In each case kin-openapi is the layer underneath, not the thing the user types.

Building from source, the Makefile, and what MIT means here

If you are working on kin-openapi itself rather than consuming it, the Makefile defines the workflow. The default goal is prepare, which runs generate, format and test in sequence. generate runs go generate ./... and then two shell scripts, maps.sh and docs.sh. format runs go fmt ./... and test runs go test ./... over the whole module.

The go.mod file pins go 1.25 and lists six direct dependencies, including github.com/gorilla/mux for the router and github.com/santhosh-tekuri/jsonschema/v6 for schema validation. That jsonschema dependency is worth knowing about if you are auditing what does the actual validation work in openapi3filter.

Licensing is MIT, held in a LICENSE file at the repository root. MIT is permissive: it allows use in closed-source products provided the copyright notice and permission notice are kept. That is a description of the licence text, not legal advice, and if you redistribute kin-openapi inside a product you should read the LICENSE file yourself rather than take this paragraph as clearance. The README also links to a sponsorship page for the maintainer, which is a funding request, not a licensing term.

Editorial conclusion

Adopt kin-openapi if you already write Go services and want to load a spec, resolve its references and validate incoming requests and outgoing responses with openapi3filter. Do not adopt it if your main goal is generating Go clients or servers from a spec: the README points to oapi-codegen and goa instead, and kin-openapi's own openapi3gen goes the other direction, from Go types to schemas. Before committing, run the validate command against your own document with --defaults and --examples, since those flags change what counts as a valid document, and check whether your spec uses OpenAPI 3.2 features beyond itemSchema and the QUERY method, which the README lists as only partially supported.

Frequently asked questions

Official sources

1. getkin/kin-openapi on GitHub
2. Issues
3. License: MIT
4. README
5. Releases