annotation

package
v0.0.0-...-38da05c Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

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.

It exists because those two jobs share one question: given a $ref, does the fact belong to the referenced declaration or to the site that references it? Site and Home answer it once: no reader here resolves a referent of its own, so a new annotation cannot quietly pick another referent.

It is also how this compiler keeps a construct verbatim, once a lowering decides to keep it.

Index

Constants

View Source
const MaxUnknownKeys = 64

MaxUnknownKeys bounds how many keys one object contributes to the IR. It sits far above what a document writes by accident, so an object reaching it is generated or hostile. Keys past it are announced under diag.UnknownKeyBudget.

It bounds the keys the census answers for, not the keys written: one another reader already kept is filtered out first, since a slot spent on an entry present either way would drop one that is not. An unreachable key still spends its slot: finding that out costs the lookup keeping it does. Diagnostics are one per key plus the budget's own.

Variables

This section is empty.

Functions

func AppendExample

func AppendExample(out []ir.Example, proto ir.Example, node *yaml.Node,
	doc provenance.Doc, base jsontext.Pointer, seg ...string,
) ([]ir.Example, []ir.Diagnostic)

AppendExample converts node into proto's value and appends the result to out. An unconvertible node is skipped and yields a warning diagnostic for the caller to record: an example is an annotation, not a structural hole, so losing it is fine as long as it is not silent. proto carries the annotations around the value (name, summary, description); base and seg locate the node, joined into a pointer only on the failure path.

func ClosesAfterComposition

func ClosesAfterComposition(s *oas3.Schema) bool

ClosesAfterComposition reports whether s closes its model once composition is resolved: it writes `unevaluatedProperties: false` and no additionalProperties, which would evaluate every property the keyword could apply to (JSON Schema 2020-12 §11.3). It reads the adjacent keyword alone, so an applicator kept verbatim that evaluates a member leaves the closure typed (GitHub #1904).

func Constraints

func Constraints(s *oas3.Schema, take Bounds, exclusiveBoolean bool, pointer jsontext.Pointer, doc provenance.Doc) (*ir.Constraints, ir.Unmodeled, []ir.Diagnostic)

Constraints reads the value constraints of the groups take names that s writes, nil when none is, and nothing of a group not taken. Numeric bounds come from the raw YAML nodes, never the *float64 model fields. A literal no BigVal holds, an exclusive bound in the other form than exclusiveBoolean selects, or a count the model misreads (ExactCount) is skipped, for the rule table's check to report (docs/compilers/openapi.md#constraints) or the caller to keep. The second return holds a 3.0 exclusive modifier with no bound beside it (applyExclusiveFlag), placed by pointer and doc.

func ContainsRaw

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

ContainsRaw combines contains/minContains/maxContains into one raw JSON object, and names the keywords it combines.

func CopyEntriesInto

func CopyEntriesInto(p *ir.Unmodeled, src ir.Unmodeled) []ir.Diagnostic

CopyEntriesInto writes onto p a copy of each entry of src, its value cloned, for a reader keeping one set of entries on several carriers. Unlike MergeUnmodeled it never replaces an entry p holds: that one stays, and the entry from src is reported missing from p (diag.UnknownKeyEntryTaken), in key order as the census reports. Another carrier may hold it, so the finding does not say the IR lacks it.

func CountIsExact

func CountIsExact(s *oas3.Schema, keyword string, count *int64) bool

CountIsExact reports whether the integer keyword s writes states a count, the parser's model holding one, count (ExactCount).

func DecidedKeyword

func DecidedKeyword(keyword string) bool

DecidedKeyword reports whether keyword is one the census leaves alone because this compiler has already decided about it (decidedKeywords).

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 because the recorders reading the same keyword lists read them there (recordResidue, dialectAt, declaredConstraints), and a predicate consulting a different source could disagree with them in either direction.

func DeclaresRedaction

func DeclaresRedaction(s *oas3.Schema) bool

DeclaresRedaction reports whether s asks for its value to be redacted, by writing `format: password`. It is honoured whatever type s declares: the table lists it for strings, but hiding a value no one needed hidden is the safe reading. It is an annotation rather than a (type, format) pairing, so the shape a position lowers to is read without it.

func DialectKeyword

func DialectKeyword(keyword string) bool

DialectKeyword reports whether keyword is one of DialectKeywords.

func DialectKeywords

func DialectKeywords() iter.Seq[string]

DialectKeywords yields the JSON Schema resource and dialect keywords the IR keeps out of scope (dialectKeywords). Each reader ranges over its own sequence, so none can change what another reads.

func EffectiveDeprecated

func EffectiveDeprecated(chain []*oas3.Schema) bool

EffectiveDeprecated reports whether a schema of chain (Site.Chain) is deprecated. JSON Schema reads a location deprecated where any occurrence of the keyword applying to it is true, and an occurrence false as one omitted, so no schema of a chain withdraws another's.

func EffectiveVisibility

func EffectiveVisibility(chain []*oas3.Schema) (ir.Visibility, bool)

EffectiveVisibility maps readOnly/writeOnly to a lifecycle visibility set (docs/ir/properties.md#visibility): readOnly is present in every response lifecycle and absent only from requests; writeOnly is create+update. The bool reports both flags in force, which no lifecycle satisfies. It is not a diagnostic because this reader has no provenance of its own.

Each flag is in force where any schema of chain sets it, as JSON Schema reads both (docs/compilers/openapi.md#ref-use-site).

Both in force is contradictory but legal: JSON Schema forbids neither. Read as sets they leave nothing, which Visibility{None: true} states, as merge.mergeVisibility answers for the pair spread over two allOf branches (GitHub #276).

func EntryKey

func EntryKey(scope, key string) string

EntryKey is the Unmodeled key the census keeps key under, written on an object at scope beneath its carrier. A reader that keeps a key itself spells it with this, so the census finds the entry and leaves the key alone.

func ExactCount

func ExactCount(s *oas3.Schema, keyword string, count *int64) *int64

ExactCount returns the count the integer keyword s writes states, where the parser's model holds one, count, and nil where the literal states no count: no number, or none that is a non-negative integer within int64. The count is the literal's, read as YAML 1.2's core schema reads it (value.NumericLiteral, docs/parser-library.md#scalar-resolution), never the model's, which reads 010 as 8, holds an integer past int64 as 0 and cuts a fraction to an integer. A negative one is the load phase's to report.

func ExamplesRaw

func ExamplesRaw(s *oas3.Schema) (ir.RawValue, []string, error)

ExamplesRaw combines example and examples into one raw JSON object, and names the keywords it combines: Set.Examples holds the two as one list.

func ExtensionsAt

func ExtensionsAt(doc provenance.Doc, 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 orders their diagnostics; distinct scopes cannot collide, so no entry depends on it.

func ExtensionsFrom

func ExtensionsFrom(ext *extensions.Extensions, doc provenance.Doc, owner jsontext.Pointer) (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.

A caller records the diagnostics whether or not it keeps the entries: an object whose every extension failed to serialize returns warnings and no entries, so gating them on the entries drops each one exactly when it matters (TestAuth_UnserializableExtensionStillWarns and its twins).

func ExtensionsNamed

func ExtensionsNamed(ext *extensions.Extensions, names iter.Seq[string]) ir.Unmodeled

ExtensionsNamed lowers the extensions names lists out of ext, keyed and valued as ExtensionsFrom gives them, for a reader of another object's keys: a carrier reading its $ref's referent. Such a reader reports nothing, so an entry has no provenance. Looking up each name leaves the rest of ext unserialized, which is every key of nearly every referent. A value that does not serialize is left out, as ExtensionsFrom reports it where it is written.

func ExtensionsUnder

func ExtensionsUnder(ext *extensions.Extensions, doc provenance.Doc, owner jsontext.Pointer, scope string) (ir.Unmodeled, []ir.Diagnostic)

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

Those objects ride on the nearest node that has one, where "openapi:x-id" from two objects would be one key, so scope names the writer: the source path from the carrier down to it, or its own keyword where it is not beneath the carrier.

Keys cannot collide: an extension name begins with "x-", and a scope extending another on its carrier first adds a keyword the compiler writes, which never does. The same gap separates them from non-extension keys.

func FillCarrierDocs

func FillCarrierDocs(d *ir.Docs, chain []*oas3.Schema)

FillCarrierDocs fills the ir.Property or ir.Parameter carrying a position with the documentation effective there: the title, description and externalDocs of chain's farthest schema first, then each nearer one's over them, field by field. A bare `$ref` therefore reads all three from the referent.

Both ends are deliberate. The use site is the only home a keyword written at the position has once the body reduced to a shared node (GitHub #116). The referent is the rule docs/compilers/openapi.md#ref-use-site: ref-target annotations merge onto the referencing Property/Parameter with use-site precedence, uniformly, constraints excepted, while the referent keeps its own copy on its node.

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, []string, error)

IfThenElseRaw combines the present if/then/else arms into one raw JSON object, and names the arms it combines.

func IsFalseSchema

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

IsFalseSchema reports whether js is the boolean `false` schema, which no other value written in its place is, though the parser decodes a null, a string, a number or a list as `false` (docs/parser-library.md#null-schema-is-false).

func IsNoSchema

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

IsNoSchema reports whether js is written as no schema: its node, its alias followed, is neither a mapping nor a scalar tagged !!bool. The parser reads such a value as the boolean `false` schema (docs/parser-library.md#null-schema-is-false), so only the node tells them apart, on every route a schema is reached by.

func IsNullNode

func IsNullNode(n *yaml.Node) bool

IsNullNode reports whether n, read through an alias, is a YAML null.

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, prov ir.Provenance,
)

PreserveInto records raw under key in p, located at prov, 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 it fails the encoding of the whole document that carries it.

func PreserveNodeInto

func PreserveNodeInto(p *ir.Unmodeled, key string, node *yaml.Node,
	reason ir.UnmodeledReason, prov ir.Provenance,
) (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 PreserveSchemaKeyword

func PreserveSchemaKeyword(p *ir.Unmodeled, s *oas3.Schema, keyword string,
	reason ir.UnmodeledReason, pointer jsontext.Pointer, doc provenance.Doc,
) (bool, []ir.Diagnostic)

PreserveSchemaKeyword is PreserveNodeInto addressed by keyword: it keeps what s, the schema at pointer, writes under keyword, keyed by EntryKey and located at the keyword itself. Those are the key and the position the census checks before keeping a keyword on its own (unrecorded). Deriving both here leaves no caller a way to have the census keep the keyword again under another key, or report a collision with this entry.

An absent keyword is no construct: it keeps and places nothing.

func PreserveValidationOnlyKeyword

func PreserveValidationOnlyKeyword(p *ir.Unmodeled, s *oas3.Schema, keyword string,
	pointer jsontext.Pointer, doc provenance.Doc,
) []ir.Diagnostic

PreserveValidationOnlyKeyword is PreserveSchemaKeyword for a validation-only keyword: it keeps the keyword under ReasonValidationOnly, at its own node, which is what a validation emitter reports against, and announces it at pointer, the schema that wrote it. What PreserveSchemaKeyword keeps nothing of, it announces nothing of. A validation-only entry combining several keywords has no such node and is not kept here but by Read, which attributes it by the keywords it holds (GitHub #534).

func RawFromNode

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

RawFromNode converts a YAML node to the canonical JSON an Unmodeled entry holds. An absent node yields (nil, nil): no construct was there. One that cannot be represented yields an error, so no caller announces a preservation that never happened (GitHub #144).

A mapping holds the members the parser reads (nodeview.View.MappingPairs), a key written twice at the copy the model reads (docs/parser-library.md#duplicate-key). Conversion fails on a mapping merging past nodeview.MergeDepthLimit, a scalar value.Classify refuses, invalid UTF-8, and an alias that cycles or expands past the node budget. Numeric literals stay exact (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, its alias followed, or nil when absent. The library's GetPropertyNode resolves Go core field names and returns key nodes; this reads the schema's root mapping for the on-wire keyword as the parser reads it (nodeview.Child), through its `<<` merges, and returns its value node, which is where exact literals live.

A null reads as absent, since no keyword admits one, unless the keyword's value is an instance (holdsInstance), so every reader sees one keyword left out (docs/compilers/openapi.md#null-keywords).

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 the schema bindings).

func TakeString

func TakeString(p *ir.Unmodeled, root *yaml.Node, key string, valid func(string) bool,
	doc provenance.Doc, owner jsontext.Pointer, scope string,
) (string, bool, []ir.Diagnostic)

TakeString reads a string field the parser's model names no member for, written directly under key on root, the mapping the census reads (GitHub #615). It reports whether it read the key, for the caller to pass to the census as taken.

A scalar the parser decodes as a string is returned, unless valid refuses a non-empty one; empty or null is read as unset. Any other value is kept verbatim on p at the census's own entry, with a warning. root is read as the parser reads it, through its `<<` merges (nodeview.Child).

func UndefinedKeywordsIn

func UndefinedKeywordsIn(p *ir.Unmodeled, s *oas3.Schema, keys []string, pointer jsontext.Pointer, doc provenance.Doc) []ir.Diagnostic

UndefinedKeywordsIn records on p each of keys, keywords s writes that the schema model names but the dialect s is read in does not define and nothing reads, and announces each as UnknownKeywordsIn announces a keyword the model does not name: JSON Schema 2020-12 ignores the two alike. The caller says which keywords those are, since only it knows the dialect and the policies.

func Under

func Under(scope string, src ir.Unmodeled) ir.Unmodeled

Under returns src with each entry keyed beneath scope: "openapi:k" becomes "openapi:<scope>/k". src is not written. It keeps what one source object writes apart from what another writes on the carrier holding both, so the two can spell one key (docs/ir/unmodeled.md#keys). An empty src returns nil.

func UnknownKeysIn

func UnknownKeysIn(p *ir.Unmodeled, model any, doc provenance.Doc, owner jsontext.Pointer, taken ...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 source pointer.

It keeps each key and reports none: the rule table reports every such key of every object it judges, lowered or not (docs/compilers/openapi.md#unknown-keys), so a report here would be the key's second. What it reports is about the entry: one taken, unreachable or past the budget.

func UnknownKeysNamed

func UnknownKeysNamed(p *ir.Unmodeled, keys []string, root *yaml.Node,
	doc provenance.Doc, owner jsontext.Pointer, scope string, taken ...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 an unrecognized key into that map rather than recording it as undeclared, so the object's census is empty however much the document wrote (docs/parser-library.md#embedded-map-keys). Its leftovers are graded as any undeclared key is, because UnknownKeysUnder delegates here.

func UnknownKeysUnder

func UnknownKeysUnder(p *ir.Unmodeled, model any, doc provenance.Doc, owner jsontext.Pointer, scope string, taken ...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. taken lists keys a reader placed in a field (TakeString).

func UnknownKeywordsIn

func UnknownKeywordsIn(p *ir.Unmodeled, s *oas3.Schema, pointer jsontext.Pointer, doc provenance.Doc, taken ...string) []ir.Diagnostic

UnknownKeywordsIn records on p the keywords s writes that no field of the JSON Schema model names, and announces each: legal JSON Schema 2020-12 an implementation must ignore, so a decision rather than a fault. The model keeps only a keyword's name, so its value is read from the raw node (docs/parser-library.md#unmodeled-keywords).

It runs after every other reader and keeps what none kept: `$vocabulary` and `dependentRequired` have readers of their own. A keyword no reader leaves a trace of is named in decidedKeywords, or in taken where only the caller knows a reader took it.

func WritesKeywordLeftOut

func WritesKeywordLeftOut(s *oas3.Schema, key string) bool

WritesKeywordLeftOut reports whether s writes key as a null that reads as the keyword left out (RawPropertyNode), for a reader that lists the keys s writes rather than asking for one. A null is a value in an extension, and in a key the census keeps.

func WritesReference

func WritesReference(raw ir.RawValue) bool

WritesReference reports whether raw, a schema or keyword value rendered as JSON, names a member referenceKeywords lists at any depth whose value is no absolute URI (fragment.Absolute), so that what it says turns on the base it is read against. Text with none says the same under every base. A member written as data, under `default` or `examples`, counts, as does a value that is no string and text that does not decode: each errs towards comparing the bases. Every token read consumes input, so the walk is bounded by raw's length.

func WritesUnknownKeyword

func WritesUnknownKeyword(s *oas3.Schema) bool

WritesUnknownKeyword reports whether s writes a keyword UnknownKeywordsIn would consider keeping, so a position can tell whether it needs a node of its own for one to land on.

func Written

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

Written reports whether js is a schema written at its position: present, and not written as no schema, which states nothing about the values there (IsNoSchema). The load phase reports such a value; every reader takes it as left out (docs/compilers/openapi.md#null-schema).

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.

Types

type Bounds

type Bounds uint8

Bounds names the groups of value bounds a reader takes, each the keywords JSON Schema applies to one kind of instance alone.

const (
	// NumberBounds are minimum, maximum, their exclusive forms and multipleOf.
	NumberBounds Bounds = 1 << iota
	// StringBounds are minLength, maxLength and pattern.
	StringBounds
	// ObjectBounds are minProperties and maxProperties.
	ObjectBounds

	// AllBounds is every group, for a reader of a value of any kind.
	AllBounds = NumberBounds | StringBounds | ObjectBounds
)

The groups of Bounds.

type Dialect

type Dialect struct {
	Identifier        string
	IdentifierIgnored bool
	Dependencies      bool
	ListedTuple       bool
}

Dialect is what a schema's dialect spells otherwise than JSON Schema 2020-12, as the readers here need it: the Identifier keyword (oas.SchemaRules.Identifier), "" for `$id`, whether the identifier is IdentifierIgnored, as the drafts before 2019-09 ignore every keyword beside a `$ref` (oas.SchemaRules.IgnoresRefFields), whether it defines Dependencies, the drafts' validation-only keyword 2019-09 split in two, and whether it reads a ListedTuple, an `items` list whose rest is the `additionalItems` beside it, as the drafts before 2020-12 spell a tuple.

type ExtensionSite

type ExtensionSite struct {
	Scope string
	Owner jsontext.Pointer
	Ext   *extensions.Extensions
}

ExtensionSite is one object's x-* map paired with where it was written: Owner is the object's own source pointer, and Scope is what its entries key under on the carrier that ends up holding them (see ExtensionsUnder).

type Home

type Home int

Home names where the annotations a schema position declares are kept. It is what decides whether a position that lowered to a shared node hoists one of its own, so the two homes can never both hold the same declaration (GitHub #116).

const (
	// HomeOwnNode marks a position with no home but a type node: items,
	// additionalProperties, prefixItems, patternProperties, a union branch, a
	// media-type schema, a component, a $ref-hoisted sub-schema. A declaration
	// there hoists an alias rather than lose what it wrote.
	HomeOwnNode Home = iota
	// HomeCarrier marks a position whose caller carries an ir.Property or
	// ir.Parameter that holds the declaration's annotations itself
	// (FillPropertyDetail, fillParamSchema): a model property, a response or
	// part header, an operation parameter. Hoisting there would give one
	// declaration two homes.
	HomeCarrier
)

type Kind

type Kind int

Kind distinguishes a position that declares a type from one that references another type and may carry annotations of its own.

const (
	Declaration Kind = iota
	Reference
)

The two site kinds. Declaration is a position that writes a schema of its own; Reference is one that points at another and may still annotate the pointer.

func (Kind) String

func (k Kind) String() string

String renders k by name; an assertion failure or test diff over a bare Kind would otherwise print the underlying int (0 or 1).

type Set

type Set struct {
	Docs       ir.Docs
	Deprecated bool
	// Sensitive is a redaction the site or its referent asks for
	// (DeclaresRedaction). A type node holds it as Sensitive, and a property or
	// a parameter as Secret.
	Sensitive bool
	XML       *ir.XMLHints
	Examples  []ir.Example
	Unmodeled ir.Unmodeled
}

Set is everything a site's annotations yield, before any of it is attached to a carrier.

The readers produce a value; the caller decides what its carrier can hold. A Parameter has no XML field and a TypeCommon has no Required, so the shape of the write differs per carrier while the reading does not.

func Read

func Read(st Site, pointer jsontext.Pointer, doc provenance.Doc) (Set, []ir.Diagnostic)

Read reads every site-local annotation at st: what its schema writes at pointer, then what each voice writes at its own. A voice agrees with what spoke before it wherever both write a keyword (schema.voicesAmong), so a keyword is taken once and nothing here chooses between two. A voice's unevaluated keywords fold nowhere (schema.foldEntry), so the position keeps none: its branch, kept whole, is their one record.

This is the one place the site-versus-referent choice is made, rather than at each position that attaches annotations: three attachment points used to make it separately and disagreed.

type Site

type Site struct {
	Kind Kind
	Node *oas3.Schema
	// Voices are the branches read as written at Node
	// (docs/compilers/openapi.md#allof-inline-residue).
	Voices []Voice
	// Referents is empty when Kind is Reference but the $ref's chain ends on no
	// schema; refTypeRef is what diagnoses that, not this.
	Referents []*oas3.Schema
	// Dialect is what the dialect Node is read in spells otherwise than 2020-12.
	Dialect Dialect
	// Closure says the node Node lowered to holds its `unevaluatedProperties:
	// false` as its openness, so no entry keeps it. The zero value keeps it.
	Closure bool
}

Site is what a schema position declares: Node is the schema written there, Voices the inline allOf branches read as written beside it, and Referents, honoured only for a reference site, what a use site's annotations fall back to, nearest first.

A Site At builds carries none of either: a declaration's annotations bind the position they are written at (attachDeclaredAnnotations), and a component that aliases another keeps the target's annotations reachable through its Base. A reader that inherits, FillPropertyDetail (schema/property.go) or fillParamSchema, builds its own Site (schema.UseOf).

func At

At builds the site for js, a reference site's without its Referents (see Site).

A schema whose $ref is present but empty ({$ref: ""}) is a declaration, not a reference site: an empty ref resolves nowhere, so IsReference is false.

At trusts its caller that js is the schema at the position being modeled.

func (Site) Chain

func (st Site) Chain() []*oas3.Schema

Chain returns what speaks for the site, nearest first: its own schema, its voices, then the referents a reference site falls back to.

type Voice

type Voice struct {
	Node *oas3.Schema
	At   jsontext.Pointer
}

Voice is an inline allOf branch and where it is written, so what it declares is read, and reported, at its own pointer.

Jump to

Keyboard shortcuts

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