spec

package
v1.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 16, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package spec brings a specification into the process and decides what it is.

Two questions, in this order: WHERE it comes from (file, URL, stdin) and WHAT it is (OpenAPI 3, Swagger 2, GraphQL schema). No dialect answers the first, and no source answers the second — which is why both live here, away from whoever interprets the content.

Index

Constants

View Source
const InstructionsLimit = 2048

InstructionsLimit is how much of the server instructions a client keeps. Claude Code truncates them at 2KB, so anything past that is written for nobody. Put what matters first.

Variables

This section is empty.

Functions

This section is empty.

Types

type Document

type Document struct {
	Source string // where it came from, so errors can point somewhere useful
	Raw    []byte
	Kind   Kind
}

Document is the loaded specification, still raw, already knowing what it is.

func Load

func Load(ctx context.Context, source string, forced Kind) (*Document, error)

Load reads the spec from a file (`file://` or a plain path), an http(s) URL, or `-` (stdin). A non-empty `forced` beats detection — it exists for when the heuristic is wrong, so nobody is stuck with it. Load reads and identifies a specification.

See LoadWithHeaders when the specification itself sits behind authentication.

func LoadWithHeaders added in v1.14.0

func LoadWithHeaders(ctx context.Context, source string, forced Kind, headers map[string]string) (*Document, error)

LoadWithHeaders is Load with headers sent while FETCHING the specification.

They are separate from the headers sent with API CALLS on purpose. The two are not the same credential in the general case: a specification is often public while the API behind it is not, and an API that keeps its specification closed may guard it with a different key. Tying them together would send the call credential to whatever host the --spec URL points at, which is a place the operator never agreed to hand it to.

They are ignored for a local path or stdin, where there is nothing to authenticate to.

func (*Document) Instructions added in v1.8.2

func (d *Document) Instructions() string

Instructions is what the server says about itself before a single tool is loaded.

It matters more than it looks. Clients that support tool search — the default in Claude Code — load only tool NAMES and this text when the session opens; every description and every parameter schema stays deferred until the model goes looking for them. So this paragraph is what decides whether the tools are ever found at all: a server that says nothing is a server the model has no reason to search.

The text comes from the spec's own `info`, because that is where an API already describes itself — nobody should have to write it twice. A schema with no `info` (GraphQL SDL, for one) yields an empty string, and the caller falls back to whatever it wants.

type Kind

type Kind string

Kind is the specification's dialect.

const (
	KindOpenAPI Kind = "openapi" // OpenAPI 3.x or Swagger 2.0 (JSON or YAML)
	KindGraphQL Kind = "graphql" // GraphQL schema, as SDL or introspection
	// KindDiscovery is Google's own format, published for 300+ of their APIs at a predictable
	// address and understood by no OpenAPI parser.
	KindDiscovery Kind = "discovery"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL