Loads OAI specs

Loads OAI v2 API specification documents from local or remote locations.

Supports JSON and YAML documents.

Announcements

• 2025-12-19 : new community chat on discord
  • a new discord community channel is available to be notified of changes and support users

You may join the discord community by clicking the invite link on the discord badge (also above).

Status

API is stable.

Import this library in your project

go get github.com/go-openapi/loads

Basic usage

  import (
	  "github.com/go-openapi/loads"
  )

  ...

	// loads a YAML spec from a http file
	doc, err := loads.Spec(ts.URL)
  
  ...

  // retrieves the object model for the API specification
  spec := doc.Spec()

  ...

See also the provided examples.

Security

This library does not enforce a security policy of its own: it reads whatever the configured loader is allowed to read.

This is deliberate — like go-openapi/swag/loading, it is a base utility, and sanitizing or containing untrusted input is the caller‘s responsibility, just as sanitizing a file name before passing it to os.ReadFile is not that function’s job.

When a spec — its path or its $ref contents — may come from an untrusted source, confine loading explicitly (e.g. loading.WithRoot for local files and a restricted loading.WithHTTPClient for remote URLs, passed via loads.WithLoadingOptions).

For the common case, the pre-baked loads.SpecRestricted / loads.JSONSpecRestricted loaders bundle a trusted root with a network-restricted client (loads.RestrictedHTTPClient) and apply the confinement to $ref resolution as well:

doc, err := loads.SpecRestricted(path, trustedRoot)

To harden the package-level default in one call — so even callers that rely on the global loader (including cross-package $ref resolution via spec.PathLoader) are confined, with no unconfined fallback left — use loads.SetRestrictedLoaders at startup:

loads.SetRestrictedLoaders(trustedRoot)

Note that loads.AddLoader only prepends to the default chain, leaving the unconfined loader reachable; use loads.SetLoaders / loads.SetRestrictedLoaders to replace it.

See the Security section of the package documentation for the threat model and runnable examples. For the project's vulnerability reporting policy, see SECURITY.md.

Change log

See https://github.com/go-openapi/loads/releases

Licensing

This library ships under the SPDX-License-Identifier: Apache-2.0.

Other documentation

• All-time contributors
• Contributing guidelines
• Maintainers documentation
• Code style

Cutting a new release

Maintainers can cut a new release by either:

• running this workflow
• or pushing a semver tag
  • signed tags are preferred
  • The tag message is prepended to release notes