resolve

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: 22 Imported by: 0

Documentation

Overview

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.

It is only that. Following a reference far enough to lower its target recurses into the schema walk, so it stays with the walk. What is here needs only the document, its path, its declared names and its bindings.

Reference resolution is not promoted to compilers/compile: not every compiler needs it, and those that do reach it by different mechanisms (docs/micro-compiler-design.md §3.2).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FilePart

func FilePart(uri string) string

FilePart returns uri, a reference's document part, as the file it names spells it: percent-decoded, since a reference is a URI reference (RFC 3986 §2.1), so "my%20file.yaml" names the file "my file.yaml". A URL is kept as written, and so is a part decoding would read otherwise: one with an escape that is not one, decoding to text that is not UTF-8, which no IR string holds, or decoding to a separator, a '#' or a scheme, each of which would name another document.

func FragmentPointer

func FragmentPointer(ref string) (jsontext.Pointer, bool)

FragmentPointer returns the JSON pointer a $ref's fragment spells, whatever document the reference names, as fragment.Pointer reads it. Unlike InternalPointer, it does not ask what this document can resolve.

It reports ok=false for a reference with no fragment, a fragment that is not a pointer (`#name` names a $anchor), a bare `#`, which names the whole document, and a fragment decoding to bytes that are not UTF-8, which no document key can spell and the IR cannot encode in an ID (GitHub #520).

func Hoistable

func Hoistable(decl *oas3.JSONSchema[oas3.Referenceable]) bool

Hoistable reports whether decl, the schema a $ref lands on, can be hoisted where it is written: one with a body, or a boolean one (GitHub #861). The schema lowering's resolvePointer and NamesReferent both ask it, so they cannot part.

func IsURL

func IsURL(location string) bool

IsURL reports whether location names a document by URL rather than as a file, as the parser library classifies it (references.ResolveAbsoluteReference): by the scheme url.Parse finds, but for a drive letter before a backslash. A scheme needs no "//" after it, and a file path holding "://" past a directory named like a scheme is still a file. A location the library cannot parse is none; it resolves nothing.

func Locate

func Locate(uri, base string) (string, bool)

Locate returns the document uri, the part of a reference before its '#', names when written in the document at base, spelled as the parser library joins one (references.ResolveAbsoluteReference), and false where it names none. It is the one reading of a document part, departing from the library's join thrice: against an http(s) URL, an absolute path resolves by RFC 3986 §5.2; a file path is read decoded (FilePart); and a relative path whose first segment holds a colon keeps a leading "./" (RFC 3986 §4.2). A URL of any scheme but file is spelled one way (normalURL).

func Object

func Object[T, S any, R interface {
	*S
	Referenced[T]
}](b *typed.Bindings, ref R) *T

Object returns what the reference-or-inline wrapper ref stands for: the object the chain of the Reference Object written where ref was read ends on, in whichever document, or ref's own object where the table reads no $ref there. It is nil for a nil ref and for a chain that does not resolve. The *S term constrains R to a pointer type so `ref == nil` is legal in generic code.

func ObjectAt

func ObjectAt[T, S any, R interface {
	*S
	Referenced[T]
}](scope Scope, ref R, use bind.Position) (*T, bind.Position)

ObjectAt is Object with the position declaring what it returns, and use for an inline entry, which declares its own object where it is written. It notes in scope.Reached each position of the source the chain passes, its end included: the declarations the IR carries through their uses.

func UseDocs

func UseDocs[T, S any, R interface {
	*S
	Referenced[T]
}](b *typed.Bindings, ref R, docs ir.Docs) ir.Docs

UseDocs folds the summary and description written beside each `$ref` of ref's chain over docs, the declaration's, from it outward, field by field, so the use site's own win, an alias's beat what it names, and a field a hop omits, or writes empty or null, leaves the one beneath standing (GitHub #610). Each is read off the mapping writing the $ref, as the model reads it, a `<<` included. OpenAPI gives such a sibling "no effect" where the object allows none, but the IR has a docs field at each position this serves (docs/compilers/openapi.md#reference-object-siblings).

Types

type Hop

type Hop[R any] struct {
	Ref R
	At  bind.Position
}

Hop is one reference a chain passes after its entry: the wrapper read where it is written, and that position, in whichever document.

func Hops

func Hops[T, S any, R interface {
	*S
	Referenced[T]
}](b *typed.Bindings, ref R) []Hop[R]

Hops returns the references the chain of ref passes after ref itself, nearest first, as the bindings' table follows it: each position a hop lands on that writes a $ref of its own. The position the chain ends at is no hop, and neither an inline entry nor one whose chain does not resolve has any. It follows as many hops as the chain counts (bind.Chain.Hops), so a loop, which resolves nowhere, is never followed.

type Names

type Names struct {
	// contains filtered or unexported fields
}

Names is a set of names, such as the component schemas a document declares, never written once NewNames builds it. A copy shares the set, which only resolve can reach, so no reader writes through one, and a Names is safe for concurrent use. The zero Names holds no name.

func NewNames

func NewNames(names ...string) Names

NewNames returns the set holding each of names.

func (Names) Has

func (n Names) Has(name string) bool

Has reports whether name is one of n's.

type Places

type Places struct {
	// contains filtered or unexported fields
}

Places is where a compile's files lie: an absolute path's directory as the compile's reader locates it (compilers.DirectoryLocator), the rule the engine places the spec's own location by, each directory asked once. A nil *Places, as for a reader locating none, leaves every path where it is spelled. Safe for concurrent use.

func NewPlaces

func NewPlaces(reader compilers.DocumentReader) *Places

NewPlaces returns where the files reader reads lie, or nil for a reader locating no directory.

func (*Places) Directory

func (p *Places) Directory(dir string) string

Directory returns where the absolute directory dir lies, asking the locator the first time, so a compile reads one answer for each directory however often it is asked. A relative one is kept as spelled, as by File.

func (*Places) File

func (p *Places) File(path string) string

File returns where the file at path lies: an absolute path, its dot segments removed, in its directory as located, its own name kept, so a file that is a link is read beside the link. A relative path is kept as spelled, as only the working directory, which a compile never reads, relates it to a directory.

func (*Places) FileOf

func (p *Places) FileOf(name string) (string, bool)

FileOf returns where the file the document name names lies (File): for a path, the path, and for a file URI the path it names, as a reader reads one (compilers.FilePath), so that one file is one document however a reference spells it. It is false for any other URL, and for a file URI naming no local file.

func (*Places) SameDocument

func (p *Places) SameDocument(a, b string) bool

SameDocument reports whether two documents a reference reads, a and b, are one: the same spelling, or for two files, a file URI naming its path, the same file where it lies (FileOf), its dot segments removed (RFC 3986 §5.2.4). A file through a link is another document only where p places no directory, and a directory that does not exist cleans away like one that does. A relative path and an absolute one are two documents, as only the working directory, which is not read, relates them. Any other URL is one only as spelled, and an empty name names none.

type Reached

type Reached struct {
	// contains filtered or unexported fields
}

Reached records the positions in the source a lowering resolved a reference to, each hop of a chain included: the declarations the IR carries through their uses rather than on a node of their own (GitHub #616).

Only the document's lowering reads it, and only once every other lowering has returned, so what it holds cannot change their answers, and as a set it cannot depend on the order they ran in. That is why sharing it between copies of a context is safe, as sharing a memo is.

func NewReached

func NewReached() *Reached

NewReached returns an empty record.

func (*Reached) Has

func (r *Reached) Has(pointer jsontext.Pointer) bool

Has reports whether a lowering resolved a reference to pointer. A nil record has recorded nothing.

type Referenced

type Referenced[T any] interface {
	GetObject() *T
}

Referenced is what Object reads of a reference-or-inline wrapper, each soa "Referenced*" alias and ReferencedMediaType alike: the object an inline one holds. Whether it is a reference, and where its chain ends, the bindings say (typed.Bindings.Reference), never the wrapper, whose resolution the compiler does not use (docs/compilers/openapi.md#references).

type ReferencedMediaType

type ReferencedMediaType = soa.Reference[soa.MediaType, *soa.MediaType, *core.MediaType]

ReferencedMediaType is a content entry OpenAPI 3.2 lets a document write as a Reference Object, or a components/mediaTypes entry, as the library's own Referenced* kinds model the others. The library names no such alias and models neither, so the load phase builds one for each, and the binder reads its $ref as it reads every other kind's (docs/parser-library.md#media-type-references).

type Scope

type Scope struct {
	// SelfPath is where the document being compiled lies, as its references
	// are read against (load.Location), against which a reference's document
	// part is judged internal or external.
	SelfPath string
	// Places is where the compile's files lie, which a document part naming
	// the source is compared by.
	Places *Places
	// Declares holds the names of the component schemas the document declares.
	Declares Names
	// Bindings answers where each reference lands, a schema's $ref or a
	// Reference Object's, as the compiler resolved it (internal/bind), and the
	// models there; nil knows none, so no reference resolves.
	Bindings *typed.Bindings
	// Foreign marks a scope over content another document holds, read where
	// that document holds it (GitHub #762). A reference there is internal only
	// when its document part, resolved against Holder, names the source. Any
	// other names a position in that document or a third.
	Foreign bool
	// Holder is the name the bindings read that document by.
	Holder string
	// Reached records each position in the source a reference ObjectAt follows
	// resolves to; nil records nothing.
	Reached *Reached
}

Scope is what resolving a reference needs to know about the document doing the referencing: which file it is, which component schemas it declares, and where its references land.

Declares is a Names rather than a map because a copied struct shares a map, and a reader has no business writing to one.

func (Scope) ComponentRef

func (s Scope) ComponentRef(pointer jsontext.Pointer) (ir.TypeID, ids.ComponentState)

ComponentRef classifies an internal pointer against the document's component schemas (ids.ComponentState), and returns a NamedComponent's stable named ID: one the document declares, where a name it does not is an UndeclaredComponent, a dangling reference to drop. The ID is rebuilt from the component's canonical name, unescaped then re-escaped by ids.Ptr, not from the incoming pointer text, so a non-canonically escaped reference (`A~B` for a component named "A~B", interned under `A~0B`) still resolves to the interned node.

func (Scope) InDocument

func (s Scope) InDocument(id bind.DocID) Scope

InDocument returns s for reading what document id of the bindings' table holds: the source's own content (InSource), or that document's.

func (Scope) InDocumentOf

func (s Scope) InDocumentOf(js *oas3.JSONSchema[oas3.Referenceable]) Scope

InDocumentOf returns s for reading what js holds, a schema the bindings know, in the document they place it in (InDocument), as where a pointer the source spells passes a reference object into another (GitHub #762); a schema they do not know is read in the source.

func (Scope) InSource

func (s Scope) InSource() Scope

InSource returns s for reading what the source holds, which is never Foreign. A reference read as internal names a position in the source, and what is written there reads its own references as the source's content does, wherever the reference naming it was written.

func (Scope) InternalPointer

func (s Scope) InternalPointer(ref string) (jsontext.Pointer, bool)

InternalPointer returns the same-document JSON pointer a $ref target addresses, and ok=false for a cross-document reference, a bare schema name or a malformed ref. A document part naming this source file is internal (see namesSelf).

It decodes the fragment (fragment.Pointer), since fragments are percent-encoded: comparing them raw missed resolvable references and interned a second node at a named position (GitHub #40).

A `#addr` fragment names a $anchor, not a position, and an ID derived from it would be a path no coordinate spells (GitHub #141).

func (Scope) MappingTarget

func (s Scope) MappingTarget(d *oas3.Discriminator, value string,
) (bind.Position, *oas3.JSONSchema[oas3.Referenceable], bool)

MappingTarget returns where the lowering places what the mapping value of the discriminator d names, read as a $ref written at d is (bind.Mapping), and the schema written there. ok is false for a value that lands on no schema.

func (Scope) NamesReferent

func (s Scope) NamesReferent(js *oas3.JSONSchema[oas3.Referenceable]) bool

NamesReferent reports whether the $ref at js names a schema this compilation can point a TypeRef at, answering what resolveSchemaRef answers without promising anything on the way, since deciding how to lower a schema must not queue nodes as a side effect of asking. resolveSchemaRef reads the registry no more than it does, so the two answer alike in any order.

func (Scope) Target

Target returns where the lowering places what the $ref at js names, as the compiler resolved it: the position its hop lands on (bind.Hop.Target), read through each reference its pointer passes, so a schema reached through an alias is placed where it is declared. ok is false for a $ref that lands on no schema, and one on a loop of $refs, which lands nowhere a type can be read.

func (Scope) TargetAt

TargetAt is TargetSchema with the position the schema is read at, for a reader keeping what it reads of a target per target rather than per use.

func (Scope) TargetSchema

func (s Scope) TargetSchema(js *oas3.JSONSchema[oas3.Referenceable]) *oas3.Schema

TargetSchema returns the schema the chain of references from js ends on when js is a reference site (typed.Bindings.RefSite), so use-site annotations can fall back to the referent, and nil otherwise or where the chain ends on none.

Jump to

Keyboard shortcuts

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