annotation

func BigValEqual ¶

func BigValEqual(a, b ir.BigVal) bool

BigValEqual reports whether two numeric literals denote the same value, so that one magnitude spelled two ways — 10, 10.0, 1e1 — is one value rather than two.

It reads each literal rather than materializing it, and that is what makes it total. A rational will not build 1e1000001 at all, so a comparison resting on one has to answer that pair some other way, and the only answer left is their text — which calls 1e1000001 and 10e1000000 two values and reports a disagreement between a bound and itself.

Identical text is the one pair that needs no reading: a literal denotes one value whatever grammar it belongs to. That is also the whole answer for a pair outside the decimal grammar, where two differing spellings are reported unequal rather than guessed at. No BigVal is outside that grammar today, and TestBigValGrammarStaysWithinTheDecimalReading is what holds that true.

func Constraints ¶

func Constraints(s *oas3.Schema, exclusiveBoolean bool, pointer string, srcIndex int) (*ir.Constraints, ir.Unmodeled, []ir.Diagnostic)

Constraints reads a schema's scalar (string/number/object-count) value constraints into an ir.Constraints. Numeric bounds are read from the raw YAML nodes, never the *float64 model fields, to preserve full decimal precision (the no-float64 invariant). Collection bounds (minItems/maxItems/uniqueItems) are List-owned and read elsewhere. A non-finite bound literal yields an error-severity diag.NumericPrecision diagnostic and is skipped; nil is returned when no constraint is present. exclusiveBoolean selects the exclusiveMinimum/exclusiveMaximum dialect (see applyExclusive), and under the 2020-12 one a side that declares both of its keywords is settled by reconcileBound rather than by whichever ran last.

The keyword that reconciliation leaves out of ir.Constraints comes back as the second return, an ir.Unmodeled the caller merges into whichever carrier its reading position owns. pointer and srcIndex locate it, exactly as they locate what Read keeps. Everything else a schema says about its values reaches a field, so on all but a co-declared numeric bound that map is nil.

It reads beside the other readers here for the reason they are here at all: what a schema says about the values admitted at a position is read the same way whoever asks, and none of it needs the lowering walk. Which dialect applies is the caller's to decide — that is a fact about the document, not about the schema, and it is the one thing this reader will not go and find.

func ContainsRaw ¶

func ContainsRaw(s *oas3.Schema) (ir.RawValue, error)

ContainsRaw combines contains/minContains/maxContains into one raw JSON object.

func DeclaredSchema ¶

func DeclaredSchema(js *oas3.JSONSchema[oas3.Referenceable]) *oas3.JSONSchema[oas3.Referenceable]

DeclaredSchema returns the schema written at the position js references — one hop, not the end of the chain. GetResolvedSchema follows a reference to a reference all the way through, which is the wrong node to hoist at that position: a sub-schema spelled {$ref: Other, minimum: 7} would be read as Other, and the bound written beside the $ref would be gone before anything could record it.

func DeclaresAny ¶

func DeclaresAny(s *oas3.Schema, keywords []string) bool

DeclaresAny reports whether s writes any of keywords. It reads the raw nodes rather than the model fields for the reason declaresValueConstraints does: the recorders these gate (recordResidue, dialectAt) read them there, and a predicate consulting a different source could disagree with them in either direction.

func EffectiveDeprecated ¶

func EffectiveDeprecated(ref, tgt *oas3.Schema) bool

EffectiveDeprecated reports the deprecated flag, use-site over referent.

func EffectiveVisibility ¶

func EffectiveVisibility(ref, tgt *oas3.Schema) (ir.Visibility, bool)

EffectiveVisibility maps readOnly/writeOnly to a lifecycle visibility set (ir-design §5.2): readOnly is present in every response lifecycle (read/delete/query) and absent only from requests; writeOnly is create+update. It reports separately whether both flags were in force, which no lifecycle satisfies.

Each flag is resolved on its own, use-site over referent, so a position that writes one of them settles that flag and leaves the other to resolve from the referent — the uniform §14 merge, not a composite annotation one node wins outright.

Both in force is contradictory but legal: JSON Schema 2020-12 says readOnly means the value is not writable and writeOnly that it is not readable, and forbids neither beside the other. Read as sets, they leave nothing — the property is admitted by no lifecycle, which Visibility{None: true} states exactly. That is what merge.mergeVisibility already answers when the same pairing is spread over two allOf branches, so the two spellings of one contradiction no longer disagree (GitHub #276). Guarding readOnly first and returning is what made them disagree, and it discarded the second flag with no diagnostic in either channel.

The bool rather than a diagnostic: this reader has no provenance of its own, and the caller that has one is the caller that knows which carrier it is filling.

func ExtensionsAt ¶

func ExtensionsAt(srcIndex int, sites ...ExtensionSite) (ir.Unmodeled, []ir.Diagnostic)

ExtensionsAt folds every site into one Unmodeled map, for the carriers that hold more than one object's extensions. Sites are applied in the order given, which is source order at every caller; distinct scopes cannot collide, so the order decides nothing but is fixed anyway.

func ExtensionsFrom ¶

func ExtensionsFrom(ext *extensions.Extensions, srcIndex int, owner string) (ir.Unmodeled, []ir.Diagnostic)

ExtensionsFrom lowers an x-* extension map into namespaced ir.Unmodeled, keys prefixed "openapi:" and values serialized to raw JSON. owner is the pointer of the object the extensions were written on; each entry is located at its own key beneath it and marked ReasonVendorExtension, since the format assigns an x-* key no semantics at all.

func ExtensionsUnder ¶

func ExtensionsUnder(ext *extensions.Extensions, srcIndex int, owner, scope string) (ir.Unmodeled, []ir.Diagnostic)

ExtensionsUnder is ExtensionsFrom with every entry keyed beneath scope, for the objects whose extensions have no Unmodeled map of their own to land on.

Most OpenAPI objects lower to an IR node that carries one, and those pass an empty scope. The rest ride on the nearest node that does — an info object's on the document, an encoding's on the content, a path item's on each of its operations — and several of them can reach the same map, where "openapi:x-id" from two objects is one key and the surviving entry would depend on which lowering ran last. scope names which object wrote them: the source path from the carrier down to it, or the object's own keyword where it is not beneath the carrier at all.

No two keys can collide: every scope segment is a literal that never begins with "x-" and every extension name always does, so the first "x-" segment is where the scope ends and the name begins, and one key cannot be spelled by two (scope, owner) pairs. That same gap holds against the non-extension keys a carrier already holds under these scopes, such as the "openapi:encoding/<part>/allowReserved" written beside an encoding's x-*.

func FillCarrierDocs ¶

func FillCarrierDocs(d *ir.Docs, ref, tgt *oas3.Schema)

FillCarrierDocs fills the ir.Property or ir.Parameter carrying a position with the documentation effective there: the $ref referent's title, description and externalDocs first, then the use-site's over them, field by field. A carrier therefore ends up with documentation the position itself need not have written — a bare `$ref` reads all three from the referent, which keeps its own copy on its node.

Both halves are deliberate. The use-site half is the only home a keyword written *at* the position has once the body reduced to a shared node (GitHub #116): dropping it there loses it outright. The referent half is ir-design §14 — ref-target annotations merge onto the referencing Property/Parameter with use-site precedence, applied uniformly — and it is how every other field this compiler reads through a $ref already behaves (fillPropertyDefault, EffectiveVisibility, EffectiveDeprecated).

Uniform is the load-bearing word: description alone inheriting, while title and externalDocs stop at the position, is the ad-hoc per-keyword patching §14 names as the counterexample to avoid.

func FillTypeDocs ¶

func FillTypeDocs(d *ir.Docs, s *oas3.Schema)

FillTypeDocs maps a schema's title, description, and externalDocs onto Docs. Every field is assigned, never accumulated: a schema declares at most one externalDocs, and a pointer read twice (a sub-schema lowered both in place and through a $ref that hoists it) must not end up with two copies of it.

func IfThenElseRaw ¶

func IfThenElseRaw(s *oas3.Schema) (ir.RawValue, error)

IfThenElseRaw combines the present if/then/else arms into one raw JSON object.

func IsFalseSchema ¶

func IsFalseSchema(js *oas3.JSONSchema[oas3.Referenceable]) bool

IsFalseSchema reports whether js is the boolean `false` schema.

func MergeUnmodeled ¶

func MergeUnmodeled(dst, src ir.Unmodeled) ir.Unmodeled

MergeUnmodeled overlays src onto dst, allocating dst on first write.

func PreserveInto ¶

func PreserveInto(p *ir.Unmodeled, key string, raw ir.RawValue,
	reason ir.UnmodeledReason, pointer string, srcIndex int,
)

PreserveInto records raw under key in p, or records nothing when there are no bytes to record.

len rather than a nil comparison: nil and a zero-length slice are distinct states, and an empty payload is the worse of the two. It preserves no construct, and json.Marshal rejects it for the whole document while naming json.RawMessage rather than the entry that carried it.

func PreserveKeywordInto ¶

func PreserveKeywordInto(p *ir.Unmodeled, key string, raw ir.RawValue,
	declPtr, entryPtr, label string, srcIndex int,
) []ir.Diagnostic

PreserveKeywordInto records a validation-only keyword and returns the one diagnostic announcing it. An absent payload records nothing and announces nothing; an unconvertible one never reaches here, because its caller reports it through UnpreservableDiag first.

func PreserveNodeInto ¶

func PreserveNodeInto(p *ir.Unmodeled, key string, node *yaml.Node,
	reason ir.UnmodeledReason, pointer string, srcIndex int,
) (bool, []ir.Diagnostic)

PreserveNodeInto converts node and records it under key, reporting a construct that reached the IR in no form at all rather than leaving its caller to announce a preservation that did not happen (GitHub #144).

It reports whether an entry was written, which is what a caller with an announcement to make gates on. The three outcomes it distinguishes are the point: an absent node writes nothing and says nothing, because there was no construct; a converted one writes the entry; an unconvertible one writes nothing and yields the diagnostic that says so.

func RawChildNode ¶

func RawChildNode(root *yaml.Node, key string) *yaml.Node

RawChildNode returns the raw YAML value node of a mapping child keyed by the on-wire name, unwrapping a document node first; nil when absent. It reads exact literals the high-level model does not preserve (links, servers, content maps).

The last pair spelling the key wins, which is the pair the parser reads: marshaller skips every occurrence of a repeated key but the last. Returning the first instead described a mapping by a value nothing else in the compiler uses — reachable once a key can be spelled two ways, since an explicit pair and an aliased one are one key to the parser and two nodes here.

func RawFromNode ¶

func RawFromNode(node *yaml.Node) (ir.RawValue, error)

RawFromNode converts a YAML node to the canonical JSON an Unmodeled entry holds.

Its three outcomes are deliberately distinct, because collapsing the first two into one nil return is what let a diagnostic announce a preservation that never happened (GitHub #144): an absent node yields (nil, nil) — there was no construct here — while a node that cannot be represented yields an error.

A node fails to convert when it names something JSON cannot: a mapping key that is not a string, a key written twice, .nan or .inf, or a scalar whose tag promises a type its text does not hold. The walk's own bounds refuse two shapes more — an alias that cycles, and one that expands past its node budget. A tag yaml.v3 assigns no type to is not a failure: its scalar keeps its text.

The conversion walks the node tree rather than decoding it into `any` and re-marshalling, because that decode rounds every numeric literal through float64: it silently rewrote a 23-digit extension value and flattened 1.000000000000000000001 to 1, in the one channel whose whole promise is verbatim preservation (GitHub #32).

func RawPropertyNode ¶

func RawPropertyNode(s *oas3.Schema, key string) *yaml.Node

RawPropertyNode returns the raw YAML value node of a top-level schema keyword, or nil when absent. The library's GetPropertyNode resolves Go core field names and returns key nodes; this scans the schema's root mapping for the on-wire keyword and returns its value node, which is where exact literals live.

func SchemaOf ¶

func SchemaOf(js *oas3.JSONSchema[oas3.Referenceable]) *oas3.Schema

SchemaOf returns the schema body written at this position, including one that also carries a $ref — an example or bound written beside a $ref binds the position, not the referent, the same rule fillPropertyAnnotations and fillPropertyConstraints apply at a property. It returns nil only where no body is written: a nil either, or a boolean schema, which admits no annotations.

Every position modeled as a site reads it through At: a named component (lowerComponentSchema) and a $ref'd internal sub-schema (hoistSubSchema, fed one hop at a time by DeclaredSchema).

func UnevaluatedRaw ¶

func UnevaluatedRaw(s *oas3.Schema) (ir.RawValue, error)

UnevaluatedRaw combines a non-false unevaluatedProperties and any unevaluatedItems into one raw JSON object (a false unevaluatedProperties is a structural mode, handled in fillAdditional).

func UnknownKeysIn ¶

func UnknownKeysIn(p *ir.Unmodeled, model any, srcIndex int, owner string) []ir.Diagnostic

UnknownKeysIn records on p the keys an OpenAPI object writes that the specification neither defines nor admits as an extension, for an object lowering to a node with an Unmodeled map of its own. owner is the object's own source pointer.

Unlike its schema neighbour this reports a fault: OpenAPI gives each of its objects a closed key set and requires every extension to be prefixed x-, so a key that is neither is nothing the document is permitted to write — in practice a misspelling of the field beside it. It is kept all the same, because invariant 2 does not bend for invalid input, and a misspelt key is the one a reader most needs to find.

func UnknownKeysNamed ¶

func UnknownKeysNamed(p *ir.Unmodeled, keys []string, root *yaml.Node,
	srcIndex int, owner, scope string,
) []ir.Diagnostic

UnknownKeysNamed is UnknownKeysUnder for an object whose model keeps no census of its own, so the caller names the keys and hands over the mapping node they were written on.

One object needs it: a Path Item Object, whose core model embeds the map of its operations. The unmarshaller folds a key it does not recognize into that embedded map rather than recording it as undeclared, so the object's own census is empty however much the document wrote (speakeasy-api/openapi v1.24.1). Its leftovers are still an undeclared key of the path item, graded as one — same code, same severity, same reason — because which reader found them is not a property of the source.

It delegates rather than duplicating the grading, so the two can only be announced alike.

func UnknownKeysUnder ¶

func UnknownKeysUnder(p *ir.Unmodeled, model any, srcIndex int, owner, scope string) []ir.Diagnostic

UnknownKeysUnder is UnknownKeysIn with every entry keyed beneath scope, for the objects with no Unmodeled map of their own, whose keys ride on the nearest node that has one — an info object's on the document, a tag's on the document.

scope says which object wrote them: the source path from the carrier down to the object. Several objects reach one map, where "openapi:status" from two of them would be a single key and the entry that survived would depend on which lowering ran last.

func UnknownKeywordsIn ¶

func UnknownKeywordsIn(p *ir.Unmodeled, s *oas3.Schema, pointer string, srcIndex int) []ir.Diagnostic

UnknownKeywordsIn records on p the keywords s writes that no field of the JSON Schema model names, and announces each.

OpenAPI 3.1 schemas are JSON Schema 2020-12, where an unrecognized keyword is legal input: the specification requires an implementation to ignore what it does not recognize and allows such a keyword to carry meaning for other tooling. So this reports a decision rather than a fault, and is graded accordingly — see diag.UnknownSchemaKeyword.

It keeps only what no other reader kept, which is why it runs after all of them: `$vocabulary` and `dependentRequired` have no field in the model either and are read straight off the raw node by readers with more to say about them, so the census finds those already recorded and leaves them alone. A keyword no reader leaves a trace of needs naming in DecidedKeywords instead.

func UnpreservableDiag ¶

func UnpreservableDiag(key, pointer string, srcIndex int, err error) ir.Diagnostic

UnpreservableDiag reports a construct the compiler could neither model nor keep verbatim, so nothing of it reached the IR.

Error rather than the degradation severity its callers otherwise use: a degraded lowering still describes the source in a weaker shape, while this one leaves no trace at all, which is a losslessness failure rather than a compromise (GitHub #144).

The vendor-extension reader (ExtensionsFrom) reports the same conversion failure as a warning and is deliberately left alone: it already branches on the error and never claimed to have kept anything, so it is not the defect this code exists for.

func XMLHints ¶

func XMLHints(x *oas3.XML) *ir.XMLHints

XMLHints maps an OpenAPI XML object onto ir.XMLHints; an attribute flag becomes the "attribute" node type. Fields are read directly rather than via the library getters, which dereference unset (nil) field pointers.