goai

type AcceptanceSecurityRule struct {
	// TypeName is matched against the unqualified Go type name of each
	// acceptance in the chain. Match is case-sensitive substring; the first
	// acceptance whose type name contains TypeName wins.
	TypeName string
	Scheme   string
	Scopes   []string
}

type BuildOptions struct {
	Title          string
	Description    string
	Version        string
	TermsOfService string
	Contact        *Contact
	License        *License
	Servers        []Server
	Tags           []Tag
	GlobalSecurity []map[string][]string
	// ExternalDocs populates the top-level Document.ExternalDocs.
	ExternalDocs *ExternalDocumentation
	// Classifier returns the set of profile names a candidate belongs to
	// when the candidate did not declare any via ProfileScope. nil means
	// "use BuiltinClassify".
	Classifier func(c OperationCandidate) []string
	// TagSecurityClassifier provides default tags + security refs when a
	// candidate has no explicit Spec entry. nil means "use DefaultClassifier".
	TagSecurityClassifier *Classifier
	// SuppressEmptySchemas, when true, omits the application/json content
	// block on responses where the registered response type is nil. This
	// produces tighter yaml for operations without registered response types.
	SuppressEmptySchemas bool
	// OperationDocExtractor, when non-nil, is consulted as a fallback
	// source for operation-level OpenAPI metadata. Explicit Spec values,
	// route-derived parameters, generated schemas, and acceptance-derived
	// security always win; docstring content fills gaps.
	//
	// Use DefaultOperationDocExtractor() to enable the built-in AST-based
	// implementation. nil disables the fallback.
	OperationDocExtractor OperationDocExtractor
}

type Callback map[string]*PathItem

type Classifier struct {
	// PathTagRules maps a path-prefix glob to a tag name. The first matching
	// rule wins; "**" matches anything.
	PathTagRules []PathTagRule
	// AcceptanceSecurityRules maps an acceptance type-name suffix to a
	// (scheme, scopes) pair. The first matching rule per acceptance wins.
	// Type-name suffix is matched case-sensitively against the unqualified
	// Go type name of the acceptance value.
	AcceptanceSecurityRules []AcceptanceSecurityRule
}

type Components struct {
	Schemas         map[string]*Schema         `yaml:"schemas,omitempty"`
	Responses       map[string]*Response       `yaml:"responses,omitempty"`
	Parameters      map[string]*Parameter      `yaml:"parameters,omitempty"`
	Examples        map[string]*Example        `yaml:"examples,omitempty"`
	RequestBodies   map[string]*RequestBody    `yaml:"requestBodies,omitempty"`
	Headers         map[string]*Header         `yaml:"headers,omitempty"`
	SecuritySchemes map[string]*SecurityScheme `yaml:"securitySchemes,omitempty"`
	Links           map[string]*Link           `yaml:"links,omitempty"`
	Callbacks       map[string]Callback        `yaml:"callbacks,omitempty"`
	Extensions      map[string]any             `yaml:",inline,omitempty"`
}

type Config struct {
	Title           string                     `yaml:"title,omitempty"`
	Description     string                     `yaml:"description,omitempty"`
	Version         string                     `yaml:"version,omitempty"`
	TermsOfService  string                     `yaml:"termsOfService,omitempty"`
	Contact         *Contact                   `yaml:"contact,omitempty"`
	License         *License                   `yaml:"license,omitempty"`
	ExternalDocs    *ExternalDocumentation     `yaml:"externalDocs,omitempty"`
	Servers         []Server                   `yaml:"servers,omitempty"`
	Tags            []Tag                      `yaml:"tags,omitempty"`
	GlobalSecurity  []map[string][]string      `yaml:"security,omitempty"`
	SecuritySchemes map[string]*SecurityScheme `yaml:"securitySchemes,omitempty"`

	// DefaultOutput is the single-output target used when neither Profiles
	// nor Output declare anything. Empty falls back to "openapi.generated.yaml".
	DefaultOutput string `yaml:"defaultOutput,omitempty"`

	// BaseSpecPath, when set, enables three-way merge with the hand-tuned
	// base yaml.
	BaseSpecPath string `yaml:"baseSpecPath,omitempty"`

	// RestrictToBaseSpecPaths constrains the generator to paths already
	// declared in the base spec.
	RestrictToBaseSpecPaths bool `yaml:"restrictToBaseSpecPaths,omitempty"`

	// ExcludePaths is the framework-level path blocklist (static assets,
	// well-known framework routes, …). Per-handler exclusion belongs on the
	// handler itself via the Hidden interface.
	ExcludePaths []string `yaml:"excludePaths,omitempty"`

	// Profiles is keyed by profile name and contains include/exclude rules.
	Profiles map[string]ConfigProfile `yaml:"profiles,omitempty"`
	// Output describes where to write each profile's yaml. Keyed by profile
	// name; value is a relative path from the config file's directory.
	Output map[string]string `yaml:"output,omitempty"`

	// EnableDocstringExtraction toggles source-level Go doc-comment
	// extraction for operation-level OpenAPI metadata. When true,
	// RunCLIFromConfig wires DefaultOperationDocExtractorWithBuildTags()
	// into the build pipeline, which reads only namespaced handler
	// `@goai.*` directives. Ordinary Go comments remain source-only.
	// Explicit Spec values, route-derived parameters, generated schemas, and
	// acceptance-derived security continue to win; docstring extraction
	// only fills gaps.
	EnableDocstringExtraction bool `yaml:"enableDocstringExtraction,omitempty"`
	// DocstringBuildTags are passed to DefaultOperationDocExtractorWithBuildTags
	// when EnableDocstringExtraction is true. Use this when handler docs or
	// schema structs live in files guarded by custom Go build tags.
	DocstringBuildTags []string `yaml:"docstringBuildTags,omitempty"`
}

type ConfigProfile struct {
	Include Selector `yaml:"include,omitempty"`
	Exclude Selector `yaml:"exclude,omitempty"`
}

type Contact struct {
	Name       string         `yaml:"name,omitempty"`
	URL        string         `yaml:"url,omitempty"`
	Email      string         `yaml:"email,omitempty"`
	Extensions map[string]any `yaml:",inline,omitempty"`
}

type CreateSpecProvider interface {
	GOAICreateSpec() Spec
}

type DeleteSpecProvider interface {
	GOAIDeleteSpec() Spec
}

type Discriminator struct {
	PropertyName string            `yaml:"propertyName"`
	Mapping      map[string]string `yaml:"mapping,omitempty"`
}

type Document struct {
	OpenAPI      string                 `yaml:"openapi"`
	Info         Info                   `yaml:"info"`
	Servers      []Server               `yaml:"servers,omitempty"`
	Tags         []Tag                  `yaml:"tags,omitempty"`
	Paths        map[string]*PathItem   `yaml:"paths"`
	Components   *Components            `yaml:"components,omitempty"`
	Security     []map[string][]string  `yaml:"security,omitempty"`
	ExternalDocs *ExternalDocumentation `yaml:"externalDocs,omitempty"`
	Extensions   map[string]any         `yaml:",inline,omitempty"`
}

type EmissionAwareParamInjector interface {
	InjectedParamsForEmission(routePath string, ctx EmissionContext) []PathParam
}

type EmissionContext struct {
	HTTPMethod string
	GoMethod   string
	ItemLevel  bool
}

type Encoding struct {
	ContentType   string             `yaml:"contentType,omitempty"`
	Headers       map[string]*Header `yaml:"headers,omitempty"`
	Style         string             `yaml:"style,omitempty"`
	Explode       *bool              `yaml:"explode,omitempty"`
	AllowReserved bool               `yaml:"allowReserved,omitempty"`
	Extensions    map[string]any     `yaml:",inline,omitempty"`
}

type Entry struct {
	Handler  ghttp.HandlerTask
	Method   string // upper-case HTTP method
	ReqType  reflect.Type
	RespType reflect.Type
	Spec     Spec
}

type Example struct {
	Summary       string         `yaml:"summary,omitempty"`
	Description   string         `yaml:"description,omitempty"`
	Value         any            `yaml:"value,omitempty"`
	ExternalValue string         `yaml:"externalValue,omitempty"`
	Extensions    map[string]any `yaml:",inline,omitempty"`
}

type ExternalDocumentation struct {
	Description string         `yaml:"description,omitempty"`
	URL         string         `yaml:"url"`
	Extensions  map[string]any `yaml:",inline,omitempty"`
}

type GetSpecProvider interface {
	GOAIGetSpec() Spec
}

type Header struct {
	Description     string                `yaml:"description,omitempty"`
	Required        bool                  `yaml:"required,omitempty"`
	Deprecated      bool                  `yaml:"deprecated,omitempty"`
	AllowEmptyValue bool                  `yaml:"allowEmptyValue,omitempty"`
	Style           string                `yaml:"style,omitempty"`
	Explode         *bool                 `yaml:"explode,omitempty"`
	AllowReserved   bool                  `yaml:"allowReserved,omitempty"`
	Schema          *Schema               `yaml:"schema,omitempty"`
	Example         any                   `yaml:"example,omitempty"`
	Examples        map[string]*Example   `yaml:"examples,omitempty"`
	Content         map[string]*MediaType `yaml:"content,omitempty"`
	Extensions      map[string]any        `yaml:",inline,omitempty"`
}

type HeaderDef struct {
	Name        string
	In          string // "header" | "response"
	Description string
	Required    bool
	Example     string
}

type Hidden interface {
	Hidden() bool
}

type IndexSpecProvider interface {
	GOAIIndexSpec() Spec
}

type Info struct {
	Title          string         `yaml:"title"`
	Description    string         `yaml:"description,omitempty"`
	TermsOfService string         `yaml:"termsOfService,omitempty"`
	Contact        *Contact       `yaml:"contact,omitempty"`
	License        *License       `yaml:"license,omitempty"`
	Version        string         `yaml:"version"`
	Extensions     map[string]any `yaml:",inline,omitempty"`
}

type ItemIDProvider interface {
	GOAIItemIDName() string
}

type License struct {
	Name       string         `yaml:"name"`
	URL        string         `yaml:"url,omitempty"`
	Extensions map[string]any `yaml:",inline,omitempty"`
}

type Link struct {
	OperationRef string         `yaml:"operationRef,omitempty"`
	OperationID  string         `yaml:"operationId,omitempty"`
	Parameters   map[string]any `yaml:"parameters,omitempty"`
	RequestBody  any            `yaml:"requestBody,omitempty"`
	Description  string         `yaml:"description,omitempty"`
	Server       *Server        `yaml:"server,omitempty"`
	Extensions   map[string]any `yaml:",inline,omitempty"`
}

type LintReport struct {
	Errors     []string
	Paths      int
	Operations int
}

type MediaType struct {
	Schema     *Schema              `yaml:"schema,omitempty"`
	Example    any                  `yaml:"example,omitempty"`
	Examples   map[string]*Example  `yaml:"examples,omitempty"`
	Encoding   map[string]*Encoding `yaml:"encoding,omitempty"`
	Extensions map[string]any       `yaml:",inline,omitempty"`
}

type MethodAwareSecurityProvider interface {
	SecurityRequirementFor(method string) (scheme string, scopes []string)
}

type OAuthFlow struct {
	AuthorizationURL string            `yaml:"authorizationUrl,omitempty"`
	TokenURL         string            `yaml:"tokenUrl,omitempty"`
	RefreshURL       string            `yaml:"refreshUrl,omitempty"`
	Scopes           map[string]string `yaml:"scopes,omitempty"`
	Extensions       map[string]any    `yaml:",inline,omitempty"`
}

type OAuthFlows struct {
	Implicit          *OAuthFlow     `yaml:"implicit,omitempty"`
	Password          *OAuthFlow     `yaml:"password,omitempty"`
	ClientCredentials *OAuthFlow     `yaml:"clientCredentials,omitempty"`
	AuthorizationCode *OAuthFlow     `yaml:"authorizationCode,omitempty"`
	Extensions        map[string]any `yaml:",inline,omitempty"`
}

type Operation struct {
	Tags         []string               `yaml:"tags,omitempty"`
	Summary      string                 `yaml:"summary,omitempty"`
	Description  string                 `yaml:"description,omitempty"`
	ExternalDocs *ExternalDocumentation `yaml:"externalDocs,omitempty"`
	OperationID  string                 `yaml:"operationId,omitempty"`
	Parameters   []*Parameter           `yaml:"parameters,omitempty"`
	RequestBody  *RequestBody           `yaml:"requestBody,omitempty"`
	Responses    map[string]*Response   `yaml:"responses,omitempty"`
	Callbacks    map[string]Callback    `yaml:"callbacks,omitempty"`
	Deprecated   bool                   `yaml:"deprecated,omitempty"`
	// Security is a pointer so the encoder can distinguish three states:
	//   nil          → inherit document-level Security (default).
	//   &[]          → explicit "no security required"; overrides document
	//                  default with an empty array per OpenAPI 3.0.3.
	//   &[{...}, ..] → operation-level requirement set; overrides document
	//                  default with the supplied alternatives.
	Security   *[]map[string][]string `yaml:"security,omitempty"`
	Servers    []Server               `yaml:"servers,omitempty"`
	Extensions map[string]any         `yaml:",inline,omitempty"`
}

type OperationCandidate struct {
	Path        string
	Method      string
	Handler     ghttp.HandlerTask
	Acceptances []ghttp.Acceptance
	// HandlerMethod is the Go method name (Index/Get/Post/Patch/Put/Delete/
	// Options/Create) that produced this candidate. Builder uses it together
	// with Method to choose registry lookup keys and operationId components.
	HandlerMethod string
	// PathParams collected from upstream PathParamInjectors plus any leaf id
	// the walker auto-appends (item-level operations get an "id" path param).
	PathParams []PathParam
	// SecurityRefs collected from upstream SecurityProviders.
	SecurityRefs []SecurityRef
	// SecurityExplicitlyEmpty is true when at least one acceptance
	// implements MethodAwareSecurityProvider AND its generic
	// SecurityProvider would have advertised a scheme, but its method-aware
	// variant returned ("", nil) for this candidate's HTTP method. The
	// builder uses it to emit `security: []` so that the operation
	// overrides any document-level GlobalSecurity inheritance.
	SecurityExplicitlyEmpty bool
	// Profiles aggregated from ProfileScope-implementing nodes; empty means
	// "let the classifier decide".
	Profiles []string
}

type OperationDoc struct {
	Endpoint       OperationEndpoint
	Operation      Operation
	Schemas        map[string]*Schema
	SchemaPackages map[string]string
}

type OperationDocExtractor func(handler any, methodName string) (*OperationDoc, bool)

type OperationEndpoint struct {
	Method string
	Path   string
}

type Option func(*Spec)

type OptionsSpecProvider interface {
	GOAIOptionsSpec() Spec
}

type Parameter struct {
	Name            string                `yaml:"name"`
	In              string                `yaml:"in"`
	Description     string                `yaml:"description,omitempty"`
	Required        bool                  `yaml:"required,omitempty"`
	Deprecated      bool                  `yaml:"deprecated,omitempty"`
	AllowEmptyValue bool                  `yaml:"allowEmptyValue,omitempty"`
	Style           string                `yaml:"style,omitempty"`
	Explode         *bool                 `yaml:"explode,omitempty"`
	AllowReserved   bool                  `yaml:"allowReserved,omitempty"`
	Schema          *Schema               `yaml:"schema,omitempty"`
	Example         any                   `yaml:"example,omitempty"`
	Examples        map[string]*Example   `yaml:"examples,omitempty"`
	Content         map[string]*MediaType `yaml:"content,omitempty"`
	Extensions      map[string]any        `yaml:",inline,omitempty"`
}

type PatchSpecProvider interface {
	GOAIPatchSpec() Spec
}

type PathAwareParamInjector interface {
	InjectedParamsFor(routePath string) []PathParam
}

type PathItem struct {
	Ref         string         `yaml:"$ref,omitempty"`
	Summary     string         `yaml:"summary,omitempty"`
	Description string         `yaml:"description,omitempty"`
	Get         *Operation     `yaml:"get,omitempty"`
	Put         *Operation     `yaml:"put,omitempty"`
	Post        *Operation     `yaml:"post,omitempty"`
	Delete      *Operation     `yaml:"delete,omitempty"`
	Options     *Operation     `yaml:"options,omitempty"`
	Head        *Operation     `yaml:"head,omitempty"`
	Patch       *Operation     `yaml:"patch,omitempty"`
	Trace       *Operation     `yaml:"trace,omitempty"`
	Servers     []Server       `yaml:"servers,omitempty"`
	Parameters  []*Parameter   `yaml:"parameters,omitempty"`
	Extensions  map[string]any `yaml:",inline,omitempty"`
}

type PathParam struct {
	Name             string
	In               string // typically "path"; "query" / "header" allowed
	Style            string // OpenAPI parameter style; default "simple"
	Description      string
	AnchorAfter      string
	Example          string
	Required         bool
	IsItemIdentifier bool
}

type PathParamInjector interface {
	InjectedParams() []PathParam
}

type PathTagRule struct {
	Pattern string
	Tag     string
}

type PostSpecProvider interface {
	GOAIPostSpec() Spec
}

type Profile struct {
	Name    string
	Include Selector
	Exclude Selector
}

type ProfileScope interface {
	GOAIProfileScope() []string
}

type PutSpecProvider interface {
	GOAIPutSpec() Spec
}

type RequestBody struct {
	Description string                `yaml:"description,omitempty"`
	Content     map[string]*MediaType `yaml:"content,omitempty"`
	Required    bool                  `yaml:"required,omitempty"`
	Extensions  map[string]any        `yaml:",inline,omitempty"`
}

type Response struct {
	Description string                `yaml:"description"`
	Headers     map[string]*Header    `yaml:"headers,omitempty"`
	Content     map[string]*MediaType `yaml:"content,omitempty"`
	Links       map[string]*Link      `yaml:"links,omitempty"`
	Extensions  map[string]any        `yaml:",inline,omitempty"`
}

type ResponseOption func(*ResponseSpec)

type ResponseSpec struct {
	// Description is rendered verbatim under responses.<status>.description.
	Description string

	// SchemaType, when non-nil, drives schema synthesis from a Go type
	// (the same path used for request bodies and successful response
	// bodies registered via goai.Register). Mutually exclusive with
	// Schema; Schema wins when both are set.
	SchemaType reflect.Type

	// Schema, when non-nil, is used directly without further synthesis.
	// Use this for hand-tuned schemas, $ref-based reuse, or to attach
	// schemas the schema builder cannot derive (e.g. raw JSON Schema
	// objects).
	Schema *Schema

	// MediaType overrides the response content media type. Empty falls
	// back to "application/json" when Schema or SchemaType is set; when
	// both Schema and SchemaType are nil the response carries no
	// content block regardless of MediaType.
	MediaType string

	// Example is a single inline example. Use Examples when richer
	// metadata (named summaries / descriptions / external values) is
	// needed.
	Example any

	// Examples is the per-name Example map. Mutually compatible with
	// Example — yaml encoders emit both fields.
	Examples map[string]*Example

	// Headers documents response headers attached to this status code.
	Headers []HeaderDef
}

type RouteFactory func() ghttp.RouteEntriesProvider

type RunFromConfigOption func(*runFromConfigOpts)

type RunOptions struct {
	// Title is the OpenAPI info.title default. CLI flag -title overrides.
	Title string

	// Description is the OpenAPI info.description.
	Description string

	// Version is the OpenAPI info.version default. CLI flag -version overrides.
	Version string

	// TermsOfService is the OpenAPI info.termsOfService URL.
	TermsOfService string

	// Contact populates Document.Info.Contact.
	Contact *Contact

	// License populates Document.Info.License (e.g. {Name: "MIT"}).
	License *License

	// ExternalDocs populates the top-level Document.ExternalDocs.
	ExternalDocs *ExternalDocumentation

	// Servers populates Document.Servers verbatim.
	Servers []Server

	// Tags populates Document.Tags verbatim. Hand-listing them controls the
	// final tag ordering in the emitted yaml.
	Tags []Tag

	// GlobalSecurity is propagated as Document.Security (the top-level
	// requirement applied to every operation that does not declare its own).
	GlobalSecurity []map[string][]string

	// TagSecurityClassifier provides per-path tag and per-acceptance security
	// fallbacks. nil → goai.DefaultClassifier() inside Build.
	TagSecurityClassifier *Classifier

	// SecuritySchemes are merged into Document.Components.SecuritySchemes
	// after Build. Wins over any classifier-injected scheme reference that
	// happens to share a name.
	SecuritySchemes map[string]*SecurityScheme

	// DefaultOutput is the -o flag default. Must be a writable file path or
	// "-" for stdout. Empty string falls back to "openapi.generated.yaml".
	DefaultOutput string

	// BaseSpec, when non-nil, is the hand-tuned OpenAPI yaml that the
	// auto-generated structure is merged onto. The hand-tuned content wins
	// for everything that is already present (info, tags, paths,
	// components.schemas, components.securitySchemes); auto-discovered
	// entries fill gaps. Use this when the project keeps a curated
	// `docs/openapi/openapi.yaml` as the canonical source of truth and
	// wants the generator to surface routes absent from it.
	//
	// Mutually exclusive with BaseSpecPath; BaseSpec wins when both are set.
	BaseSpec []byte

	// BaseSpecPath, when non-empty, is the filesystem path to the
	// hand-tuned OpenAPI yaml. RunCLI loads it on startup and feeds the
	// bytes through the same merge path as BaseSpec. Empty path means "no
	// merge, emit pure auto-generated yaml".
	BaseSpecPath string

	// RestrictToBaseSpecPaths, when true and a base spec is supplied,
	// constrains the generator to ONLY emit operations whose path also
	// appears in the base spec. Auto-discovered routes absent from the
	// hand-tuned yaml are dropped from the output.
	//
	// Use this when the curated `docs/openapi/openapi.yaml` is treated as
	// the canonical endpoint registry — i.e. a route does not "exist" for
	// API consumers until it has been documented. This is the strict
	// inverse of the default behavior, which surfaces every walked route
	// regardless of base-spec coverage.
	RestrictToBaseSpecPaths bool

	// ExcludePaths is an explicit blocklist of path globs. Paths matching
	// any of these patterns are dropped from the generated document
	// before merge, regardless of whether RestrictToBaseSpecPaths is set.
	//
	// Glob syntax: "*" matches one segment, "**" matches any number of
	// segments. Examples:
	//
	//	{"/static/**", "/favicon.ico", "/robots.txt"} // drop static asset routes
	//	{"/debug/**"}                                  // drop debug-only routes
	ExcludePaths []string

	// OperationDocExtractor enables source-level Go doc-comment extraction
	// for operation-level OpenAPI metadata. The built-in extractor only
	// reads namespaced `@goai.*` directives from handler struct and method
	// docs, so ordinary implementation comments stay private. Use
	// DefaultOperationDocExtractor() or
	// DefaultOperationDocExtractorWithBuildTags() to turn on the AST-based
	// implementation; pass nil (the default) to disable docstring
	// fallback entirely.
	//
	// Explicit Spec values, route-derived parameters, generated schemas,
	// and acceptance-derived security always win; docstring content only
	// fills gaps.
	OperationDocExtractor OperationDocExtractor

	// Args is the argv slice the CLI parses. nil → os.Args[1:].
	Args []string

	// Stdout is where yaml goes when DefaultOutput resolves to "-". nil →
	// os.Stdout. Tests inject a buffer here.
	Stdout io.Writer

	// Stderr is where progress and error messages go. nil → os.Stderr.
	Stderr io.Writer

	// Exit is invoked on terminal failure with a non-zero code. nil →
	// os.Exit. Tests inject a recorder.
	Exit func(int)
}

type RuntimeOption func(*runtimeConfig)

type Schema struct {
	Ref string `yaml:"$ref,omitempty"`

	Title       string `yaml:"title,omitempty"`
	Type        string `yaml:"type,omitempty"`
	Format      string `yaml:"format,omitempty"`
	Description string `yaml:"description,omitempty"`

	// Numeric validation
	MultipleOf       *float64 `yaml:"multipleOf,omitempty"`
	Maximum          *float64 `yaml:"maximum,omitempty"`
	ExclusiveMaximum bool     `yaml:"exclusiveMaximum,omitempty"`
	Minimum          *float64 `yaml:"minimum,omitempty"`
	ExclusiveMinimum bool     `yaml:"exclusiveMinimum,omitempty"`

	// String validation
	MaxLength *uint64 `yaml:"maxLength,omitempty"`
	MinLength *uint64 `yaml:"minLength,omitempty"`
	Pattern   string  `yaml:"pattern,omitempty"`

	// Array validation
	MaxItems    *uint64 `yaml:"maxItems,omitempty"`
	MinItems    *uint64 `yaml:"minItems,omitempty"`
	UniqueItems bool    `yaml:"uniqueItems,omitempty"`

	// Object validation
	MaxProperties *uint64 `yaml:"maxProperties,omitempty"`
	MinProperties *uint64 `yaml:"minProperties,omitempty"`

	// Enumeration / fixed
	Enum    []any `yaml:"enum,omitempty"`
	Default any   `yaml:"default,omitempty"`

	// Composition
	OneOf []*Schema `yaml:"oneOf,omitempty"`
	AllOf []*Schema `yaml:"allOf,omitempty"`
	AnyOf []*Schema `yaml:"anyOf,omitempty"`
	Not   *Schema   `yaml:"not,omitempty"`

	// Object
	Properties           map[string]*Schema `yaml:"properties,omitempty"`
	Required             []string           `yaml:"required,omitempty"`
	AdditionalProperties any                `yaml:"additionalProperties,omitempty"`

	// Array
	Items *Schema `yaml:"items,omitempty"`

	// OAS-specific
	Nullable      bool                   `yaml:"nullable,omitempty"`
	Discriminator *Discriminator         `yaml:"discriminator,omitempty"`
	ReadOnly      bool                   `yaml:"readOnly,omitempty"`
	WriteOnly     bool                   `yaml:"writeOnly,omitempty"`
	XML           *XML                   `yaml:"xml,omitempty"`
	ExternalDocs  *ExternalDocumentation `yaml:"externalDocs,omitempty"`
	Example       any                    `yaml:"example,omitempty"`
	Deprecated    bool                   `yaml:"deprecated,omitempty"`

	Extensions map[string]any `yaml:",inline,omitempty"`
}

type SchemaNameProvider interface {
	GOAISchemaName() string
}

type SecurityProvider interface {
	SecurityRequirement() (scheme string, scopes []string)
}

type SecurityRef struct {
	Scheme string
	Scopes []string
}

type SecurityScheme struct {
	Type             string         `yaml:"type"`
	Description      string         `yaml:"description,omitempty"`
	Name             string         `yaml:"name,omitempty"`
	In               string         `yaml:"in,omitempty"`
	Scheme           string         `yaml:"scheme,omitempty"`
	BearerFormat     string         `yaml:"bearerFormat,omitempty"`
	Flows            *OAuthFlows    `yaml:"flows,omitempty"`
	OpenIDConnectURL string         `yaml:"openIdConnectUrl,omitempty"`
	Extensions       map[string]any `yaml:",inline,omitempty"`
}

type Selector struct {
	Paths    []string `yaml:"paths,omitempty"`
	Packages []string `yaml:"packages,omitempty"`
	Tags     []string `yaml:"tags,omitempty"`
	Profiles []string `yaml:"profiles,omitempty"`
}

type Server struct {
	URL         string                     `yaml:"url"`
	Description string                     `yaml:"description,omitempty"`
	Variables   map[string]*ServerVariable `yaml:"variables,omitempty"`
	Extensions  map[string]any             `yaml:",inline,omitempty"`
}

type ServerVariable struct {
	Enum        []string       `yaml:"enum,omitempty"`
	Default     string         `yaml:"default"`
	Description string         `yaml:"description,omitempty"`
	Extensions  map[string]any `yaml:",inline,omitempty"`
}

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

type SpecProvider interface {
	GOAISpec() Spec
}

type Tag struct {
	Name         string                 `yaml:"name"`
	Description  string                 `yaml:"description,omitempty"`
	ExternalDocs *ExternalDocumentation `yaml:"externalDocs,omitempty"`
	Extensions   map[string]any         `yaml:",inline,omitempty"`
}

type TraceSpecProvider interface {
	GOAITraceSpec() Spec
}

type XML struct {
	Name       string         `yaml:"name,omitempty"`
	Namespace  string         `yaml:"namespace,omitempty"`
	Prefix     string         `yaml:"prefix,omitempty"`
	Attribute  bool           `yaml:"attribute,omitempty"`
	Wrapped    bool           `yaml:"wrapped,omitempty"`
	Extensions map[string]any `yaml:",inline,omitempty"`
}