index

package
v0.36.0 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2026 License: MIT Imports: 30 Imported by: 30

Documentation

Overview

Package index builds and queries reference indexes for OpenAPI and JSON Schema documents.

Internal layout

The package is organized around a few cooperating subsystems:

  • SpecIndex owns a single parsed document, its discovered references, derived component maps, counters, and runtime caches.
  • reference extraction walks YAML nodes and records references, inline definitions, and component metadata used later by lookup and resolution.
  • lookup resolves local, external, and schema-id based references. Exact component references use direct map lookups first, with JSONPath-based traversal retained as a fallback.
  • Rolodex coordinates local and remote file systems, external document indexing, and shared reference lookup across multiple indexed documents.
  • Resolver performs circular reference analysis and, when requested, destructive in-place resolution of relative references.

Key invariants

  • Public behavior is preserved through staged internal refactors. Helper extraction and subsystem boundaries should not change external APIs.
  • SpecIndex.Release and Rolodex.Release are responsible for clearing owned runtime state so long-lived processes do not retain unnecessary memory.
  • Common exact component references should avoid JSONPath parsing on the hot path.
  • External lookup must remain safe under concurrent indexing and must not leak locks, response bodies, or in-flight wait state.

When editing this package, prefer extending the existing subsystem seams instead of adding more responsibility to the top-level orchestration files for indexing, rolodex loading, or resolver entry points.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddIndexingFile added in v0.30.0 

func AddIndexingFile(ctx context.Context, filePath string) context.Context

AddIndexingFile adds a file to the indexing set in the context. Returns a new context with the updated set.

func AddResolvingId added in v0.30.5 

func AddResolvingId(ctx context.Context, id string) context.Context

AddResolvingId adds a $id to the resolving set in the context. Returns a new context with the updated set (copy-on-write for thread safety).

func ClearContentDetectionCache added in v0.33.11 

func ClearContentDetectionCache()

ClearContentDetectionCache clears the content detection cache. Call this between document lifecycles in long-running processes to bound memory.

func ClearHashCache added in v0.25.0 

func ClearHashCache()

ClearHashCache clears the hash cache - useful for testing and memory management

func ClearNodePools added in v0.34.0 

func ClearNodePools()

ClearNodePools replaces the sync.Pool instances that hold *yaml.Node pointers with fresh pools. After a document lifecycle ends, pooled slices and maps still reference the parsed YAML tree, preventing GC from collecting it. Call this (via libopenapi.ClearAllCaches) to release those references.

func FindSchemaIdInNode added in v0.33.2 

func FindSchemaIdInNode(node *yaml.Node) string

FindSchemaIdInNode looks for a $id key in a mapping node and returns its value. Returns empty string if not found or if the node is not a mapping.

func GenerateCleanSpecConfigBaseURL added in v0.6.0 

func GenerateCleanSpecConfigBaseURL(baseURL *url.URL, dir string, includeFile bool) string

GenerateCleanSpecConfigBaseURL builds a cleaned base URL by merging the baseURL path with dir, removing duplicate segments. If includeFile is true, the last path segment is preserved.

func GetIndexingFiles added in v0.30.0 

func GetIndexingFiles(ctx context.Context) map[string]bool

GetIndexingFiles returns the set of files currently being indexed in the call chain. Returns nil if not set.

func GetResolvingIds added in v0.30.5 

func GetResolvingIds(ctx context.Context) map[string]bool

GetResolvingIds returns the set of $id values currently being resolved in the call chain.

func HashNode added in v0.19.0 

func HashNode(n *yaml.Node) string

HashNode returns a fast hash string of the node and its children. Uses maphash (same algorithm as Go maps) with WriteString for zero allocations. Iterative traversal avoids recursion overhead.

func HumanFileSize added in v0.13.13 

func HumanFileSize(size float64) string

func IsFileBeingIndexed added in v0.30.0 

func IsFileBeingIndexed(ctx context.Context, filePath string) bool

IsFileBeingIndexed checks if a file is currently being indexed in the call chain. For HTTP URLs, it also checks if the PATH portion matches any indexed file, since the same file might be referenced with different hostnames (which get normalized to a common server).

func IsIdBeingResolved added in v0.30.5 

func IsIdBeingResolved(ctx context.Context, id string) bool

IsIdBeingResolved checks if a $id is currently being resolved in the call chain. Used to detect and prevent circular $id resolution.

func ResolveRefAgainstSchemaId added in v0.30.5 

func ResolveRefAgainstSchemaId(ref string, scope *SchemaIdScope) (string, error)

ResolveRefAgainstSchemaId resolves a $ref value against the current $id scope. Absolute refs are returned as-is; relative refs are resolved against the nearest ancestor $id.

func ResolveReferenceValue added in v0.34.3 

func ResolveReferenceValue(ref string, specIndex *SpecIndex, getDocData func() map[string]interface{}) interface{}

ResolveReferenceValue resolves a reference string to a decoded value.

Resolution order:

  1. Resolve using SpecIndex when available.
  2. Fallback to local JSON pointer resolution (e.g. "#/components/schemas/Foo") using getDocData when provided.

Returns nil when the reference cannot be resolved.

func ResolveRefsInNode added in v0.34.3 

func ResolveRefsInNode(node *yaml.Node, idx *SpecIndex) *yaml.Node

ResolveRefsInNode resolves local $ref values in a YAML node using the provided index. If a mapping contains sibling keys alongside $ref, sibling keys are preserved and merged into the resolved mapping (sibling values take precedence).

func ResolveSchemaId added in v0.30.5 

func ResolveSchemaId(id string, baseUri string) (string, error)

ResolveSchemaId resolves a potentially relative $id against a base URI. Returns the fully resolved absolute URI.

func Round added in v0.13.13 

func Round(val float64, roundOn float64, places int) (newVal float64)

func SplitRefFragment added in v0.30.5 

func SplitRefFragment(ref string) (baseUri string, fragment string)

SplitRefFragment splits a reference into base URI and fragment components. Example: "https://example.com/schema.json#/definitions/Pet" -> baseUri="https://example.com/schema.json", fragment="#/definitions/Pet"

func ValidateSchemaId added in v0.30.5 

func ValidateSchemaId(id string) error

ValidateSchemaId checks if a $id value is valid per JSON Schema 2020-12 spec. Per the spec, $id MUST NOT contain a fragment identifier (#).

func WithSchemaIdScope added in v0.30.5 

func WithSchemaIdScope(ctx context.Context, scope *SchemaIdScope) context.Context

WithSchemaIdScope returns a new context with the given $id scope.

Types

type Cache added in v0.18.5 

type Cache interface {
	SetStore(*sync.Map)
	GetStore() *sync.Map
	AddHit() uint64
	AddMiss() uint64
	GetHits() uint64
	GetMisses() uint64
	Clear()
	Load(any) (any, bool)
	Store(any, any)
}

Cache is an interface for a simple cache that can be used by any consumer.

func CreateNewCache added in v0.18.5 

func CreateNewCache() Cache

CreateNewCache creates a new simple cache with a sync.Map store.

type CanBeIndexed added in v0.13.0 

type CanBeIndexed interface {
	Index(config *SpecIndexConfig) (*SpecIndex, error)
}

CanBeIndexed is an interface that allows a file to be indexed.

type CircularReferenceResult 

type CircularReferenceResult struct {
	Journey             []*Reference
	ParentNode          *yaml.Node
	Start               *Reference
	LoopIndex           int
	LoopPoint           *Reference
	IsArrayResult       bool   // if this result comes from an array loop.
	PolymorphicType     string // which type of polymorphic loop is this? (oneOf, anyOf, allOf)
	IsPolymorphicResult bool   // if this result comes from a polymorphic loop.
	IsInfiniteLoop      bool   // if all the definitions in the reference loop are marked as required, this is an infinite circular reference, thus is not allowed.
}

CircularReferenceResult contains a circular reference found when traversing the graph.

func (*CircularReferenceResult) GenerateJourneyPath added in v0.0.5 

func (c *CircularReferenceResult) GenerateJourneyPath() string

GenerateJourneyPath generates a string representation of the journey taken to find the circular reference.

type ContextKey added in v0.13.0 

type ContextKey string
const (
	CurrentPathKey   ContextKey = "currentPath"
	FoundIndexKey    ContextKey = "foundIndex"
	RootIndexKey     ContextKey = "currentIndex"
	IndexingFilesKey ContextKey = "indexingFiles" // Tracks files being indexed in current call chain
)
const ResolvingIdsKey ContextKey = "resolvingIds"

ResolvingIdsKey is the context key for tracking $id values currently being resolved. 

const SchemaIdScopeKey ContextKey = "schemaIdScope"

SchemaIdScopeKey is the context key for tracking the current $id scope during extraction.

type DescriptionReference 

type DescriptionReference struct {
	Content    string
	Path       string
	KeyNode    *yaml.Node
	Node       *yaml.Node
	ParentNode *yaml.Node
	IsSummary  bool
}

DescriptionReference holds data about a description that was found and where it was found.

type EnumReference 

type EnumReference struct {
	Node       *yaml.Node
	KeyNode    *yaml.Node
	Type       *yaml.Node
	Path       string
	SchemaNode *yaml.Node
	ParentNode *yaml.Node
}

EnumReference holds data about an enum definition found during indexing, including its type, schema node, and location path within the specification.

type ExternalLookupFunction 

type ExternalLookupFunction func(id string) (foundNode *yaml.Node, rootNode *yaml.Node, lookupError error)

ExternalLookupFunction is for lookup functions that take a JSONSchema reference and tries to find that node in the URI based document. Decides if the reference is local, remote or in a file.

type ExtractedRef added in v0.13.0 

type ExtractedRef struct {
	Location string
	Type     RefType
}

ExtractedRef represents a parsed reference with its resolved location and type.

func (*ExtractedRef) GetFile added in v0.13.0 

func (r *ExtractedRef) GetFile() string

GetFile returns the file path of the reference.

func (*ExtractedRef) GetReference added in v0.13.0 

func (r *ExtractedRef) GetReference() string

GetReference returns the reference path of the reference.

type FileExtension added in v0.13.0 

type FileExtension int

FileExtension is the type of file extension. 

const (
	YAML FileExtension = iota
	JSON
	JS
	GO
	TS
	CS
	C
	CPP
	PHP
	PY
	HTML
	MD
	JAVA
	RS
	ZIG
	RB
	UNSUPPORTED
)

func ExtractFileType added in v0.13.0 

func ExtractFileType(ref string) FileExtension

ExtractFileType returns the file extension of the reference.

type IndexingError 

type IndexingError struct {
	Err     error
	Node    *yaml.Node
	KeyNode *yaml.Node
	Path    string
}

IndexingError holds data about something that went wrong during indexing, including the offending node and its path within the specification.

func (*IndexingError) Error 

func (i *IndexingError) Error() string

Error returns the underlying error message.

type LocalFS added in v0.13.0 

type LocalFS struct {
	Files sync.Map
	// contains filtered or unexported fields
}

LocalFS is a file system that indexes local files.

func NewLocalFSWithConfig added in v0.13.0 

func NewLocalFSWithConfig(config *LocalFSConfig) (*LocalFS, error)

NewLocalFSWithConfig creates a new LocalFS with the supplied configuration.

func (*LocalFS) GetErrors added in v0.13.0 

func (l *LocalFS) GetErrors() []error

GetErrors returns any errors that occurred during the indexing process.

func (*LocalFS) GetFiles added in v0.13.0 

func (l *LocalFS) GetFiles() map[string]RolodexFile

GetFiles returns the files that have been indexed. A map of RolodexFile objects keyed by the full path of the file.

func (*LocalFS) Open added in v0.13.0 

func (l *LocalFS) Open(name string) (fs.File, error)

Open opens a file, returning it or an error. If the file is not found, the error is of type *PathError.

func (*LocalFS) OpenWithContext added in v0.23.0 

func (l *LocalFS) OpenWithContext(ctx context.Context, name string) (fs.File, error)

func (*LocalFS) SetLogger added in v0.23.0 

func (l *LocalFS) SetLogger(logger *slog.Logger)

func (*LocalFS) SetRolodex added in v0.23.0 

func (l *LocalFS) SetRolodex(rolodex *Rolodex)

type LocalFSConfig added in v0.13.0 

type LocalFSConfig struct {
	// the base directory to index
	BaseDirectory string

	// supply your own logger
	Logger *slog.Logger

	// supply a list of specific files to index only
	FileFilters []string

	// supply a custom fs.FS to use
	DirFS fs.FS

	// supply an index configuration to use
	IndexConfig *SpecIndexConfig
}

LocalFSConfig is the configuration for the LocalFS.

type LocalFile added in v0.13.0 

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

LocalFile is a file that has been indexed by the LocalFS. It implements the RolodexFile interface.

func (*LocalFile) Close added in v0.13.0 

func (l *LocalFile) Close() error

Close closes the file (doesn't do anything, returns no error)

func (*LocalFile) FullPath added in v0.13.0 

func (l *LocalFile) FullPath() string

FullPath returns the full path of the file.

func (*LocalFile) GetContent added in v0.13.0 

func (l *LocalFile) GetContent() string

GetContent returns the content of the file as a string.

func (*LocalFile) GetContentAsYAMLNode added in v0.13.0 

func (l *LocalFile) GetContentAsYAMLNode() (*yaml.Node, error)

GetContentAsYAMLNode returns the content of the file as a *yaml.Node. If something went wrong then an error is returned.

func (*LocalFile) GetErrors added in v0.13.0 

func (l *LocalFile) GetErrors() []error

GetErrors returns any errors that occurred during the indexing process.

func (*LocalFile) GetFileExtension added in v0.13.0 

func (l *LocalFile) GetFileExtension() FileExtension

GetFileExtension returns the FileExtension of the file.

func (*LocalFile) GetFullPath added in v0.13.0 

func (l *LocalFile) GetFullPath() string

GetFullPath returns the full path of the file.

func (*LocalFile) GetIndex added in v0.13.0 

func (l *LocalFile) GetIndex() *SpecIndex

GetIndex returns the *SpecIndex for the file.

func (*LocalFile) Index added in v0.13.0 

func (l *LocalFile) Index(config *SpecIndexConfig) (*SpecIndex, error)

Index returns the *SpecIndex for the file. If the index has not been created, it will be created (indexed)

func (*LocalFile) IndexWithContext added in v0.23.0 

func (l *LocalFile) IndexWithContext(ctx context.Context, config *SpecIndexConfig) (*SpecIndex, error)

IndexWithContext returns the *SpecIndex for the file. If the index has not been created, it will be created (indexed), also supplied context

func (*LocalFile) IsDir added in v0.13.0 

func (l *LocalFile) IsDir() bool

IsDir returns true if the file is a directory, it always returns false

func (*LocalFile) ModTime added in v0.13.0 

func (l *LocalFile) ModTime() time.Time

ModTime returns the modification time of the file.

func (*LocalFile) Mode added in v0.13.0 

func (l *LocalFile) Mode() fs.FileMode

Mode returns the file mode bits for the file.

func (*LocalFile) Name added in v0.13.0 

func (l *LocalFile) Name() string

Name returns the name of the file.

func (*LocalFile) Read added in v0.13.0 

func (l *LocalFile) Read(b []byte) (int, error)

Read reads the file into a byte slice, makes it compatible with io.Reader.

func (*LocalFile) Size added in v0.13.0 

func (l *LocalFile) Size() int64

Size returns the size of the file.

func (*LocalFile) Stat added in v0.13.0 

func (l *LocalFile) Stat() (fs.FileInfo, error)

Stat returns the FileInfo for the file.

func (*LocalFile) Sys added in v0.13.0 

func (l *LocalFile) Sys() interface{}

Sys returns the underlying data source (always returns nil)

func (*LocalFile) WaitForIndexing added in v0.30.0 

func (l *LocalFile) WaitForIndexing()

WaitForIndexing blocks until the file's index is ready. This is used to coordinate between concurrent goroutines when one is loading a file and another needs to use its index.

type NodeOrigin added in v0.13.12 

type NodeOrigin struct {
	// Node is the node in question (defaults to key node)
	Node *yaml.Node `json:"-"`

	// ValueNode is the value node of the node in question, if has a different origin
	ValueNode *yaml.Node `json:"-"`

	// Line is the original line of where the node was found in the original file
	Line int `json:"line" yaml:"line"`

	// Column is the original column of where the node was found in the original file
	Column int `json:"column" yaml:"column"`

	// LineValue is the line of the value (if the origin of the key and value are different)
	LineValue int `json:"lineValue,omitempty" yaml:"lineValue,omitempty"`

	// ColumnValue is the column of the value (if the origin of the key and value are different)
	ColumnValue int `json:"columnKey,omitempty" yaml:"columnKey,omitempty"`

	// AbsoluteLocation is the absolute path to the reference was extracted from.
	// This can either be an absolute path to a file, or a URL.
	AbsoluteLocation string `json:"absoluteLocation" yaml:"absoluteLocation"`

	// AbsoluteLocationValue is the absolute path to where the ValueNode was extracted from.
	// this only applies when keys and values have different origins.
	AbsoluteLocationValue string `json:"absoluteLocationValue,omitempty" yaml:"absoluteLocationValue,omitempty"`

	// Index is the index that contains the node that was located in.
	Index *SpecIndex `json:"-" yaml:"-"`
}

NodeOrigin represents where a node has come from within a specification. This is not useful for single file specs, but becomes very, very important when dealing with exploded specifications, and we need to know where in the mass of files a node has come from.

type ObjectReference added in v0.4.8 

type ObjectReference struct {
	Node       *yaml.Node
	KeyNode    *yaml.Node
	Path       string
	ParentNode *yaml.Node
}

ObjectReference holds data about an object with properties found during indexing.

type RefType added in v0.13.0 

type RefType int

RefType is an enum identifying the location type of a reference. 

const (
	Local RefType = iota
	File
	HTTP
)

RefType identifies where a reference points to: within the same file (Local), to another file on disk (File), or to a remote URL (HTTP).

type Reference 

type Reference struct {
	FullDefinition        string                `json:"fullDefinition,omitempty"`
	Definition            string                `json:"definition,omitempty"`
	RawRef                string                `json:"-"`
	SchemaIdBase          string                `json:"-"`
	Name                  string                `json:"name,omitempty"`
	Node                  *yaml.Node            `json:"-"`
	KeyNode               *yaml.Node            `json:"-"`
	ParentNode            *yaml.Node            `json:"-"`
	ParentNodeSchemaType  string                `json:"-"` // used to determine if the parent node is an array or not.
	ParentNodeTypes       []string              `json:"-"` // used to capture deep journeys, if any item is an array, we need to know.
	Resolved              bool                  `json:"-"`
	Circular              bool                  `json:"-"`
	Seen                  bool                  `json:"-"`
	IsRemote              bool                  `json:"isRemote,omitempty"`
	IsExtensionRef        bool                  `json:"isExtensionRef,omitempty"` // true if ref is under an x-* extension path
	Index                 *SpecIndex            `json:"-"`                        // index that contains this reference.
	RemoteLocation        string                `json:"remoteLocation,omitempty"`
	Path                  string                `json:"path,omitempty"`               // this won't always be available.
	RequiredRefProperties map[string][]string   `json:"requiredProperties,omitempty"` // definition names (eg, #/definitions/One) to a list of required properties on this definition which reference that definition
	HasSiblingProperties  bool                  `json:"-"`                            // indicates if ref has sibling properties
	SiblingProperties     map[string]*yaml.Node `json:"-"`                            // stores sibling property nodes
	SiblingKeys           []*yaml.Node          `json:"-"`                            // stores sibling key nodes
	In                    string                `json:"-"`                            // parameter location (path, query, header, cookie) - cached for performance
}

Reference is a wrapper around *yaml.Node that tracks a single $ref usage in a specification. It captures the full definition path, the resolved node, parent context, circular reference state, and sibling properties. Used throughout the index for reference resolution and change detection.

func FindComponent added in v0.13.0 

func FindComponent(_ context.Context, root *yaml.Node, componentID, absoluteFilePath string, index *SpecIndex) *Reference

FindComponent locates a component within a specific root YAML node.

The lookup prefers direct fragment navigation and direct component maps first, and falls back to JSONPath traversal for legacy or non-direct component identifiers.

type ReferenceMapped 

type ReferenceMapped struct {
	OriginalReference *Reference `json:"originalReference,omitempty"`
	Reference         *Reference `json:"reference,omitempty"`
	Definition        string     `json:"definition,omitempty"`
	FullDefinition    string     `json:"fullDefinition,omitempty"`
	IsPolymorphic     bool       `json:"isPolymorphic,omitempty"`
}

ReferenceMapped is a helper struct that pairs a mapped reference with its original definition key, preserving insertion order when references are sequenced from a map.

func (*ReferenceMapped) MarshalJSON added in v0.19.0 

func (rm *ReferenceMapped) MarshalJSON() ([]byte, error)

MarshalJSON is a custom JSON marshaller for the ReferenceMapped struct.

type RemoteFS added in v0.13.0 

type RemoteFS struct {
	RemoteHandlerFunc utils.RemoteURLHandler
	Files             sync.Map
	ProcessingFiles   sync.Map
	FetchTime         int64
	FetchChannel      chan *RemoteFile
	// contains filtered or unexported fields
}

RemoteFS is a file system that indexes remote files. It implements the fs.FS interface. Files are located remotely and served via HTTP.

func NewRemoteFSWithConfig added in v0.13.0 

func NewRemoteFSWithConfig(specIndexConfig *SpecIndexConfig) (*RemoteFS, error)

NewRemoteFSWithConfig creates a new RemoteFS using the supplied SpecIndexConfig.

func NewRemoteFSWithRootURL added in v0.13.0 

func NewRemoteFSWithRootURL(rootURL string) (*RemoteFS, error)

NewRemoteFSWithRootURL creates a new RemoteFS using the supplied root URL.

func (*RemoteFS) GetErrors added in v0.13.0 

func (i *RemoteFS) GetErrors() []error

GetErrors returns any errors that occurred during the indexing process.

func (*RemoteFS) GetFiles added in v0.13.0 

func (i *RemoteFS) GetFiles() map[string]RolodexFile

GetFiles returns the files that have been indexed.

func (*RemoteFS) Open added in v0.13.0 

func (i *RemoteFS) Open(remoteURL string) (fs.File, error)

Open opens a file, returning it or an error. If the file is not found, the error is of type *PathError.

func (*RemoteFS) OpenWithContext added in v0.23.0 

func (i *RemoteFS) OpenWithContext(ctx context.Context, remoteURL string) (fs.File, error)

func (*RemoteFS) SetIndexConfig added in v0.13.0 

func (i *RemoteFS) SetIndexConfig(config *SpecIndexConfig)

SetIndexConfig sets the index configuration.

func (*RemoteFS) SetRemoteHandlerFunc added in v0.13.0 

func (i *RemoteFS) SetRemoteHandlerFunc(handlerFunc utils.RemoteURLHandler)

SetRemoteHandlerFunc sets the remote handler function.

type RemoteFile added in v0.13.0 

type RemoteFile struct {
	URL *url.URL
	// contains filtered or unexported fields
}

RemoteFile is a file that has been indexed by the RemoteFS. It implements the RolodexFile interface.

func (*RemoteFile) Close added in v0.13.0 

func (f *RemoteFile) Close() error

Close closes the file (doesn't do anything, returns no error)

func (*RemoteFile) GetContent added in v0.13.0 

func (f *RemoteFile) GetContent() string

GetContent returns the content of the file as a string.

func (*RemoteFile) GetContentAsYAMLNode added in v0.13.0 

func (f *RemoteFile) GetContentAsYAMLNode() (*yaml.Node, error)

GetContentAsYAMLNode returns the content of the file as a yaml.Node.

func (*RemoteFile) GetErrors added in v0.13.0 

func (f *RemoteFile) GetErrors() []error

GetErrors returns any errors that occurred while reading the file.

func (*RemoteFile) GetFileExtension added in v0.13.0 

func (f *RemoteFile) GetFileExtension() FileExtension

GetFileExtension returns the file extension of the file.

func (*RemoteFile) GetFileName added in v0.13.0 

func (f *RemoteFile) GetFileName() string

GetFileName returns the name of the file.

func (*RemoteFile) GetFullPath added in v0.13.0 

func (f *RemoteFile) GetFullPath() string

GetFullPath returns the full path of the file.

func (*RemoteFile) GetIndex added in v0.13.0 

func (f *RemoteFile) GetIndex() *SpecIndex

GetIndex returns the index for the file.

func (*RemoteFile) GetLastModified added in v0.13.0 

func (f *RemoteFile) GetLastModified() time.Time

GetLastModified returns the last modified time of the file.

func (*RemoteFile) Index added in v0.13.0 

func (f *RemoteFile) Index(ctx context.Context, config *SpecIndexConfig) (*SpecIndex, error)

Index indexes the file and returns a *SpecIndex, any errors are returned as well.

func (*RemoteFile) IsDir added in v0.13.0 

func (f *RemoteFile) IsDir() bool

IsDir returns true if the file is a directory.

func (*RemoteFile) ModTime added in v0.13.0 

func (f *RemoteFile) ModTime() time.Time

ModTime returns the modification time of the file.

func (*RemoteFile) Mode added in v0.13.0 

func (f *RemoteFile) Mode() fs.FileMode

Mode returns the file mode bits for the file.

func (*RemoteFile) Name added in v0.13.0 

func (f *RemoteFile) Name() string

Name returns the name of the file.

func (*RemoteFile) Read added in v0.13.0 

func (f *RemoteFile) Read(b []byte) (int, error)

Read reads the file. Makes it compatible with io.Reader.

func (*RemoteFile) Size added in v0.13.0 

func (f *RemoteFile) Size() int64

Size returns the size of the file.

func (*RemoteFile) Stat added in v0.13.0 

func (f *RemoteFile) Stat() (fs.FileInfo, error)

Stat returns the FileInfo for the file.

func (*RemoteFile) Sys added in v0.13.0 

func (f *RemoteFile) Sys() interface{}

Sys returns the underlying data source (always returns nil)

func (*RemoteFile) WaitForIndexing added in v0.30.0 

func (f *RemoteFile) WaitForIndexing()

WaitForIndexing blocks until the file's index is ready. This is used to coordinate between concurrent goroutines when one is loading a file and another needs to use its index.

type Resolver added in v0.13.0 

type Resolver struct {
	IgnorePoly  bool
	IgnoreArray bool
	// contains filtered or unexported fields
}

Resolver uses a SpecIndex to stitch together a resolved root tree from all discovered references, detecting circular references and resolving polymorphic relationships along the way.

func NewResolver added in v0.13.0 

func NewResolver(index *SpecIndex) *Resolver
Example

Example of how to resolve the Stripe OpenAPI specification, and check for circular reference errors 

// create a yaml.Node reference as a root node.
var rootNode yaml.Node

//  load in the Stripe OpenAPI spec (lots of polymorphic complexity in here)
stripeBytes, _ := os.ReadFile("../test_specs/stripe.yaml")

// unmarshal bytes into our rootNode.
_ = yaml.Unmarshal(stripeBytes, &rootNode)

// create a new spec index (resolver depends on it)
indexConfig := CreateClosedAPIIndexConfig()
idx := NewSpecIndexWithConfig(&rootNode, indexConfig)

// create a new resolver using the index.
resolver := NewResolver(idx)

// resolve the document, if there are circular reference errors, they are returned/
// WARNING: this is a destructive action and the rootNode will be PERMANENTLY altered and cannot be unresolved
circularErrors := resolver.Resolve()

// The Stripe API has a bunch of circular reference problems, mainly from polymorphism.
// So let's print them out.
//
fmt.Printf("There is %d circular reference error, %d of them are polymorphic errors, %d are not\n"+
	"with a total pf %d safe circular references.\n",
	len(circularErrors), len(resolver.GetPolymorphicCircularErrors()), len(resolver.GetNonPolymorphicCircularErrors()),
	len(resolver.GetSafeCircularReferences()))

Output:
There is 1 circular reference error, 0 of them are polymorphic errors, 1 are not
with a total pf 25 safe circular references.

func (*Resolver) CheckForCircularReferences added in v0.13.0 

func (resolver *Resolver) CheckForCircularReferences() []*ResolvingError

CheckForCircularReferences walks all references without resolving them, detecting circular reference chains. Returns any resolving errors found, including infinite circular loops.

func (*Resolver) GetCircularReferences added in v0.13.0 

func (resolver *Resolver) GetCircularReferences() []*CircularReferenceResult

func (*Resolver) GetIgnoredCircularArrayReferences added in v0.13.0 

func (resolver *Resolver) GetIgnoredCircularArrayReferences() []*CircularReferenceResult

func (*Resolver) GetIgnoredCircularPolyReferences added in v0.13.0 

func (resolver *Resolver) GetIgnoredCircularPolyReferences() []*CircularReferenceResult

func (*Resolver) GetIndexesVisited added in v0.13.0 

func (resolver *Resolver) GetIndexesVisited() int

func (*Resolver) GetInfiniteCircularReferences added in v0.13.0 

func (resolver *Resolver) GetInfiniteCircularReferences() []*CircularReferenceResult

func (*Resolver) GetJourneysTaken added in v0.13.0 

func (resolver *Resolver) GetJourneysTaken() int

func (*Resolver) GetNonPolymorphicCircularErrors added in v0.13.0 

func (resolver *Resolver) GetNonPolymorphicCircularErrors() []*CircularReferenceResult

func (*Resolver) GetPolymorphicCircularErrors added in v0.13.0 

func (resolver *Resolver) GetPolymorphicCircularErrors() []*CircularReferenceResult

func (*Resolver) GetReferenceVisited added in v0.13.0 

func (resolver *Resolver) GetReferenceVisited() int

func (*Resolver) GetRelativesSeen added in v0.13.0 

func (resolver *Resolver) GetRelativesSeen() int

func (*Resolver) GetResolvingErrors added in v0.13.0 

func (resolver *Resolver) GetResolvingErrors() []*ResolvingError

func (*Resolver) GetSafeCircularReferences added in v0.13.0 

func (resolver *Resolver) GetSafeCircularReferences() []*CircularReferenceResult

func (*Resolver) IgnoreArrayCircularReferences added in v0.13.0 

func (resolver *Resolver) IgnoreArrayCircularReferences()

func (*Resolver) IgnorePolymorphicCircularReferences added in v0.13.0 

func (resolver *Resolver) IgnorePolymorphicCircularReferences()

func (*Resolver) Release added in v0.34.0 

func (resolver *Resolver) Release()

func (*Resolver) Resolve added in v0.13.0 

func (resolver *Resolver) Resolve() []*ResolvingError

func (*Resolver) ResolvePendingNodes added in v0.13.21 

func (resolver *Resolver) ResolvePendingNodes()

ResolvePendingNodes applies deferred node content replacements that were collected during resolution.

func (*Resolver) VisitReference added in v0.13.0 

func (resolver *Resolver) VisitReference(ref *Reference, seen map[string]bool, journey []*Reference, resolve bool) []*yaml.Node

VisitReference visits a single reference, collecting its relatives (dependencies) and recursively visiting them. The seen map prevents infinite loops, journey tracks the path for circular detection, and resolve controls whether nodes are actually resolved or just visited for analysis.

type ResolvingError added in v0.13.0 

type ResolvingError struct {
	ErrorRef error
	Node     *yaml.Node
	Path     string

	// CircularReference is the detected circular reference result, if this error relates to one.
	CircularReference *CircularReferenceResult
}

ResolvingError represents an issue the resolver had trying to stitch the tree together.

Example 
re := ResolvingError{
	ErrorRef: errors.New("je suis une erreur"),
	Node: &yaml.Node{
		Line:   5,
		Column: 21,
	},
	Path:              "#/definitions/JeSuisUneErreur",
	CircularReference: &CircularReferenceResult{},
}

fmt.Printf("%s", re.Error())

Output:
je suis une erreur: #/definitions/JeSuisUneErreur [5:21]

func (*ResolvingError) Error added in v0.13.0 

func (r *ResolvingError) Error() string

type Rolodex added in v0.13.0 

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

Rolodex is a file system abstraction that allows for the indexing of multiple file systems and the ability to resolve references across those file systems. It is used to hold references to external files, and the indexes they hold. The rolodex is the master lookup for all references.

func NewRolodex added in v0.13.0 

func NewRolodex(indexConfig *SpecIndexConfig) *Rolodex

NewRolodex creates a new rolodex with the provided index configuration.

func (*Rolodex) AddExternalIndex added in v0.13.12 

func (r *Rolodex) AddExternalIndex(idx *SpecIndex, location string)

func (*Rolodex) AddIndex added in v0.13.12 

func (r *Rolodex) AddIndex(idx *SpecIndex)

func (*Rolodex) AddLocalFS added in v0.13.0 

func (r *Rolodex) AddLocalFS(baseDir string, fileSystem fs.FS)

AddLocalFS adds a local file system to the rolodex.

func (*Rolodex) AddRemoteFS added in v0.13.0 

func (r *Rolodex) AddRemoteFS(baseURL string, fileSystem fs.FS)

AddRemoteFS adds a remote file system to the rolodex.

func (*Rolodex) BuildIndexes added in v0.13.0 

func (r *Rolodex) BuildIndexes()

BuildIndexes builds the indexes in the rolodex, this is generally not required unless manually building a rolodex.

func (*Rolodex) CheckForCircularReferences added in v0.13.0 

func (r *Rolodex) CheckForCircularReferences()

CheckForCircularReferences checks for circular references in the rolodex.

func (*Rolodex) ClearIndexCaches added in v0.18.5 

func (r *Rolodex) ClearIndexCaches()

func (*Rolodex) FindNodeOrigin added in v0.13.12 

func (r *Rolodex) FindNodeOrigin(node *yaml.Node) *NodeOrigin

FindNodeOrigin searches all indexes for the origin of a node. If the node is found, a NodeOrigin is returned, otherwise nil is returned.

func (*Rolodex) FindNodeOriginWithValue added in v0.19.0 

func (r *Rolodex) FindNodeOriginWithValue(key, value, refNode *yaml.Node, refValue string) *NodeOrigin

FindNodeOriginWithValue searches all indexes for the origin of a node with a specific value. If the node is found, a NodeOrigin is returned, otherwise nil is returned. The key and the value have to be provided. If the refNode and refValue are provided, the returned value will be the key origin, not the value origin.

func (*Rolodex) GetAllGlobalSchemaIds added in v0.30.5 

func (r *Rolodex) GetAllGlobalSchemaIds() map[string]*SchemaIdEntry

GetAllGlobalSchemaIds returns a copy of all registered $id entries across all indexes.

func (*Rolodex) GetAllMappedReferences added in v0.18.0 

func (r *Rolodex) GetAllMappedReferences() map[string]*Reference

GetAllMappedReferences returns all mapped references found in the root and all other indices

func (*Rolodex) GetAllReferences added in v0.18.0 

func (r *Rolodex) GetAllReferences() map[string]*Reference

GetAllReferences returns all references found in the root and all other indices

func (*Rolodex) GetCaughtErrors added in v0.13.0 

func (r *Rolodex) GetCaughtErrors() []error

GetCaughtErrors returns all the errors that were caught during the indexing process.

func (*Rolodex) GetConfig added in v0.16.12 

func (r *Rolodex) GetConfig() *SpecIndexConfig

GetConfig returns the index configuration of the rolodex.

func (*Rolodex) GetFullLineCount added in v0.18.0 

func (r *Rolodex) GetFullLineCount() int64

GetFullLineCount returns the total number of lines from all files in the Rolodex

func (*Rolodex) GetId added in v0.23.0 

func (r *Rolodex) GetId() string

GetId returns the unique ID for the rolodex.

func (*Rolodex) GetIgnoredCircularReferences added in v0.13.0 

func (r *Rolodex) GetIgnoredCircularReferences() []*CircularReferenceResult

GetIgnoredCircularReferences returns a list of circular references that were ignored during the indexing process. These can be an array or polymorphic references. Will return an empty slice if no ignored circular references are found.

func (*Rolodex) GetIndexes added in v0.13.0 

func (r *Rolodex) GetIndexes() []*SpecIndex

GetIndexes returns all the indexes in the rolodex.

func (*Rolodex) GetIndexingDuration added in v0.13.0 

func (r *Rolodex) GetIndexingDuration() time.Duration

GetIndexingDuration returns the duration it took to index the rolodex.

func (*Rolodex) GetRootIndex added in v0.13.0 

func (r *Rolodex) GetRootIndex() *SpecIndex

GetRootIndex returns the root index of the rolodex (the entry point, the main document)

func (*Rolodex) GetRootNode added in v0.13.3 

func (r *Rolodex) GetRootNode() *yaml.Node

GetRootNode returns the root node of the rolodex (the entry point, the main document)

func (*Rolodex) GetSafeCircularReferences added in v0.19.0 

func (r *Rolodex) GetSafeCircularReferences() []*CircularReferenceResult

GetSafeCircularReferences returns a list of circular references that were found to be safe during the indexing process. These can be an array or polymorphic references. Will return an empty slice if no safe circular references are found.

func (*Rolodex) IndexTheRolodex added in v0.13.0 

func (r *Rolodex) IndexTheRolodex(ctx context.Context) error

IndexTheRolodex indexes the rolodex, building out the indexes for each file, and then building the root index.

func (*Rolodex) LookupSchemaById added in v0.30.5 

func (r *Rolodex) LookupSchemaById(uri string) *SchemaIdEntry

LookupSchemaById looks up a schema by its $id URI across all indexes.

func (*Rolodex) Open added in v0.13.0 

func (r *Rolodex) Open(location string) (RolodexFile, error)

Open opens a file in the rolodex, and returns a RolodexFile.

func (*Rolodex) OpenWithContext added in v0.23.0 

func (r *Rolodex) OpenWithContext(ctx context.Context, location string) (RolodexFile, error)

OpenWithContext opens a file in the rolodex, and returns a RolodexFile - providing a context. The method supports both custom file systems (like LocalFS) and standard fs.FS implementations. For standard fs.FS implementations, paths are automatically converted to relative paths as required by the fs.FS interface specification (which mandates relative, slash-separated paths).

func (*Rolodex) RegisterGlobalSchemaId added in v0.30.5 

func (r *Rolodex) RegisterGlobalSchemaId(entry *SchemaIdEntry) error

RegisterGlobalSchemaId registers a schema $id in the Rolodex global registry. Returns an error if the $id is invalid.

func (*Rolodex) RegisterIdsFromIndex added in v0.30.5 

func (r *Rolodex) RegisterIdsFromIndex(idx *SpecIndex)

RegisterIdsFromIndex aggregates all $id registrations from an index into the global registry. Called after each index is built to populate the Rolodex global registry.

func (*Rolodex) Release added in v0.34.0 

func (r *Rolodex) Release()

Release nils all fields that can pin YAML node trees, SpecIndex objects, or circular reference results in memory. Acquires locks for fields that are protected elsewhere. Call this once all consumers of the rolodex are finished.

func (*Rolodex) Resolve added in v0.13.0 

func (r *Rolodex) Resolve()

Resolve resolves references in the rolodex.

func (*Rolodex) RolodexFileSize added in v0.13.13 

func (r *Rolodex) RolodexFileSize() int64

func (*Rolodex) RolodexFileSizeAsString added in v0.13.13 

func (r *Rolodex) RolodexFileSizeAsString() string

func (*Rolodex) RolodexTotalFiles added in v0.13.13 

func (r *Rolodex) RolodexTotalFiles() int

func (*Rolodex) RotateId added in v0.23.0 

func (r *Rolodex) RotateId() string

RotateId generates a new unique ID for the rolodex.

func (*Rolodex) SetRootIndex added in v0.23.0 

func (r *Rolodex) SetRootIndex(rootIndex *SpecIndex)

SetRootIndex sets the root index of the rolodex (the entry point, the main document).

func (*Rolodex) SetRootNode added in v0.13.0 

func (r *Rolodex) SetRootNode(node *yaml.Node)

SetRootNode sets the root node of the rolodex (the entry point, the main document)

func (*Rolodex) SetSafeCircularReferences added in v0.23.0 

func (r *Rolodex) SetSafeCircularReferences(refs []*CircularReferenceResult)

SetSafeCircularReferences sets the safe circular references for the rolodex.

type RolodexFS added in v0.13.0 

type RolodexFS interface {
	Open(name string) (fs.File, error)
	GetFiles() map[string]RolodexFile
}

RolodexFS is an interface that represents a RolodexFS, is the same interface as `fs.FS`, except it also exposes a GetFiles() signature, to extract all files in the FS.

type RolodexFSWithContext added in v0.23.0 

type RolodexFSWithContext interface {
	OpenWithContext(ctx context.Context, name string) (fs.File, error)
}

RolodexFSWithContext is an interface like fs.FS, but with a context parameter for the Open method.

type RolodexFile added in v0.13.0 

type RolodexFile interface {
	GetContent() string
	GetFileExtension() FileExtension
	GetFullPath() string
	GetErrors() []error
	GetContentAsYAMLNode() (*yaml.Node, error)
	GetIndex() *SpecIndex
	// WaitForIndexing blocks until the file's index is ready.
	// This is used to coordinate between concurrent goroutines when one is loading
	// a file and another needs to use its index.
	WaitForIndexing()
	Name() string
	ModTime() time.Time
	IsDir() bool
	Sys() any
	Size() int64
	Mode() os.FileMode
}

RolodexFile is an interface that represents a file in the rolodex. It combines multiple `fs` interfaces like `fs.FileInfo` and `fs.File` into one interface, so the same struct can be used for everything.

type Rolodexable added in v0.23.0 

type Rolodexable interface {
	SetRolodex(rolodex *Rolodex)
	SetLogger(logger *slog.Logger)
}

type SchemaIdEntry added in v0.30.5 

type SchemaIdEntry struct {
	Id             string     // The $id value as declared in the schema
	ResolvedUri    string     // Fully resolved absolute URI after applying base URI resolution
	SchemaNode     *yaml.Node // The YAML node containing the schema with this $id
	ParentId       string     // The $id of the parent scope (for nested schemas with $id)
	Index          *SpecIndex // Reference to the SpecIndex containing this schema
	DefinitionPath string     // JSON pointer path to this schema (e.g., #/components/schemas/Pet)
	Line           int        // Line number where $id was declared (for error reporting)
	Column         int        // Column number where $id was declared (for error reporting)
}

SchemaIdEntry represents a schema registered by its JSON Schema 2020-12 $id. This enables $ref resolution against $id values per JSON Schema specification.

func (*SchemaIdEntry) GetKey added in v0.30.5 

func (e *SchemaIdEntry) GetKey() string

GetKey returns the registry key for this entry. Uses ResolvedUri if available, otherwise falls back to Id.

type SchemaIdScope added in v0.30.5 

type SchemaIdScope struct {
	BaseUri string   // Current base URI for relative $id and $ref resolution
	Chain   []string // Stack of $id URIs from root to current location
}

SchemaIdScope tracks the resolution context during tree walking. Used to maintain the base URI hierarchy when extracting $id values.

func GetSchemaIdScope added in v0.30.5 

func GetSchemaIdScope(ctx context.Context) *SchemaIdScope

GetSchemaIdScope returns the current $id scope from the context.

func NewSchemaIdScope added in v0.30.5 

func NewSchemaIdScope(baseUri string) *SchemaIdScope

NewSchemaIdScope initializes scope tracking for base URI resolution during schema tree traversal.

func (*SchemaIdScope) Copy added in v0.30.5 

func (s *SchemaIdScope) Copy() *SchemaIdScope

Copy creates an independent scope for exploring alternative branches without affecting the parent scope's state (used in anyOf/oneOf/allOf traversal).

func (*SchemaIdScope) PopId added in v0.30.5 

func (s *SchemaIdScope) PopId()

PopId restores the previous base URI when exiting a schema scope.

func (*SchemaIdScope) PushId added in v0.30.5 

func (s *SchemaIdScope) PushId(id string)

PushId updates the base URI context when entering a schema with $id. The new $id becomes the base for resolving relative references in child schemas.

type SimpleCache added in v0.18.5 

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

SimpleCache is a simple cache for the index, or any other consumer that needs it.

func (*SimpleCache) AddHit added in v0.18.5 

func (c *SimpleCache) AddHit() uint64

AddHit increments the hit counter by one, and returns the current value of hits.

func (*SimpleCache) AddMiss added in v0.18.5 

func (c *SimpleCache) AddMiss() uint64

AddMiss increments the miss counter by one, and returns the current value of misses.

func (*SimpleCache) Clear added in v0.18.5 

func (c *SimpleCache) Clear()

Clear clears the cache.

func (*SimpleCache) GetHits added in v0.18.5 

func (c *SimpleCache) GetHits() uint64

GetHits returns the current value of hits.

func (*SimpleCache) GetMisses added in v0.18.5 

func (c *SimpleCache) GetMisses() uint64

GetMisses returns the current value of misses.

func (*SimpleCache) GetStore added in v0.18.5 

func (c *SimpleCache) GetStore() *sync.Map

GetStore returns the store for the cache.

func (*SimpleCache) Load added in v0.18.5 

func (c *SimpleCache) Load(key any) (value any, ok bool)

Load retrieves a value from the cache.

func (*SimpleCache) SetStore added in v0.18.5 

func (c *SimpleCache) SetStore(store *sync.Map)

SetStore sets the store for the cache.

func (*SimpleCache) Store added in v0.18.5 

func (c *SimpleCache) Store(key, value any)

Store stores a key-value pair in the cache.

type SpecIndex 

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

SpecIndex is a complete pre-computed index of the entire specification. Numbers are pre-calculated and quick direct access to paths, operations, tags are all available. No need to walk the entire node tree in rules, everything is pre-walked if you need it.

func NewSpecIndex 

func NewSpecIndex(rootNode *yaml.Node) *SpecIndex

NewSpecIndex creates a new SpecIndex with default configuration from the given root YAML node.

Example

Example of how to load in an OpenAPI Specification and index it. 

// define a rootNode to hold our raw spec AST.
var rootNode yaml.Node

// load in the stripe OpenAPI specification into bytes (it's pretty meaty)
stripeSpec, _ := os.ReadFile("../test_specs/stripe.yaml")

// unmarshal spec into our rootNode
_ = yaml.Unmarshal(stripeSpec, &rootNode)

// create a new specification index.
index := NewSpecIndexWithConfig(&rootNode, CreateOpenAPIIndexConfig())

// print out some statistics
fmt.Printf("There are %d references\n"+
	"%d paths\n"+
	"%d operations\n"+
	"%d component schemas\n"+
	"%d reference schemas\n"+
	"%d inline schemas\n"+
	"%d inline schemas that are objects or arrays\n"+
	"%d total schemas\n"+
	"%d enums\n"+
	"%d polymorphic references",
	len(index.GetAllCombinedReferences()),
	len(index.GetAllPaths()),
	index.GetOperationCount(),
	len(index.GetAllComponentSchemas()),
	len(index.GetAllReferenceSchemas()),
	len(index.GetAllInlineSchemas()),
	len(index.GetAllInlineSchemaObjects()),
	len(index.GetAllSchemas()),
	len(index.GetAllEnums()),
	len(index.GetPolyOneOfReferences())+len(index.GetPolyAnyOfReferences()))

Output:
There are 871 references
336 paths
494 operations
871 component schemas
2712 reference schemas
15928 inline schemas
3857 inline schemas that are objects or arrays
19511 total schemas
2579 enums
1023 polymorphic references

func NewSpecIndexWithConfig added in v0.6.0 

func NewSpecIndexWithConfig(rootNode *yaml.Node, config *SpecIndexConfig) *SpecIndex

NewSpecIndexWithConfig creates a new SpecIndex from the given root YAML node and configuration, using a background context.

func NewSpecIndexWithConfigAndContext added in v0.23.0 

func NewSpecIndexWithConfigAndContext(ctx context.Context, rootNode *yaml.Node, config *SpecIndexConfig) *SpecIndex

NewSpecIndexWithConfigAndContext creates a new SpecIndex from the given root YAML node and configuration. The context is passed through to reference extraction for schema ID scope tracking.

func (*SpecIndex) AllowCircularReferenceResolving added in v0.0.5 

func (index *SpecIndex) AllowCircularReferenceResolving() bool

AllowCircularReferenceResolving returns whether circular reference resolving is enabled.

func (*SpecIndex) BuildIndex added in v0.9.0 

func (index *SpecIndex) BuildIndex()

BuildIndex runs all count and extraction functions concurrently to populate the index. This is called automatically during construction unless AvoidBuildIndex is set in the config.

func (*SpecIndex) ExtractComponentsFromRefs 

func (index *SpecIndex) ExtractComponentsFromRefs(ctx context.Context, refs []*Reference) []*Reference

func (*SpecIndex) ExtractExternalDocuments 

func (index *SpecIndex) ExtractExternalDocuments(node *yaml.Node) []*Reference

ExtractExternalDocuments recursively searches the YAML tree for externalDocs objects and returns references to each one found.

func (*SpecIndex) ExtractRefs 

func (index *SpecIndex) ExtractRefs(ctx context.Context, node, parent *yaml.Node, seenPath []string, level int, poly bool, pName string) []*Reference

ExtractRefs will return a deduplicated slice of references for every unique ref found in the document. The total number of refs, will generally be much higher, you can extract those from GetRawReferenceCount()

func (*SpecIndex) FindComponent 

func (index *SpecIndex) FindComponent(ctx context.Context, componentId string) *Reference

FindComponent locates a component in the index by reference.

It resolves local references directly from the current document first, then recurses through rolodex-backed file and remote references as needed. It returns nil when the target cannot be found.

func (*SpecIndex) FindComponentInRoot added in v0.0.5 

func (index *SpecIndex) FindComponentInRoot(ctx context.Context, componentID string) *Reference

FindComponentInRoot locates a component reference in the current root document only.

It normalizes file-prefixed local references back to root-document fragments before delegating to FindComponent.

func (*SpecIndex) FindNodeOrigin added in v0.13.12 

func (index *SpecIndex) FindNodeOrigin(node *yaml.Node) *NodeOrigin

FindNodeOrigin searches this index for a matching node. If the node is found, a NodeOrigin is returned, otherwise nil is returned.

func (*SpecIndex) GetAllCallbacks 

func (index *SpecIndex) GetAllCallbacks() map[string]*Reference

GetAllCallbacks returns all callback definitions from the components section.

func (*SpecIndex) GetAllCombinedReferences 

func (index *SpecIndex) GetAllCombinedReferences() map[string]*Reference

GetAllCombinedReferences returns a merged map of all standard and polymorphic references.

func (*SpecIndex) GetAllComponentPathItems added in v0.21.9 

func (index *SpecIndex) GetAllComponentPathItems() map[string]*Reference

GetAllComponentPathItems returns all path item definitions from the components section.

func (*SpecIndex) GetAllComponentSchemas added in v0.5.0 

func (index *SpecIndex) GetAllComponentSchemas() map[string]*Reference

GetAllComponentSchemas returns all component schema definitions, converting from the internal sync.Map on first access and caching the result.

func (*SpecIndex) GetAllDescriptions 

func (index *SpecIndex) GetAllDescriptions() []*DescriptionReference

GetAllDescriptions returns all description nodes found during indexing.

func (*SpecIndex) GetAllDescriptionsCount 

func (index *SpecIndex) GetAllDescriptionsCount() int

GetAllDescriptionsCount returns the total number of description nodes found during indexing.

func (*SpecIndex) GetAllEnums 

func (index *SpecIndex) GetAllEnums() []*EnumReference

GetAllEnums returns all enum definitions found during indexing.

func (*SpecIndex) GetAllExamples 

func (index *SpecIndex) GetAllExamples() map[string]*Reference

GetAllExamples returns all example definitions from the components section.

func (*SpecIndex) GetAllExternalDocuments 

func (index *SpecIndex) GetAllExternalDocuments() map[string]*Reference

GetAllExternalDocuments returns all external document references found in the specification.

func (*SpecIndex) GetAllHeaders 

func (index *SpecIndex) GetAllHeaders() map[string]*Reference

GetAllHeaders returns all header definitions from the components section.

func (*SpecIndex) GetAllInlineSchemaObjects added in v0.5.0 

func (index *SpecIndex) GetAllInlineSchemaObjects() []*Reference

GetAllInlineSchemaObjects returns all inline schema definitions that are objects.

func (*SpecIndex) GetAllInlineSchemas added in v0.5.0 

func (index *SpecIndex) GetAllInlineSchemas() []*Reference

GetAllInlineSchemas returns all inline schema definitions found during extraction. 

func (index *SpecIndex) GetAllLinks() map[string]*Reference

GetAllLinks returns all link definitions from the components section.

func (*SpecIndex) GetAllObjectsWithProperties added in v0.4.8 

func (index *SpecIndex) GetAllObjectsWithProperties() []*ObjectReference

GetAllObjectsWithProperties returns all objects that have a "properties" keyword.

func (*SpecIndex) GetAllOperationsServers 

func (index *SpecIndex) GetAllOperationsServers() map[string]map[string][]*Reference

GetAllOperationsServers returns server references keyed by path, then HTTP method.

func (*SpecIndex) GetAllParameters 

func (index *SpecIndex) GetAllParameters() map[string]*Reference

GetAllParameters returns all parameter definitions from the components section.

func (*SpecIndex) GetAllParametersFromOperations 

func (index *SpecIndex) GetAllParametersFromOperations() map[string]map[string]map[string][]*Reference

GetAllParametersFromOperations returns all parameters keyed by path, HTTP method, then parameter name.

func (*SpecIndex) GetAllPaths 

func (index *SpecIndex) GetAllPaths() map[string]map[string]*Reference

GetAllPaths returns all path items keyed by path, then HTTP method.

func (*SpecIndex) GetAllReferenceSchemas added in v0.9.8 

func (index *SpecIndex) GetAllReferenceSchemas() []*Reference

GetAllReferenceSchemas returns all schema definitions that are $ref references.

func (*SpecIndex) GetAllReferences 

func (index *SpecIndex) GetAllReferences() map[string]*Reference

GetAllReferences returns all deduplicated references found during extraction.

func (*SpecIndex) GetAllRequestBodies 

func (index *SpecIndex) GetAllRequestBodies() map[string]*Reference

GetAllRequestBodies returns all request body definitions from the components section.

func (*SpecIndex) GetAllResponses 

func (index *SpecIndex) GetAllResponses() map[string]*Reference

GetAllResponses returns all response definitions from the components section.

func (*SpecIndex) GetAllRootServers 

func (index *SpecIndex) GetAllRootServers() []*Reference

GetAllRootServers returns all server references from the top-level "servers" array.

func (*SpecIndex) GetAllSchemaIds added in v0.30.5 

func (index *SpecIndex) GetAllSchemaIds() map[string]*SchemaIdEntry

GetAllSchemaIds returns a copy of all $id entries registered in this index.

func (*SpecIndex) GetAllSchemas 

func (index *SpecIndex) GetAllSchemas() []*Reference

GetAllSchemas returns all schemas (component, inline, and reference) sorted by line number.

func (*SpecIndex) GetAllSecuritySchemes 

func (index *SpecIndex) GetAllSecuritySchemes() map[string]*Reference

GetAllSecuritySchemes returns all security scheme definitions from the components section.

func (*SpecIndex) GetAllSequencedReferences 

func (index *SpecIndex) GetAllSequencedReferences() []*Reference

GetAllSequencedReferences returns all raw references in scan order.

func (*SpecIndex) GetAllSummaries 

func (index *SpecIndex) GetAllSummaries() []*DescriptionReference

GetAllSummaries returns all summary nodes found during indexing.

func (*SpecIndex) GetAllSummariesCount 

func (index *SpecIndex) GetAllSummariesCount() int

GetAllSummariesCount returns the total number of summary nodes found during indexing.

func (*SpecIndex) GetCache added in v0.13.0 

func (index *SpecIndex) GetCache() *sync.Map

GetCache returns the reference lookup cache used during resolution.

func (*SpecIndex) GetCircularReferences added in v0.0.5 

func (index *SpecIndex) GetCircularReferences() []*CircularReferenceResult

GetCircularReferences returns all circular references found during resolution.

func (*SpecIndex) GetComponentParameterCount 

func (index *SpecIndex) GetComponentParameterCount() int

GetComponentParameterCount returns the number of component-level parameter definitions.

func (*SpecIndex) GetComponentSchemaCount 

func (index *SpecIndex) GetComponentSchemaCount() int

GetComponentSchemaCount extracts and counts all component schemas, parameters, request bodies, responses, security schemes, headers, examples, links, callbacks, and path items from the specification. Also handles Swagger 2.0 "definitions" and "securityDefinitions" sections.

func (*SpecIndex) GetConfig added in v0.12.1 

func (index *SpecIndex) GetConfig() *SpecIndexConfig

GetConfig returns the SpecIndexConfig for this index.

func (*SpecIndex) GetDiscoveredReferences 

func (index *SpecIndex) GetDiscoveredReferences() map[string]*Reference

GetDiscoveredReferences returns all deduplicated references found during extraction, keyed by their full definition path.

func (*SpecIndex) GetExtensionRefsSequenced added in v0.30.0 

func (index *SpecIndex) GetExtensionRefsSequenced() []*Reference

GetExtensionRefsSequenced returns only references that appear under x-* extension paths, in scan order.

func (*SpecIndex) GetGlobalCallbacksCount added in v0.0.5 

func (index *SpecIndex) GetGlobalCallbacksCount() int

GetGlobalCallbacksCount returns the total number of callback objects found across all operations.

func (*SpecIndex) GetGlobalLinksCount 

func (index *SpecIndex) GetGlobalLinksCount() int

GetGlobalLinksCount returns the total number of link objects found across all operations.

func (*SpecIndex) GetGlobalTagsCount 

func (index *SpecIndex) GetGlobalTagsCount() int

GetGlobalTagsCount returns the number of top-level tags and also extracts tag references and checks for circular parent references. Returns -1 if root is nil.

func (*SpecIndex) GetGlobalTagsNode 

func (index *SpecIndex) GetGlobalTagsNode() *yaml.Node

GetGlobalTagsNode returns the raw YAML node for the top-level "tags" array.

func (*SpecIndex) GetHighCache added in v0.18.5 

func (index *SpecIndex) GetHighCache() Cache

GetHighCache returns the high model cache for this index.

func (*SpecIndex) GetHighCacheHits added in v0.18.5 

func (index *SpecIndex) GetHighCacheHits() uint64

GetHighCacheHits returns the number of hits on the high model cache.

func (*SpecIndex) GetHighCacheMisses added in v0.18.5 

func (index *SpecIndex) GetHighCacheMisses() uint64

GetHighCacheMisses returns the number of misses on the high model cache.

func (*SpecIndex) GetIgnoredArrayCircularReferences added in v0.15.0 

func (index *SpecIndex) GetIgnoredArrayCircularReferences() []*CircularReferenceResult

GetIgnoredArrayCircularReferences returns circular references that were ignored because they involve array items.

func (*SpecIndex) GetIgnoredPolymorphicCircularReferences added in v0.15.0 

func (index *SpecIndex) GetIgnoredPolymorphicCircularReferences() []*CircularReferenceResult

GetIgnoredPolymorphicCircularReferences returns circular references that were ignored because they involve polymorphic keywords.

func (*SpecIndex) GetInlineDuplicateParamCount 

func (index *SpecIndex) GetInlineDuplicateParamCount() int

GetInlineDuplicateParamCount returns the number of inline parameters that have duplicate names.

func (*SpecIndex) GetInlineOperationDuplicateParameters 

func (index *SpecIndex) GetInlineOperationDuplicateParameters() map[string][]*Reference

GetInlineOperationDuplicateParameters returns parameters with duplicate names found inline in operations.

func (*SpecIndex) GetInlineUniqueParamCount 

func (index *SpecIndex) GetInlineUniqueParamCount() int

GetInlineUniqueParamCount returns the number of unique inline parameter names.

func (*SpecIndex) GetLinesWithReferences 

func (index *SpecIndex) GetLinesWithReferences() map[int]bool

GetLinesWithReferences returns a set of line numbers that contain at least one reference.

func (*SpecIndex) GetLogger added in v0.13.0 

func (index *SpecIndex) GetLogger() *slog.Logger

GetLogger returns the structured logger used by this index.

func (*SpecIndex) GetMappedReferences 

func (index *SpecIndex) GetMappedReferences() map[string]*Reference

GetMappedReferences returns all resolved component references keyed by definition path.

func (*SpecIndex) GetMappedReferencesSequenced 

func (index *SpecIndex) GetMappedReferencesSequenced() []*ReferenceMapped

GetMappedReferencesSequenced returns all resolved component references in deterministic order.

func (*SpecIndex) GetNode added in v0.13.12 

func (index *SpecIndex) GetNode(line int, column int) (*yaml.Node, bool)

GetNode returns a node from the spec based on a line and column. The second return var bool is true if the node was found, false if not.

func (*SpecIndex) GetNodeMap added in v0.15.0 

func (index *SpecIndex) GetNodeMap() map[int]map[int]*yaml.Node

GetNodeMap returns the line-to-column-to-node map built during indexing.

func (*SpecIndex) GetOperationCount 

func (index *SpecIndex) GetOperationCount() int

GetOperationCount returns the total number of operations across all paths and extracts path-level and operation-level references (methods, tags, descriptions, summaries, servers).

func (*SpecIndex) GetOperationParameterReferences 

func (index *SpecIndex) GetOperationParameterReferences() map[string]map[string]map[string][]*Reference

GetOperationParameterReferences returns parameters keyed by path, then HTTP method, then parameter name.

func (*SpecIndex) GetOperationParametersIndexErrors 

func (index *SpecIndex) GetOperationParametersIndexErrors() []error

GetOperationParametersIndexErrors returns any errors found when scanning operation parameters.

func (*SpecIndex) GetOperationTags 

func (index *SpecIndex) GetOperationTags() map[string]map[string][]*Reference

GetOperationTags returns tags keyed by path, then HTTP method.

func (*SpecIndex) GetOperationTagsCount 

func (index *SpecIndex) GetOperationTagsCount() int

GetOperationTagsCount returns the number of unique tags referenced across all operations.

func (*SpecIndex) GetOperationsParameterCount 

func (index *SpecIndex) GetOperationsParameterCount() int

GetOperationsParameterCount scans all path items and operations to count parameters, extract tags, descriptions, summaries, and servers. Also builds the inline parameter deduplication maps.

func (*SpecIndex) GetParametersNode 

func (index *SpecIndex) GetParametersNode() *yaml.Node

GetParametersNode returns the raw YAML node for the components/parameters section.

func (*SpecIndex) GetPathCount 

func (index *SpecIndex) GetPathCount() int

GetPathCount returns the number of paths defined in the specification. Returns -1 if root is nil.

func (*SpecIndex) GetPathsNode 

func (index *SpecIndex) GetPathsNode() *yaml.Node

GetPathsNode returns the raw YAML node for the top-level "paths" object.

func (*SpecIndex) GetPolyAllOfReferences 

func (index *SpecIndex) GetPolyAllOfReferences() []*Reference

GetPolyAllOfReferences returns all references found under allOf keywords.

func (*SpecIndex) GetPolyAnyOfReferences 

func (index *SpecIndex) GetPolyAnyOfReferences() []*Reference

GetPolyAnyOfReferences returns all references found under anyOf keywords.

func (*SpecIndex) GetPolyOneOfReferences 

func (index *SpecIndex) GetPolyOneOfReferences() []*Reference

GetPolyOneOfReferences returns all references found under oneOf keywords.

func (*SpecIndex) GetPolyReferences 

func (index *SpecIndex) GetPolyReferences() map[string]*Reference

GetPolyReferences returns all polymorphic references (allOf, oneOf, anyOf) keyed by definition.

func (*SpecIndex) GetRawReferenceCount 

func (index *SpecIndex) GetRawReferenceCount() int

GetRawReferenceCount returns the total number of raw (non-deduplicated) references found.

func (*SpecIndex) GetRawReferencesSequenced added in v0.15.0 

func (index *SpecIndex) GetRawReferencesSequenced() []*Reference

GetRawReferencesSequenced returns all raw references in the order they were scanned.

func (*SpecIndex) GetReferenceIndexErrors added in v0.0.5 

func (index *SpecIndex) GetReferenceIndexErrors() []error

GetReferenceIndexErrors returns any errors that occurred during reference extraction.

func (*SpecIndex) GetReferencesWithSiblings 

func (index *SpecIndex) GetReferencesWithSiblings() map[string]Reference

GetReferencesWithSiblings returns references that have sibling properties alongside the $ref keyword.

func (*SpecIndex) GetRefsByLine 

func (index *SpecIndex) GetRefsByLine() map[string]map[int]bool

GetRefsByLine returns a map of reference definition to the set of line numbers where it appears.

func (*SpecIndex) GetResolver added in v0.13.0 

func (index *SpecIndex) GetResolver() *Resolver

GetResolver returns the resolver for this index.

func (*SpecIndex) GetRolodex added in v0.13.12 

func (index *SpecIndex) GetRolodex() *Rolodex

GetRolodex returns the Rolodex file system abstraction associated with this index.

func (*SpecIndex) GetRootNode 

func (index *SpecIndex) GetRootNode() *yaml.Node

GetRootNode returns the root YAML node of the specification document.

func (*SpecIndex) GetRootSecurityNode 

func (index *SpecIndex) GetRootSecurityNode() *yaml.Node

GetRootSecurityNode returns the raw YAML node for the top-level "security" array.

func (*SpecIndex) GetRootSecurityReferences 

func (index *SpecIndex) GetRootSecurityReferences() []*Reference

GetRootSecurityReferences returns references from the top-level security requirement array.

func (*SpecIndex) GetRootServersNode 

func (index *SpecIndex) GetRootServersNode() *yaml.Node

GetRootServersNode returns the raw YAML node for the top-level "servers" array.

func (*SpecIndex) GetSchemaById added in v0.30.5 

func (index *SpecIndex) GetSchemaById(uri string) *SchemaIdEntry

GetSchemaById looks up a schema by its resolved $id URI in this index's local registry.

func (*SpecIndex) GetSchemasNode 

func (index *SpecIndex) GetSchemasNode() *yaml.Node

GetSchemasNode returns the raw YAML node for the components/schemas (or definitions) section.

func (*SpecIndex) GetSecurityRequirementReferences added in v0.1.4 

func (index *SpecIndex) GetSecurityRequirementReferences() map[string]map[string][]*Reference

GetSecurityRequirementReferences returns security requirements keyed by security scheme name.

func (*SpecIndex) GetSpecAbsolutePath added in v0.13.0 

func (index *SpecIndex) GetSpecAbsolutePath() string

GetSpecAbsolutePath returns the absolute path to the spec file for the index. Will be absolute, either as a http link or a file.

func (*SpecIndex) GetSpecFileName added in v0.18.0 

func (index *SpecIndex) GetSpecFileName() string

GetSpecFileName returns the base filename of the specification (e.g. "openapi.yaml"). Falls back to "root.yaml" if no file path is configured.

func (*SpecIndex) GetTagCircularReferences added in v0.24.0 

func (index *SpecIndex) GetTagCircularReferences() []*CircularReferenceResult

GetTagCircularReferences returns circular references found in tag parent hierarchies.

func (*SpecIndex) GetTotalTagsCount 

func (index *SpecIndex) GetTotalTagsCount() int

GetTotalTagsCount returns the combined count of unique global and operation tags.

func (*SpecIndex) HighCacheHit added in v0.18.5 

func (index *SpecIndex) HighCacheHit() uint64

HighCacheHit increments the counter of high cache hits by one, and returns the current value of hits.

func (*SpecIndex) HighCacheMiss added in v0.18.5 

func (index *SpecIndex) HighCacheMiss() uint64

HighCacheMiss increments the counter of high cache misses by one, and returns the current value of misses.

func (*SpecIndex) InitHighCache added in v0.21.7 

func (index *SpecIndex) InitHighCache()

InitHighCache allocates a new high model cache onto the index.

func (*SpecIndex) MapNodes added in v0.13.12 

func (index *SpecIndex) MapNodes(rootNode *yaml.Node)

MapNodes maps all nodes in the document to a map of line/column to node. Writes directly to index.nodeMap with lock protection (concurrent reads may happen from ExtractRefs running in parallel).

func (*SpecIndex) RegisterSchemaId added in v0.30.5 

func (index *SpecIndex) RegisterSchemaId(entry *SchemaIdEntry) error

RegisterSchemaId registers a JSON Schema $id entry in this index's local registry.

func (*SpecIndex) Release added in v0.34.0 

func (index *SpecIndex) Release()

Release nils every field on SpecIndex that can pin YAML node trees, Reference maps, or large caches in memory. Call this once all consumers of the index are finished so the GC can reclaim the underlying data even if an interface value or escaped closure still holds a pointer to the SpecIndex struct itself.

func (*SpecIndex) ResolveRefViaSchemaId added in v0.30.5 

func (index *SpecIndex) ResolveRefViaSchemaId(ref string) *Reference

ResolveRefViaSchemaId attempts to resolve a $ref via the $id registry. Implements JSON Schema 2020-12 $id-based resolution: 1. Split ref into base URI and fragment 2. Look up base URI in $id registry 3. Navigate to fragment within found schema if present Returns nil if the ref cannot be resolved via $id.

func (*SpecIndex) ResolveRelativeFilePath added in v0.33.3 

func (index *SpecIndex) ResolveRelativeFilePath(defRoot, ref string) string

ResolveRelativeFilePath is a public wrapper for resolving local file references.

func (*SpecIndex) SearchIndexForReference added in v0.6.0 

func (index *SpecIndex) SearchIndexForReference(ref string) (*Reference, *SpecIndex)

SearchIndexForReference searches the index for a reference, first looking through the mapped references and then externalSpecIndex for a match. If no match is found, it will recursively search the child indexes extracted when parsing the OpenAPI Spec.

func (*SpecIndex) SearchIndexForReferenceByReference added in v0.13.0 

func (index *SpecIndex) SearchIndexForReferenceByReference(fullRef *Reference) (*Reference, *SpecIndex)

SearchIndexForReferenceByReference searches the index for a matching reference using a background context.

func (*SpecIndex) SearchIndexForReferenceByReferenceWithContext added in v0.13.0 

func (index *SpecIndex) SearchIndexForReferenceByReferenceWithContext(ctx context.Context, searchRef *Reference) (*Reference, *SpecIndex, context.Context)

func (*SpecIndex) SearchIndexForReferenceWithContext added in v0.13.0 

func (index *SpecIndex) SearchIndexForReferenceWithContext(ctx context.Context, ref string) (*Reference, *SpecIndex, context.Context)

SearchIndexForReferenceWithContext searches the index for a reference string with context for schema ID tracking.

func (*SpecIndex) SetAbsolutePath added in v0.13.12 

func (index *SpecIndex) SetAbsolutePath(absolutePath string)

SetAbsolutePath sets the absolute path to the spec file for the index. Will be absolute, either as a http link or a file.

func (*SpecIndex) SetAllowCircularReferenceResolving added in v0.0.5 

func (index *SpecIndex) SetAllowCircularReferenceResolving(allow bool)

SetAllowCircularReferenceResolving sets whether circular references should be resolved instead of returning an error.

func (*SpecIndex) SetCache added in v0.13.0 

func (index *SpecIndex) SetCache(sync *sync.Map)

SetCache sets a sync map as a temporary cache for the index.

func (*SpecIndex) SetCircularReferences added in v0.0.5 

func (index *SpecIndex) SetCircularReferences(refs []*CircularReferenceResult)

SetCircularReferences sets the circular reference results for this index.

func (*SpecIndex) SetHighCache added in v0.18.5 

func (index *SpecIndex) SetHighCache(cache *SimpleCache)

SetHighCache sets the high model cache for this index.

func (*SpecIndex) SetIgnoredArrayCircularReferences added in v0.15.0 

func (index *SpecIndex) SetIgnoredArrayCircularReferences(refs []*CircularReferenceResult)

SetIgnoredArrayCircularReferences sets circular references that were ignored because they involve array items.

func (*SpecIndex) SetIgnoredPolymorphicCircularReferences added in v0.15.0 

func (index *SpecIndex) SetIgnoredPolymorphicCircularReferences(refs []*CircularReferenceResult)

SetIgnoredPolymorphicCircularReferences sets circular references that were ignored because they involve polymorphic keywords (allOf, oneOf, anyOf).

func (*SpecIndex) SetMappedReferences added in v0.22.0 

func (index *SpecIndex) SetMappedReferences(mappedRefs map[string]*Reference)

SetMappedReferences replaces the mapped references for this index.

func (*SpecIndex) SetResolver added in v0.23.0 

func (index *SpecIndex) SetResolver(resolver *Resolver)

SetResolver sets the resolver for this index.

func (*SpecIndex) SetRolodex added in v0.23.0 

func (index *SpecIndex) SetRolodex(rolodex *Rolodex)

SetRolodex sets the Rolodex file system abstraction for this index.

func (*SpecIndex) SetRootNode added in v0.23.0 

func (index *SpecIndex) SetRootNode(node *yaml.Node)

SetRootNode sets the root YAML node for this index.

type SpecIndexConfig added in v0.6.0 

type SpecIndexConfig struct {
	// The BaseURL will be the root from which relative references will be resolved from if they can't be found locally.
	//
	// For example:
	//  - $ref: somefile.yaml#/components/schemas/SomeSchema
	//
	// Might not be found locally, if the file was pulled in from a remote server (a good example is the DigitalOcean API).
	// so by setting a BaseURL, the reference will try to be resolved from the remote server.
	//
	// If our baseURL is set to https://pb33f.io/libopenapi then our reference will try to be resolved from:
	//  - $ref: https://pb33f.io/libopenapi/somefile.yaml#/components/schemas/SomeSchema
	//
	// More details on relative references can be found in issue #73: https://github.com/pb33f/libopenapi/issues/73
	BaseURL *url.URL // set the Base URL for resolving relative references if the spec is exploded.

	// If resolving remotely, the RemoteURLHandler will be used to fetch the remote document.
	// If not set, the default http client will be used.
	// Resolves [#132]: https://github.com/pb33f/libopenapi/issues/132
	// Deprecated: Use the Rolodex instead.
	RemoteURLHandler func(url string) (*http.Response, error)

	// FSHandler is an entity that implements the `fs.FS` interface that will be used to fetch local or remote documents.
	// This is useful if you want to use a custom file system handler, or if you want to use a custom http client or
	// custom network implementation for a lookup.
	//
	// libopenapi will pass the path to the FSHandler, and it will be up to the handler to determine how to fetch
	// the document. This is really useful if your application has a custom file system or uses a database for storing
	// documents.
	//
	// If the FSHandler is set, it will be used for all lookups, regardless of whether they are local or remote.
	// It also overrides the RemoteURLHandler if set.
	//
	// Resolves [#85]: https://github.com/pb33f/libopenapi/issues/85
	// Deprecated: Use the Rolodex instead.
	FSHandler fs.FS

	// If resolving locally, the BasePath will be the root from which relative references will be resolved from
	BasePath string // set the Base Path for resolving relative references if the spec is exploded.

	// SpecFilePath is the name of the root specification file (usually named "openapi.yaml").
	SpecFilePath string

	// In an earlier version of libopenapi (pre 0.6.0) the index would automatically resolve all references
	// They could have been local, or they could have been remote. This was a problem because it meant
	// There was a potential for a remote exploit if a remote reference was malicious. There aren't any known
	// exploits, but it's better to be safe than sorry.
	//
	// To read more about this, you can find a discussion here: https://github.com/pb33f/libopenapi/pull/64
	AllowRemoteLookup bool // Allow remote lookups for references. Defaults to false
	AllowFileLookup   bool // Allow file lookups for references. Defaults to false

	// If set to true, the index will not be built out, which means only the foundational elements will be
	// parsed and added to the index. This is useful to avoid building out an index if the specification is
	// broken up into references and want it fully resolved.
	//
	// Use the `BuildIndex()` method on the index to build it out once resolved/ready.
	AvoidBuildIndex bool

	// If set to true, the index will not check for circular references automatically, this should be triggered
	// manually, otherwise resolving may explode.
	AvoidCircularReferenceCheck bool

	// Logger is a logger that will be used for logging errors and warnings. If not set, the default logger
	// will be used, set to the Error level.
	Logger *slog.Logger

	// SpecInfo is a pointer to the SpecInfo struct that contains the root node and the spec version. It's the
	// struct that was used to create this index.
	SpecInfo *datamodel.SpecInfo

	// Rolodex is what provides all file and remote based lookups. Without the rolodex, no remote or file lookups
	// can be used. Normally you won't need to worry about setting this as each root document gets a rolodex
	// of its own automatically.
	Rolodex *Rolodex

	// The absolute path to the spec file for the index. Will be absolute, either as a http link or a file.
	// If the index is for a single file spec, then the root will be empty.
	SpecAbsolutePath string

	// IgnorePolymorphicCircularReferences will skip over checking for circular references in polymorphic schemas.
	// A polymorphic schema is any schema that is composed other schemas using references via `oneOf`, `anyOf` of `allOf`.
	// This is disabled by default, which means polymorphic circular references will be checked.
	IgnorePolymorphicCircularReferences bool

	// IgnoreArrayCircularReferences will skip over checking for circular references in arrays. Sometimes a circular
	// reference is required to describe a data-shape correctly. Often those shapes are valid circles if the
	// type of the schema implementing the loop is an array. An empty array would technically break the loop.
	// So if libopenapi is returning circular references for this use case, then this option should be enabled.
	// this is disabled by default, which means array circular references will be checked.
	IgnoreArrayCircularReferences bool

	// SkipDocumentCheck will skip the document check when building the index. A document check will look for an 'openapi'
	// or 'swagger' node in the root of the document. If it's not found, then the document is not a valid OpenAPI or
	// the file is a JSON Schema. To allow JSON Schema files to be included set this to true.
	SkipDocumentCheck bool

	// SkipExternalRefResolution will skip resolving external $ref references (those not starting with #).
	// When enabled, external references will be left as-is during model building.
	SkipExternalRefResolution bool

	// ExtractRefsSequentially will extract all references sequentially, which means the index will look up references
	// as it finds them, vs looking up everything asynchronously.
	// This is a more thorough way of building the index, but it's slower. It's required building a document
	// to be bundled.
	ExtractRefsSequentially bool

	// ExcludeExtensionReferences will prevent the indexing of any $ref pointers buried under extensions.
	// defaults to false (which means extensions will be included)
	ExcludeExtensionRefs bool

	// UseSchemaQuickHash will use a quick hash to determine if a schema is the same as another schema if its a reference.
	// This is important when a root / entry document does not have a components/schemas node, and schemas are defined in
	// external documents. Enabling this will allow the what-changed module to perform deeper schema reference checks.
	// -- IMPORTANT --
	// Enabling this (default is false) will stop changes from being detected if a schema is circular.
	// As identified in https://github.com/pb33f/libopenapi/pull/441
	// So, in the edge case where you have circular references in your root / entry components/schemas and you also
	// want changes in them to be picked up, then you should not enable this.
	UseSchemaQuickHash bool

	// AllowUnknownExtensionContentDetection will enable content detection for remote URLs that don't have
	// a known file extension. When enabled, libopenapi will fetch the first 1-2KB of unknown URLs to determine
	// if they contain valid JSON or YAML content. This is disabled by default for security and performance.
	//
	// If disabled, URLs without recognized extensions (.yaml, .yml, .json) will be rejected.
	// If enabled, unknown URLs will be fetched and analyzed for JSON/YAML content with retry logic.
	AllowUnknownExtensionContentDetection bool

	// TransformSiblingRefs enables OpenAPI 3.1/JSON Schema Draft 2020-12 compliance for sibling refs.
	// When enabled, schemas with $ref and additional properties will be transformed to use allOf.
	TransformSiblingRefs bool

	// MergeReferencedProperties enables merging of properties from referenced schemas with local properties.
	// When enabled, properties from referenced schemas will be merged with local sibling properties.
	MergeReferencedProperties bool

	// ResolveNestedRefsWithDocumentContext uses the referenced document's path/index as the base for any nested refs.
	// This is disabled by default to preserve historical resolver behavior.
	ResolveNestedRefsWithDocumentContext bool

	// PropertyMergeStrategy defines how to handle conflicts when merging properties.
	PropertyMergeStrategy datamodel.PropertyMergeStrategy
	// contains filtered or unexported fields
}

SpecIndexConfig is a configuration struct for the SpecIndex introduced in 0.6.0 that provides an expandable set of granular options. The first being the ability to set the Base URL for resolving relative references, and allowing or disallowing remote or local file lookups.

func CreateClosedAPIIndexConfig added in v0.6.0 

func CreateClosedAPIIndexConfig() *SpecIndexConfig

CreateClosedAPIIndexConfig is a helper function to create a new SpecIndexConfig with the AllowRemoteLookup and AllowFileLookup set to false. This is the default behavior of the index in versions 0.6.0+

The default BasePath is the current working directory.

func CreateOpenAPIIndexConfig added in v0.6.0 

func CreateOpenAPIIndexConfig() *SpecIndexConfig

CreateOpenAPIIndexConfig is a helper function to create a new SpecIndexConfig with the AllowRemoteLookup and AllowFileLookup set to true. This is the default behavior of the index in previous versions of libopenapi. (pre 0.6.0)

The default BasePath is the current working directory.

func (*SpecIndexConfig) GetId added in v0.23.0 

func (s *SpecIndexConfig) GetId() string

GetId returns the id of the SpecIndexConfig. If the id is not set, it will generate a random alphanumeric string

func (*SpecIndexConfig) SetTheoreticalRoot added in v0.18.0 

func (s *SpecIndexConfig) SetTheoreticalRoot()

SetTheoreticalRoot sets the spec file paths to point to a theoretical spec file, which does not exist but is required 

to formulate the absolute path to root references correctly.

func (*SpecIndexConfig) ToDocumentConfiguration added in v0.27.0 

func (s *SpecIndexConfig) ToDocumentConfiguration() *datamodel.DocumentConfiguration

ToDocumentConfiguration converts SpecIndexConfig to DocumentConfiguration for compatibility

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.