Documentation
¶
Overview ¶
Package openapi lowers OpenAPI 3.0/3.1/3.2 documents into the Morphic IR. It implements compilers.Compiler.
This package is the compiler's public face and the assembly behind it: the Compiler, its Options and the text vocabulary DecodeOptions reads, and the run that calls the lowerings in order and builds a Document from what they return.
Parsing is delegated to github.com/speakeasy-api/openapi. Recognizing a source from its bytes, loading it and the lowering itself (identity, hoisting, normalization, and lossless preservation of constructs the IR does not model structurally) live in the packages under internal/, each of which states its own place in the order.
Index ¶
- Constants
- func DefaultBinaryMediaTypes() []string
- func DefaultExtensionPromotions() map[ExtensionTarget][]ExtensionSource
- func DefaultStreamingMediaTypes() []string
- type BinaryInference
- type Compiler
- func (c *Compiler) Compile(ctx context.Context, sources []compilers.Source, opts compilers.Options) (*ir.Document, []ir.Diagnostic, error)
- func (*Compiler) DecodeOptions(set compilers.OptionSet) (any, error)
- func (*Compiler) Detect(ctx context.Context, src compilers.Source, opts compilers.Options) (compilers.Recognition, []ir.Diagnostic, bool)
- func (*Compiler) Formats() []compilers.SourceFormat
- func (*Compiler) SourceLimit(opts compilers.Options) int
- func (*Compiler) SourceTable(sources []compilers.Source, opts compilers.Options) []ir.SourceInfo
- type DiscriminatorInference
- type ExtensionLists
- type ExtensionPromotions
- type ExtensionSource
- type ExtensionTarget
- type GroupingExtension
- type GroupingStrategy
- type HTTPDateInference
- type IdempotencyInference
- type Limits
- type Location
- type NullableInference
- type Options
- type Overlay
- type PaginationInference
- type ReplacementInference
- type SecretInference
- type StreamingInference
- type TitleNames
Constants ¶
const ( // GroupByTags groups operations by their first OpenAPI tag (default). GroupByTags = lowering.GroupByTags // GroupByPathPrefix groups operations by the first path segment. GroupByPathPrefix = lowering.GroupByPathPrefix // GroupByExtension groups operations by the group path a vendor extension // states, nesting a group for each segment, and an operation stating none by // GroupingExtension.Fallback. GroupByExtension = lowering.GroupByExtension )
Grouping strategies.
const ( // ListsAreSegments reads a list as one path, each entry adding its segments. ListsAreSegments = lowering.ListsAreSegments // ListsAreGroups reads a list as several paths, filing the operation under // the first and making a group for each of the rest. ListsAreGroups = lowering.ListsAreGroups )
The readings of a list value.
const ( // TargetDeprecation states that what a key sits on is deprecated. TargetDeprecation = lowering.TargetDeprecation // TargetDeprecationMessage fills ir.Deprecation.Message. TargetDeprecationMessage = lowering.TargetDeprecationMessage // TargetDeprecationSince fills ir.Deprecation.Since. TargetDeprecationSince = lowering.TargetDeprecationSince // TargetDeprecationRemovalVersion fills ir.Deprecation.RemovalVersion. TargetDeprecationRemovalVersion = lowering.TargetDeprecationRemovalVersion // TargetDeprecationRemovalDate fills ir.Deprecation.RemovalDate. TargetDeprecationRemovalDate = lowering.TargetDeprecationRemovalDate // TargetDeprecationReplacedBy fills ir.Deprecation.ReplacedBy. TargetDeprecationReplacedBy = lowering.TargetDeprecationReplacedBy // TargetEnumOpen clears ir.Enum.Closed, or ir.Union.Closed on the union a // mixed enum lowers to. TargetEnumOpen = lowering.TargetEnumOpen // TargetUnionOpen clears ir.Union.Closed on a union a oneOf or anyOf lowers // to. TargetUnionOpen = lowering.TargetUnionOpen // TargetStability fills ir.Operation.Stability. TargetStability = lowering.TargetStability // TargetRedaction asks for a value to be redacted. TargetRedaction = lowering.TargetRedaction // TargetAllowReserved sets ir.HTTPParamBinding.AllowReserved on a parameter // writing no allowReserved. TargetAllowReserved = lowering.TargetAllowReserved // TargetServerName names an ir.Server the document names in no other way. TargetServerName = lowering.TargetServerName // TargetTokenEndpointAuthMethods fills // ir.OAuthFlow.TokenEndpointAuthMethods. TargetTokenEndpointAuthMethods = lowering.TargetTokenEndpointAuthMethods // TargetPaginationCursor fills the InputCursor of a cursor ir.Pagination. TargetPaginationCursor = lowering.TargetPaginationCursor // TargetPaginationOffset fills the InputCursor of an offset ir.Pagination. TargetPaginationOffset = lowering.TargetPaginationOffset // TargetPaginationPage fills the InputCursor of a page ir.Pagination. TargetPaginationPage = lowering.TargetPaginationPage // TargetPaginationLimit fills ir.Pagination.InputLimit. TargetPaginationLimit = lowering.TargetPaginationLimit // TargetPaginationItems fills ir.Pagination.Items. TargetPaginationItems = lowering.TargetPaginationItems // TargetPaginationNextCursor fills ir.Pagination.NextCursor. TargetPaginationNextCursor = lowering.TargetPaginationNextCursor // TargetPaginationHasMore fills ir.Pagination.HasMore, and the stop // ir.PageStopNoMore beside it. TargetPaginationHasMore = lowering.TargetPaginationHasMore // TargetPaginationNextLink fills ir.Pagination.NextLink. TargetPaginationNextLink = lowering.TargetPaginationNextLink // TargetPaginationTotalCount fills ir.Pagination.TotalCount. TargetPaginationTotalCount = lowering.TargetPaginationTotalCount // TargetPaginationTotalPages fills ir.Pagination.TotalPages. TargetPaginationTotalPages = lowering.TargetPaginationTotalPages // TargetStreamTerminator fills ir.StreamDetail.Terminator, from a key on a // streaming content of a success response or on the operation. TargetStreamTerminator = lowering.TargetStreamTerminator // TargetStreamCondition fills ir.StreamDetail.Condition, from a key on the // operation naming an input of its request. TargetStreamCondition = lowering.TargetStreamCondition // TargetParamChoices fills ir.Operation.ParamChoices, from a key on the // operation naming alternatives among its parameters. TargetParamChoices = lowering.TargetParamChoices )
The typed fields promotion can fill today.
const ( // DefaultMaxSourceBytes is the byte budget: 64 MiB, a 5.2x margin over the // largest measured description. It is the only budget enforceable before a // YAML source is parsed, which is why it is the loosest — it exists to bound // that parse, and everything finer is measured after it. A JSON text is // held to the node budget as it is read. DefaultMaxSourceBytes = 1 << 26 // DefaultMaxSourceNodes is the parsed-node budget: 2,097,152, a 4.4x margin // over the largest measured description. Node count, not byte count, is what // the phases after the parse cost — building the typed model and resolving // its references peaked at 1.5 GB of RSS for GitHub's 471,735 nodes — so this // is the budget that bounds a compile, and the byte budget above is only what // gets a document far enough to be counted. DefaultMaxSourceNodes = 1 << 21 // DefaultMaxEnumMembers is the per-enum member budget: 65,536, a 109x margin // over the largest measured enum and roughly 7x the largest registry an API // might reasonably inline (IATA airport codes, BCP-47 language subtags, both // under 10,000 entries). // // An enum's IR cost per source node is disproportionate: every member becomes // an ir.EnumMember, and a heterogeneous enum adds a hoisted Literal type and a // union variant per member. One 1,000,000-member enum turned 10 MB of source // into 2.6 GB of peak RSS while well inside the node budget above (GitHub #75). // An enum at this budget compiles in under 200 MB. DefaultMaxEnumMembers = 1 << 16 // DefaultMaxAliasSurplus is the alias budget: 262,144 nodes that YAML // aliases may add to a document beyond its own. The three descriptions // above barely alias, so it is measured against 1,693 real OpenAPI and // Swagger specs, those three among them and 199 chosen for their anchors, // whose largest surplus is 15,727 nodes: a 16.7x margin. // // It bounds the memory an alias-heavy document can cost, since the parser // builds a fresh subtree for every path through an alias // (docs/parser-library.md#alias-expansion), and, unlike a relative bound, // padding cannot lift it: at 1<<20 a purpose-built 93 KiB document peaked // at 4.4 GiB; at this default the largest one accepted peaks at 1.65 GiB. DefaultMaxAliasSurplus = 1 << 18 // DefaultMaxExternalDocuments is the document budget: 16,384, a 4.7x margin // over the 3,476 files the $refs of DigitalOcean's public API description // reach, counted 2026-10-18, the largest split description found. The three // above are single files, and a description split per resource or per // schema is what reading external documents is for. DefaultMaxExternalDocuments = 1 << 14 // DefaultMaxReferenceExpansion is the reference-expansion budget: // 16,777,216, a 4.3x margin over the 3,919,648 that the $refs of Microsoft // Graph's description of its generally available API copy, the most of the // descriptions the source budgets admit, measured 2026-11-04. Its beta // API's, past those budgets, copies 6,614,806, GitHub's REST API // description 3,121,777, Cloudflare's 270,530, and none of 1,840 others // more than 2,216,018. The costliest document built to spend it, a response // of inline headers, peaks near 5.6 GB writing its IR to standard output, // about what Microsoft Graph's description costs there (5.8 GB). DefaultMaxReferenceExpansion = 1 << 24 )
Compiled-in defaults for Limits, each calibrated against measured documents rather than chosen round. The measurements are of three flagship public descriptions, taken 2026-08-09: GitHub's REST API (12,920,264 bytes, 471,735 parsed YAML nodes, largest enum 53 members), Stripe's (7,967,776 bytes, 265,846 nodes, largest enum 599 members) and Kubernetes' aggregated Swagger (4,475,339 bytes, 138,990 nodes, no enum at all).
const DiscriminatorInferenceHeuristic = lowering.DiscriminatorInferenceHeuristic
DiscriminatorInferenceHeuristic is the name a union's Provenance.Inferred carries where the discriminator-inference policy filled its discriminator, and a subtype's where it read its tag.
const HTTPDateInferenceHeuristic = lowering.HTTPDateInferenceHeuristic
HTTPDateInferenceHeuristic is the name a header's Provenance.Inferred carries where the HTTP-date policy set its Encoding.
const IdempotencyInferenceHeuristic = lowering.IdempotencyInferenceHeuristic
IdempotencyInferenceHeuristic is the name an operation's Provenance.Inferred carries where the idempotency policy read its token.
const NullableInferenceHeuristic = lowering.NullableInferenceHeuristic
NullableInferenceHeuristic is the name ir.TypeRef.Inferred carries on a reference whose null the nullable-inference policy read in.
const PaginationInferenceHeuristic = lowering.PaginationInferenceHeuristic
PaginationInferenceHeuristic is the name an operation's Provenance.Inferred carries where the pagination-inference policy filled its Pagination.
const ReplacementInferenceHeuristic = lowering.ReplacementInferenceHeuristic
ReplacementInferenceHeuristic is the name a deprecated node's Provenance.Inferred carries where the replacement policy read its replacements out of the message.
const SecretInferenceHeuristic = lowering.SecretInferenceHeuristic
SecretInferenceHeuristic is the name a parameter's, a header's or a property's Provenance.Inferred carries where the secret policy set its Secret.
Variables ¶
This section is empty.
Functions ¶
func DefaultBinaryMediaTypes ¶
func DefaultBinaryMediaTypes() []string
DefaultBinaryMediaTypes returns the media types BinaryInference classifies as binary when the caller names none, for the reason DefaultStreamingMediaTypes is exported.
func DefaultExtensionPromotions ¶
func DefaultExtensionPromotions() map[ExtensionTarget][]ExtensionSource
DefaultExtensionPromotions returns the extension-to-field mapping applied when the caller names none. It is exported so a caller changing the mapping can start from it rather than transcribe it.
func DefaultStreamingMediaTypes ¶
func DefaultStreamingMediaTypes() []string
DefaultStreamingMediaTypes returns the media types and suffixes StreamingInference classifies as streams when the caller names none. It is exported so a caller extending the list can start from it rather than transcribe it.
Types ¶
type BinaryInference ¶
type BinaryInference = lowering.BinaryInference
BinaryInference is the binary media-type policy: which media types mean a body or part is a file when its schema says nothing more than that it is a string. It is another injectable-policy seam (architecture principle 6), named here for the reason GroupingStrategy is.
type Compiler ¶
type Compiler struct{}
Compiler lowers OpenAPI 3.x documents into the IR.
func (*Compiler) Compile ¶
func (c *Compiler) Compile(ctx context.Context, sources []compilers.Source, opts compilers.Options) (*ir.Document, []ir.Diagnostic, error)
Compile implements compilers.Compiler. Milestone 1 accepts exactly one root source; multi-document stitching belongs to the link pass.
func (*Compiler) DecodeOptions ¶
DecodeOptions implements compilers.Compiler: it turns textual settings into an Options value. Settings are read in sorted order so that a set with two bad values always reports the same one. An overlay is named, not read: the compile reads it.
func (*Compiler) Detect ¶
func (*Compiler) Detect(ctx context.Context, src compilers.Source, opts compilers.Options) (compilers.Recognition, []ir.Diagnostic, bool)
Detect implements compilers.Compiler. It reports the dialect src declares by its version's major.minor prefix, naming swagger@2.0 too, which it does not serve, so the caller can say unsupported rather than unreadable. The path is not consulted.
It parses all of src, handing Compile the parse in Recognition.Parsed. Three sources are declined with an error whatever their format: one past SourceLimit or the node budget, with Compile's refusal, and one whose root merges deeper than detection reads, its own keys leaving the version open. Any other decline is silent unless src declares a version under a discriminating key and is unreadable.
func (*Compiler) Formats ¶
func (*Compiler) Formats() []compilers.SourceFormat
Formats reports the OpenAPI dialects this compiler accepts.
func (*Compiler) SourceLimit ¶
SourceLimit implements compilers.Compiler: the byte budget, Limits.MaxSourceBytes, of the options opts would compile with, spelled as the contract spells one (load.ReadLimit).
func (*Compiler) SourceTable ¶
SourceTable implements compilers.Compiler: the source at rootSrcIndex, then the overlay at overlaySrcIndex when the options name one. Compile takes exactly one source, so the two indexes are the ones every provenance this compiler builds uses.
The overlay is listed whenever it is named, not only when it applied: a compile it refused reports at its index, and that refusal is the case this table exists for.
type DiscriminatorInference ¶
type DiscriminatorInference = lowering.DiscriminatorInference
DiscriminatorInference is the discriminator-inference policy: whether a union's tags are read off the strings each variant pins its tag property to, where the document declares no mapping or no discriminator, and a subtype's off the strings it admits, where it is routed by name. It is another injectable-policy seam (architecture principle 6), and is named here rather than restated for the reason GroupingStrategy is.
type ExtensionLists ¶
type ExtensionLists = lowering.ExtensionLists
ExtensionLists is what a list value of a grouping extension means.
type ExtensionPromotions ¶
type ExtensionPromotions = lowering.ExtensionPromotions
ExtensionPromotions is the vendor-extension promotion policy: which x-* keys are read into which typed IR field. It is another injectable-policy seam (architecture principle 6), and is named here rather than restated for the reason GroupingStrategy is.
type ExtensionSource ¶
type ExtensionSource = lowering.ExtensionSource
ExtensionSource is one place a policy reads a fact from: an extension key, and the member of its object value where it holds several facts.
type ExtensionTarget ¶
type ExtensionTarget = lowering.ExtensionTarget
ExtensionTarget names one typed IR field a promoted extension fills.
type GroupingExtension ¶
type GroupingExtension = lowering.GroupingExtension
GroupingExtension is what GroupByExtension reads: which extension states an operation's group path, what a list there means, and how an operation stating none is grouped. It is named here for the reason GroupingStrategy is.
func DefaultGroupingExtension ¶
func DefaultGroupingExtension() GroupingExtension
DefaultGroupingExtension returns the extension GroupByExtension reads where the caller names none. It is exported so a caller can start from it.
type GroupingStrategy ¶
type GroupingStrategy = lowering.GroupingStrategy
GroupingStrategy selects how operations are grouped into OperationGroups. It is the injectable-policy seam (architecture principle 6): grouping is inferred policy, not source semantics, and can be switched or disabled.
The vocabulary is declared once, beneath both walks, and named here rather than restated: two declarations of one strategy set can drift, and a strategy only the public half knew would fall through to the default unreported.
type HTTPDateInference ¶
type HTTPDateInference = lowering.HTTPDateInference
HTTPDateInference is the HTTP-date policy: whether a response header whose field an RFC defines as an HTTP-date, and whose schema declares a date-time with no encoding, is written and read as an HTTP-date. It is another injectable-policy seam (architecture principle 6), named here for the reason GroupingStrategy is.
type IdempotencyInference ¶
type IdempotencyInference = lowering.IdempotencyInference
IdempotencyInference is the idempotency policy: whether an operation declaring an `Idempotency-Key` header parameter, and no idempotency, takes it as its idempotency token. It is another injectable-policy seam (architecture principle 6), named here for the reason GroupingStrategy is.
type Limits ¶
type Limits struct {
// MaxSourceBytes bounds one source document's size in bytes, checked before
// it is parsed; it is the compiler's SourceLimit, so a caller reads a source
// no further than it allows. It binds the same way on an overlay and on a
// document an external reference names, each read no further.
MaxSourceBytes int `json:"maxSourceBytes,omitzero"`
// MaxSourceNodes bounds the nodes one document holds as it is read: the
// source, the overlay and each document an external reference names, a
// JSON text read no further than the first node past it and a YAML text
// counted once parsed, before the typed model or the resolver builds from
// it. It also bounds the tree an overlay leaves: an action that would build
// past it is refused before it builds anything, so no overlay lifts a
// source past it. What references reach in an external document is
// validated within this budget plus MaxAliasSurplus.
MaxSourceNodes int `json:"maxSourceNodes,omitzero"`
// MaxEnumMembers bounds the members of a single enum. An enum past it lowers
// as the top type with an error diagnostic naming the budget; the rest of the
// document still lowers.
MaxEnumMembers int `json:"maxEnumMembers,omitzero"`
// MaxAliasSurplus bounds the nodes YAML aliases may add to a source
// document or its overlay: its cost with every alias expanded
// (docs/parser-library.md#alias-expansion), less its cost as written. A
// source past it is refused before the model is built, an overlay before it
// is applied, an external document before the resolver builds from it.
//
// Turning it off leaves alias refusal on: a document expanding past both
// 128 times its own size and 32,768 nodes is refused anyway, as
// openapi/alias-amplification, not openapi/budget-exceeded, so only
// expansion up to the larger of the two goes unchecked. A document without
// aliases adds nothing.
MaxAliasSurplus int `json:"maxAliasSurplus,omitzero"`
// MaxExternalDocuments bounds the documents external references read in one
// compile: each file and each URL, read once however many references name
// it. A document past it is not read, each reference into it is reported
// unresolved, and the compile reports openapi/budget-exceeded once. It
// bounds how many documents are read, not their size, which MaxSourceBytes
// and MaxSourceNodes bound one at a time
// (docs/compilers/openapi.md#source-budgets).
MaxExternalDocuments int `json:"maxExternalDocuments,omitzero"`
// MaxReferenceExpansion bounds what lowering copies through $refs and path
// items. A declaration a $ref names, a schema aside, lowers again at every
// $ref naming it, so each is charged what its chain's declarations weigh,
// each component alias included: one for each YAML node, a YAML alias as a
// copy of what it names, and one for each byte of scalar text, but one for a
// schema, which lowers once. Each additionalOperations entry is charged its
// copy of what its path item declares. A document past it is refused as
// openapi/budget-exceeded, compiling to no Document.
MaxReferenceExpansion int `json:"maxReferenceExpansion,omitzero"`
}
Limits bounds the size and cardinality of one compile, so a legal but pathologically large input is refused with a diagnostic rather than left to exhaust the host (GitHub #75).
It is policy, not semantics (architecture principle 6): what counts as pathological depends on the machine, so each budget is the caller's. Zero takes the documented default and a negative value means unbounded, except where a field says a constant beside its budget still applies.
Other bounds, such as schema nesting depth, are constants beside the code that walks them: no caller could legitimately want more.
type Location ¶
Location maps the documents a URI prefix names to where their bytes are: the URI Prefix + rest is read at Location + rest. Prefix is an absolute URI ending in "/", with no query or fragment. Location is a directory, a relative one read against the source's, or an http(s) URL ending in "/".
type NullableInference ¶
type NullableInference = lowering.NullableInference
NullableInference is the nullable-inference policy: whether a null a schema spells, by `nullable: true` or beside a $ref, widens what it is written on. It is another injectable-policy seam (architecture principle 6), and is named here rather than restated for the reason GroupingStrategy is.
type Options ¶
type Options struct {
// Grouping selects the operation-grouping strategy.
Grouping GroupingStrategy `json:"grouping,omitempty"`
// GroupingExtension is what GroupByExtension reads, set as text by the
// options grouping-key, grouping-lists, grouping-aliases and
// grouping-fallback, and refused with any other strategy. Naming neither Key
// nor Lists reads DefaultGroupingExtension's, its Aliases unless the caller
// names one, and naming one without the other is refused, since conventions
// disagree on a list. Fallback defaults to GroupByTags.
GroupingExtension GroupingExtension `json:"groupingExtension,omitzero"`
// StreamingInference selects which media types imply a stream. The zero value is
// the default list, on; a caller who wants only what a document declares
// disables it.
StreamingInference StreamingInference `json:"streamingInference"`
// BinaryInference selects which media types make a file of a body or part whose
// schema says no more than that it is a string. The zero value is the
// default list, on; a caller who wants only what a document declares
// disables it.
BinaryInference BinaryInference `json:"binaryInference"`
// Promotions selects which vendor extensions are read into typed IR fields.
// The zero value is the default mapping, on; a caller who wants extensions
// kept verbatim and nothing more disables it.
Promotions ExtensionPromotions `json:"promotions"`
// NullableInference selects whether a null a schema spells widens what it is
// written on, a reference it decides marked as inferred. The zero value is
// on; a caller who wants only what the document's version says disables it.
NullableInference NullableInference `json:"nullableInference"`
// DiscriminatorInference selects whether a union's tags are read off the
// strings each variant pins its tag property to, where the document
// declares no mapping or no discriminator, and a subtype's routed by name
// off the strings it admits, what it reads marked as inferred. The zero value is on;
// a caller who wants only what the document declares disables it.
DiscriminatorInference DiscriminatorInference `json:"discriminatorInference"`
// IdempotencyInference selects whether an operation declaring an
// `Idempotency-Key` header parameter, and no idempotency, takes it as its
// idempotency token, marked as inferred. The zero value is on; a caller who
// wants only what the document declares disables it.
IdempotencyInference IdempotencyInference `json:"idempotencyInference"`
// SecretInference selects whether a parameter, a header or a property whose
// name says it holds a credential is redacted, marked as inferred. The zero
// value is on; a caller who wants only the redaction the document asks for
// disables it.
SecretInference SecretInference `json:"secretInference"`
// HTTPDateInference selects whether a date-time response header whose field
// an RFC defines as an HTTP-date is written and read as one, marked as
// inferred. The zero value is on; a caller who wants the text the format
// names disables it.
HTTPDateInference HTTPDateInference `json:"httpDateInference"`
// ReplacementInference selects whether a deprecation whose message names
// what to use instead names it in ReplacedBy too, marked as inferred. The
// zero value is on; a caller who wants the replacement left in the message
// disables it.
ReplacementInference ReplacementInference `json:"replacementInference"`
// PaginationInference selects whether an operation's pagination is read off
// the names of its query parameters and of its success responses' members,
// what it reads marked as inferred. The zero value is on; a caller who wants
// only what the document declares disables it.
PaginationInference PaginationInference `json:"paginationInference"`
// TitleNames selects whether a schema's title names the anonymous node
// built from it, its title its summary either way. The zero value is on; a
// caller who wants every such node named by its position disables it.
TitleNames TitleNames `json:"titleNames"`
// AllowExternalRefs lets a read of another document leave the directory the
// source lies in (Source.Location, else Source.Path) for any file and
// http(s) URLs. Off by default, since a spec is untrusted: reads stay
// inside that directory, symbolic links included, and follow relative
// references alone. On or off, a reference in a document read over
// http(s) reads only http(s) URLs.
//
// Reads go through compilers.Options.Reader; with none, nothing is read.
// Each document read is a Document.Sources entry, and what it declares is
// lowered there. One past the source's budgets or pre-parse refusals fails
// each reference naming it.
AllowExternalRefs bool `json:"allowExternalRefs"`
// Locations maps where the documents named under a URI prefix are read
// from, as the caller writes it: nothing is mapped unless it is written
// here. Each is applied where a document is opened, before any read judges
// it, and never to an $id or a $self, which keeps the URI it writes
// (docs/compilers/openapi.md#references).
Locations []Location `json:"locations,omitempty"`
// Overlay is an OpenAPI Overlay document to apply to the source before
// lowering, or nil for none. It is the source-document patching hook
// architecture §2.2 names, and is deliberately not the IR overlay pass beside
// it: a fix that has to land before naming and hoisting heuristics read the
// broken shape cannot be made afterwards.
Overlay *Overlay `json:"overlay,omitzero"`
// Limits bounds how large an input this compile will lower. The zero value
// takes every default.
Limits Limits `json:"limits"`
}
Options configures the OpenAPI compiler. It is the concrete type this compiler expects in compilers.Options.FormatOptions; the zero value is valid and normalized by withDefaults.
It stays whole here while each phase below takes its own input projected from it — load.Options, and the strategy the lowering context carries. Its shape is a published contract, since a caller outside this package constructs this exact type by field, and most of it describes work no single phase does.
type Overlay ¶
type Overlay struct {
// Path names the overlay document, and is recorded as its SourceInfo path.
// With empty Data, it is the local file Compile reads through
// compilers.Options.Reader; an empty path or an http(s) URL is refused.
Path string `json:"path,omitempty"`
// Data is the overlay document's bytes, or empty to read the one Path
// names: no overlay document is empty.
Data []byte `json:"data,omitempty"`
// Lax turns off strict application.
//
// Strict — the zero value — is the default because an action whose selector
// matches nothing is nearly always a typo in a JSONPath, and an overlay that
// silently does nothing ships an SDK missing the very fix it was written to
// make. Under strict such an action refuses the compile; under lax it is
// reported as a warning, and the rest of the overlay applies.
Lax bool `json:"lax,omitzero"`
}
Overlay is one OpenAPI Overlay document and how strictly to apply it.
The document arrives as bytes, or is read through compilers.Options.Reader, as every document beyond the source is, within the source's byte budget. A programmatic caller sets this through engine.RunOptions.FormatOptions; a caller with only text names the file with the "overlay" setting.
An applied overlay becomes a second entry in Document.Sources, and every position it introduced or rewrote names that entry as its Provenance.Source. Positions it left alone keep the source's line and column, since the overlay applies to the parsed tree, not to re-serialised bytes.
type PaginationInference ¶
type PaginationInference = lowering.PaginationInference
PaginationInference is the pagination-inference policy: whether an operation's pagination is read off the names of its query parameters and of its success responses' members. It is another injectable-policy seam (architecture principle 6), and is named here rather than restated for the reason GroupingStrategy is.
type ReplacementInference ¶
type ReplacementInference = lowering.ReplacementInference
ReplacementInference is the replacement policy: whether a deprecation whose message names what to use instead, in a form the document's entities resolve, names it in ReplacedBy too. It is another injectable-policy seam (architecture principle 6), named here for the reason GroupingStrategy is.
type SecretInference ¶
type SecretInference = lowering.SecretInference
SecretInference is the secret policy: whether a parameter, a header or a property whose name says it holds a credential, and whose value is text, is redacted where the document asks for no redaction. It is another injectable-policy seam (architecture principle 6), named here for the reason GroupingStrategy is.
type StreamingInference ¶
type StreamingInference = lowering.StreamingInference
StreamingInference is the media-type streaming policy: which media types imply that a body is a sequence of frames when the document declares nothing that says so. It is another injectable-policy seam (architecture principle 6), and it is named here rather than restated for the reason GroupingStrategy is.
type TitleNames ¶
type TitleNames = lowering.TitleNames
TitleNames is the title-names policy: whether a schema's title names the anonymous node built from it, in place of the hint its position composes. It is another injectable-policy seam (architecture principle 6), and is named here rather than restated for the reason GroupingStrategy is.
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
annotation
Package annotation reads the documentation-adjacent facts a schema or a carrier declares — descriptions, deprecation, redaction, visibility, XML hints, extensions — and the validation-only JSON Schema keywords the IR keeps verbatim rather than models.
|
Package annotation reads the documentation-adjacent facts a schema or a carrier declares — descriptions, deprecation, redaction, visibility, XML hints, extensions — and the validation-only JSON Schema keywords the IR keeps verbatim rather than models. |
|
auth
Package auth lowers what a document says about authentication: the security schemes it declares, and the requirements that name them.
|
Package auth lowers what a document says about authentication: the security schemes it declares, and the requirements that name them. |
|
bind
Package bind resolves every $ref of an OpenAPI source, a schema's and a Reference Object's, into an immutable table, over the decoded YAML trees and never through the parser's resolver: for each reference, where its own $ref lands and where its chain ends, or why it does not.
|
Package bind resolves every $ref of an OpenAPI source, a schema's and a Reference Object's, into an immutable table, over the decoded YAML trees and never through the parser's resolver: for each reference, where its own $ref lands and where its chain ends, or why it does not. |
|
bind/typed
Package typed answers what the lowering asks of a bind table about the typed schemas it holds: where a schema's $ref lands, the schema written there and the one its chain ends on.
|
Package typed answers what the lowering asks of a bind table about the typed schemas it holds: where a schema's $ref lands, the schema written there and the one its chain ends on. |
|
budget
Package budget counts the work and the size of a compile against their limits.
|
Package budget counts the work and the size of a compile against their limits. |
|
canary
Package canary pins the parser library behaviours docs/parser-library.md records, one test for each entry.
|
Package canary pins the parser library behaviours docs/parser-library.md records, one test for each entry. |
|
convention
Package convention fills the facts an OpenAPI document implies by the names it gives its fields rather than declares: an operation's idempotency token, by the header the key travels in; a credential's redaction, by what it is called; and a response header's HTTP-date text, by the field it is.
|
Package convention fills the facts an OpenAPI document implies by the names it gives its fields rather than declares: an operation's idempotency token, by the header the key travels in; a credential's redaction, by what it is called; and a response header's HTTP-date text, by the field it is. |
|
detect
Package detect recognizes an OpenAPI or Swagger document from its bytes: the discriminating key it writes and the version beside it, read off the parse the compile goes on to lower.
|
Package detect recognizes an OpenAPI or Swagger document from its bytes: the discriminating key it writes and the version beside it, read off the parse the compile goes on to lower. |
|
diag
Package diag holds the OpenAPI compiler's diagnostic vocabulary: the stable codes it reports under, the single constructor that builds a diagnostic from them, and how one quotes a dependency's error or panic.
|
Package diag holds the OpenAPI compiler's diagnostic vocabulary: the stable codes it reports under, the single constructor that builds a diagnostic from them, and how one quotes a dependency's error or panic. |
|
doctree
Package doctree reads an input's bytes, the source's, an overlay's or a document a reference names, into the YAML parser's tree of its first document that holds content, held to the node budget as it is read.
|
Package doctree reads an input's bytes, the source's, an overlay's or a document a reference names, into the YAML parser's tree of its first document that holds content, held to the node budget as it is read. |
|
document
Package document lowers what a document says about itself rather than its types or operations: its info and root externalDocs, and, kept verbatim, what the objects around them write that lowers to no node (docs/compilers/openapi.md#document-metadata, docs/compilers/openapi.md#unreferenced-components).
|
Package document lowers what a document says about itself rather than its types or operations: its info and root externalDocs, and, kept verbatim, what the objects around them write that lowers to no node (docs/compilers/openapi.md#document-metadata, docs/compilers/openapi.md#unreferenced-components). |
|
fragment
Package fragment is the one place the compiler reads a $ref fragment as a JSON pointer (GitHub #911), and tells an absolute reference, which no base moves, from a relative one.
|
Package fragment is the one place the compiler reads a $ref fragment as a JSON pointer (GitHub #911), and tells an absolute reference, which no base moves, from a relative one. |
|
ids
Package ids builds the RFC 6901 pointer that names a position — a jsontext.Pointer from construction on, read back through its methods, never split on '/' — and derives IR identifiers and namespaces from it.
|
Package ids builds the RFC 6901 pointer that names a position — a jsontext.Pointer from construction on, read back through its methods, never split on '/' — and derives IR identifiers and namespaces from it. |
|
jsonpath
Package jsonpath evaluates RFC 9535 queries over the JSON value a YAML tree stands for: an alias reads as the node it names, a `<<` merge key's members as members of the mapping merging them, and a scalar as the compiler reads it.
|
Package jsonpath evaluates RFC 9535 queries over the JSON value a YAML tree stands for: an alias reads as the node it names, a `<<` merge key's members as members of the mapping merging them, and a scalar as the compiler reads it. |
|
load
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.
|
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. |
|
lowering
Package lowering holds the context every OpenAPI lowering reads.
|
Package lowering holds the context every OpenAPI lowering reads. |
|
lowering/loweringtest
Package loweringtest builds the lowering context the compiler's tests lower under, over a document the load phase read, as the compiler builds its own.
|
Package loweringtest builds the lowering context the compiler's tests lower under, over a document the load phase read, as the compiler builds its own. |
|
merge
Package merge reconciles the properties more than one allOf branch declares: folding the declarations into one, composing the models they name, or reporting that they disagree.
|
Package merge reconciles the properties more than one allOf branch declares: folding the declarations into one, composing the models they name, or reporting that they disagree. |
|
naming
Package naming names every node the OpenAPI compiler builds as a function of the documents and the node's coordinate (GitHub #981), so which lowering reaches a coordinate first cannot change what it is called.
|
Package naming names every node the OpenAPI compiler builds as a function of the documents and the node's coordinate (GitHub #981), so which lowering reaches a coordinate first cannot change what it is called. |
|
nodeview
Package nodeview is the compiler's one reading of a raw YAML tree: a mapping read the way the parser reads it, through aliases and `<<` merge keys, each key and each key written twice settled as the parser's model settles them (docs/parser-library.md#merge-keys, #duplicate-key, #non-scalar-key), and one bounded, iterative walk of a tree as written (Walk).
|
Package nodeview is the compiler's one reading of a raw YAML tree: a mapping read the way the parser reads it, through aliases and `<<` merge keys, each key and each key written twice settled as the parser's model settles them (docs/parser-library.md#merge-keys, #duplicate-key, #non-scalar-key), and one bounded, iterative walk of a tree as written (Walk). |
|
oas
Package oas holds the OpenAPI Specification's rules as data, and the engine that checks a source tree against them at the minor it declares.
|
Package oas holds the OpenAPI Specification's rules as data, and the engine that checks a source tree against them at the minor it declares. |
|
openapitest
Package openapitest holds the test scaffolding every test package under compilers/openapi would otherwise copy, since test files cannot share unexported helpers.
|
Package openapitest holds the test scaffolding every test package under compilers/openapi would otherwise copy, since test files cannot share unexported helpers. |
|
operation
Package operation lowers what a document says an API does: its path items, webhooks and callbacks, the parameters merged onto each operation, and the content of every request body, response and header.
|
Package operation lowers what a document says an API does: its path items, webhooks and callbacks, the parameters merged onto each operation, and the content of every request body, response and header. |
|
overlay
Package overlay applies an OpenAPI Overlay document to the parsed node tree, and records which positions in the result the overlay is answerable for.
|
Package overlay applies an OpenAPI Overlay document to the parsed node tree, and records which positions in the result the overlay is answerable for. |
|
pagination
Package pagination fills an operation's ir.Pagination: Promote from the extensions a policy maps to the pagination targets (docs/compilers/openapi.md#extension-pagination), and InferWalks, under the pagination-inference policy, from the names its query parameters and its success responses' members give (docs/compilers/openapi.md#pagination-policy).
|
Package pagination fills an operation's ir.Pagination: Promote from the extensions a policy maps to the pagination targets (docs/compilers/openapi.md#extension-pagination), and InferWalks, under the pagination-inference policy, from the names its query parameters and its success responses' members give (docs/compilers/openapi.md#pagination-policy). |
|
paramchoice
Package paramchoice reads what the promotion policy maps an operation's key to, the choices among its parameters, once the document is whole (docs/compilers/openapi.md#mutually-exclusive-parameters): each names alternative sets of the operation's parameters by name, resolved as a link's parameters key is.
|
Package paramchoice reads what the promotion policy maps an operation's key to, the choices among its parameters, once the document is whole (docs/compilers/openapi.md#mutually-exclusive-parameters): each names alternative sets of the operation's parameters by name, resolved as a link's parameters key is. |
|
provenance
Package provenance places a finding or a lowered position in the input document that supplied it: a pointer through Doc, and a node of a decoded tree through Tree, each a value the package placing asks of directly.
|
Package provenance places a finding or a lowered position in the input document that supplied it: a pointer through Doc, and a node of a decoded tree through Tree, each a value the package placing asks of directly. |
|
replacement
Package replacement fills what a deprecation names as its replacement (ir.Deprecation.ReplacedBy): Resolve from the vendor extensions a policy maps to lowering.TargetDeprecationReplacedBy, as every promotion reads the extensions the nodes keep, and Infer, under the replacement policy, from what the deprecation's message names where no such extension is written.
|
Package replacement fills what a deprecation names as its replacement (ir.Deprecation.ReplacedBy): Resolve from the vendor extensions a policy maps to lowering.TargetDeprecationReplacedBy, as every promotion reads the extensions the nodes keep, and Infer, under the replacement policy, from what the deprecation's message names where no such extension is written. |
|
resolve
Package resolve answers what a $ref names: the same-document pointer it addresses, the schema declared there and the type interned there, and, for components that are not schemas, the concrete value and declaration site a reference-or-inline entry stands for.
|
Package resolve answers what a $ref names: the same-document pointer it addresses, the schema declared there and the type interned there, and, for components that are not schemas, the concrete value and declaration site a reference-or-inline entry stands for. |
|
runtimeexpr
Package runtimeexpr reads the runtime expressions an OpenAPI document writes, as the values of a link and the page walk of an extension do, and finds the members of a body one names, through the reading of the compiled document those steps share (whole.Document).
|
Package runtimeexpr reads the runtime expressions an OpenAPI document writes, as the values of a link and the page walk of an extension do, and finds the members of a body one names, through the reading of the compiled document those steps share (whole.Document). |
|
scan
Package scan refuses a source document before any of it is lowered, for shapes the parser library cannot decode: a YAML alias cycle or fan-out, which overflows its stack or exhausts memory (docs/parser-library.md#alias-cycle, docs/parser-library.md#alias-expansion), and nesting so deep that its cost per node, growing with depth, adds up past use (docs/parser-library.md#nesting-cost).
|
Package scan refuses a source document before any of it is lowered, for shapes the parser library cannot decode: a YAML alias cycle or fan-out, which overflows its stack or exhausts memory (docs/parser-library.md#alias-cycle, docs/parser-library.md#alias-expansion), and nesting so deep that its cost per node, growing with depth, adds up past use (docs/parser-library.md#nesting-cost). |
|
schema
Package schema lowers OpenAPI schemas into IR types: the shape walk, its compositions, the references between schemas, and the preservation of what the IR has no field for.
|
Package schema lowers OpenAPI schemas into IR types: the shape walk, its compositions, the references between schemas, and the preservation of what the IR has no field for. |
|
servers
Package servers lowers the servers a document declares, whichever object declares them, into one registry keyed by ID, and names the ones a scope uses (docs/compilers/openapi.md#servers, docs/compilers/openapi.md#path-item-servers).
|
Package servers lowers the servers a document declares, whichever object declares them, into one registry keyed by ID, and names the ones a scope uses (docs/compilers/openapi.md#servers, docs/compilers/openapi.md#path-item-servers). |
|
sourceindex
Package sourceindex answers, in one walk, the questions asked of a decoded source tree before any of it is lowered: how many nodes it declares, how deeply it nests, which aliases name an ancestor, and which mappings carry a tag the parser faults on, as a value the caller carries rather than a walk it repeats.
|
Package sourceindex answers, in one walk, the questions asked of a decoded source tree before any of it is lowered: how many nodes it declares, how deeply it nests, which aliases name an ancestor, and which mappings carry a tag the parser faults on, as a value the caller carries rather than a walk it repeats. |
|
spelling
Package spelling relates the primitive kinds OpenAPI spells.
|
Package spelling relates the primitive kinds OpenAPI spells. |
|
stream
Package stream reads what the promotion policy maps an operation's or a streaming content's keys to, of the stream an operation's success responses carry, once the document is whole: the frame data that ends it and the request input that asks for it (docs/compilers/openapi.md#streaming-media).
|
Package stream reads what the promotion policy maps an operation's or a streaming content's keys to, of the stream an operation's success responses carry, once the document is whole: the frame data that ends it and the request input that asks for it (docs/compilers/openapi.md#streaming-media). |
|
value
Package value classifies YAML scalars and lowers source values into ir.Value, keeping numeric literals as their exact source text so nothing rounds through float64.
|
Package value classifies YAML scalars and lowers source values into ir.Value, keeping numeric literals as their exact source text so nothing rounds through float64. |
|
whole
Package whole reads a compiled document once it is whole, for the steps that run after the lowerings: it lists the operations and indexes the members, parameters and headers those steps name (Document).
|
Package whole reads a compiled document once it is whole, for the steps that run after the lowerings: it lists the operations and indexes the members, parameters and headers those steps name (Document). |
|
ynode
Package ynode spells yaml.v3 nodes for tests: the constructors for the node kinds a parse produces, the `<<` merge key among them, and the merge chain the compiler's depth bounds are measured against.
|
Package ynode spells yaml.v3 nodes for tests: the constructors for the node kinds a parse produces, the `<<` merge key among them, and the merge chain the compiler's depth bounds are measured against. |