load

Documentation

Overview

Package load turns one source document into a parsed, reference-resolved OpenAPI document plus the identity metadata the rest of the compiler stamps into the IR.

It sits on the entry side of the pipeline: nothing below it in the compiler calls back into it, and it knows nothing about lowering. Spec problems leave as ir.Diagnostic values; the Go error return is reserved for I/O and programmer errors.

Index

• func SupportedMinor(version string) (string, bool)
• type Document
  • func Load(ctx context.Context, srcIndex int, src compilers.Source, opts Options) (*Document, []ir.Diagnostic, error)
• type Options

Functions

func SupportedMinor

func SupportedMinor(version string) (string, bool)

SupportedMinor returns the normalized major.minor prefix of an OpenAPI version string and whether the compiler supports it (3.0, 3.1, or 3.2).

Types

type Document

type Document struct {
	Doc    *soa.OpenAPI  // parsed, reference-resolved document
	Source ir.SourceInfo // format tag, path, content hash
	// Overlay attributes the positions an applied overlay is answerable for. Its
	// zero value — nothing applied — is the answer for a compile with no overlay.
	Overlay overlay.Origin
}

Document is the successful output of the load phase: a parsed, resolved speakeasy document plus the identity metadata the rest of the compiler needs. A nil *Document with error-severity diagnostics means the source is a spec problem the compiler refuses to lower (e.g. an unsupported version). The normalized "openapi" + major.minor format reaches the IR through Source.Format alone; Document does not separately carry a compilers.SourceFormat, since nothing downstream ever read one.

func Load

func Load(ctx context.Context, srcIndex int, src compilers.Source, opts Options) (*Document, []ir.Diagnostic, error)

Load parses, validates, and resolves one source document. Spec problems become ir.Diagnostic values; the Go error return is reserved for I/O and programmer errors (a hard unmarshal failure). A nil document with diagnostics signals a refusal to lower (unsupported version) without aborting the batch.

type Options

type Options struct {
	// AllowExternalRefs lets reference resolution reach outside the document —
	// off the filesystem or over the network. Off is the default, so the zero
	// value performs no I/O.
	AllowExternalRefs bool
	// Overlay is the OpenAPI Overlay document to apply to the source before the
	// model is built, or nil for none. Its bytes are the caller's to read, like
	// the source's.
	Overlay *overlay.Options
	// OverlaySrcIndex is the index the overlay document takes in Document.Sources.
	// It is read only when Overlay is set.
	OverlaySrcIndex int
	// MaxSourceBytes bounds the source document's size in bytes. Zero is
	// unbounded: the compiler's public Limits resolves its defaults and translates
	// its own spelling of "unbounded" before projecting onto this, so a budget
	// still zero here is one no caller set.
	MaxSourceBytes int
	// MaxSourceNodes bounds the YAML nodes the source parses to, counted after any
	// overlay is applied. Zero is unbounded, as in MaxSourceBytes.
	MaxSourceNodes int
	// contains filtered or unexported fields
}

Options is what Load needs from the compiler's own options. It is a separate type rather than the compiler's, because openapi.Options is public API whose shape is fixed by ir-design §10 and most of it describes lowering, which nothing here can see.