openapi

type Anchor struct {
	Location
	In   *Schema
	Name Text
	Type AnchorType
}

type AnchorType uint8

type Anchors struct {
	Standard  []Anchor // $anchor
	Recursive *Anchor  // $recursiveAnchor
	Dynamic   []Anchor // $dynamicAnchor
}

type BaseVisitor struct{}

type Callbacks struct {
	Extensions `json:"-"`
	PathItems  `json:"-"`
}

type CallbacksMap = ComponentMap[*Callbacks]

type CompiledSchema interface {
	Validate(data interface{}) error
}

type CompiledSchemas struct {
	OpenAPI    map[semver.Version]map[Kind]CompiledSchema
	JSONSchema map[uri.URI]CompiledSchema
}

type Component[T refable] struct {
	Location
	Reference *Reference[T]
	Object    T
}

type ComponentEntry[V refable] struct {
	Key       Text
	Component *Component[V]
}

type ComponentMap[T refable] struct {
	Location
	Items []*ComponentEntry[T]
}

type ComponentSlice[T refable] struct {
	Location `json:"-"`
	Items    []*Component[T] `json:"-"`
}

type Components struct {
	// OpenAPI extensions
	Extensions `json:"-"`
	Location   `json:"-"`

	Schemas         *SchemaMap         `json:"schemas,omitempty"`
	Responses       *ResponseMap       `json:"responses,omitempty"`
	Parameters      *ParameterMap      `json:"parameters,omitempty"`
	RequestBodies   *RequestBodyMap    `json:"requestBodies,omitempty"`
	Headers         *HeaderMap         `json:"headers,omitempty"`
	SecuritySchemes *SecuritySchemeMap `json:"securitySchemes,omitempty"`
	Links           *LinkMap           `json:"links,omitempty"`
	Callbacks       *CallbacksMap      `json:"callbacks,omitempty"`
	PathItems       *PathItemMap       `json:"pathItems,omitempty"`
	Examples        *ExampleMap        `json:"examples,omitempty"` //
}

type Contact struct {
	Extensions `json:"-"`
	Location   `json:"-"`
	// The identifying name of the contact person/organization.
	Name Text `json:"name,omitempty"`
	// The URL pointing to the contact information. This MUST be in the form of
	// a URL.
	URL *uri.URI `json:"url,omitempty"`
	// The email address of the contact person/organization. This MUST be in the
	// form of an email address.
	Emails Text `json:"email,omitempty"`
}

type ContentMap = ObjMap[*MediaType]

type Discriminator struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	// The name of the property in the payload that will hold the discriminator
	// value.
	//
	// *required
	PropertyName Text `json:"propertyName"`
	// An object to hold mappings between payload values and schema names or
	// references.
	Mapping *Map[Text] `json:"mapping,omitempty"`
}

type Document struct {
	Location   `json:"-"`
	Extensions `json:"-"`

	// OpenAPI - The OpenAPI Version
	//
	// This string MUST be the version number of the OpenAPI
	// Specification that the OpenAPI document uses. The openapi field SHOULD be
	// used by tooling to interpret the OpenAPI document. This is not related to
	// the API info.version string.
	//
	// 	*required*
	OpenAPI *semver.Version `json:"openapi"`

	// Provides metadata about the API. The metadata MAY be used by
	// tooling as required.
	//
	// 	*required*
	Info *Info `json:"info"`

	// The default value for the $schema keyword within Schema Objects contained
	// within this OAS document.
	JSONSchemaDialect *uri.URI `json:"jsonSchemaDialect,omitempty"`

	// A list of tags used by the document with additional metadata. The order
	// of the tags can be used to reflect on their order by the parsing tools.
	// Not all tags that are used by the Operation Object must be declared. The
	// tags that are not declared MAY be organized randomly or based on the
	// tools’ logic. Each tag name in the list MUST be unique.
	Tags *TagSlice `json:"tags,omitempty"`

	// An array of Server Objects, which provide connectivity information to a
	// target server. If the servers property is not provided, or is an empty
	// array, the default value would be a Server Object with a url value of /.
	Servers *ServerSlice `json:"servers,omitempty" yaml:"servers,omitempty,omtiempty"`

	// The available paths and operations for the API.
	Paths *Paths `json:"paths,omitempty"`

	// The incoming webhooks that MAY be received as part of this API and that
	// the API consumer MAY choose to implement. Closely related to the
	// callbacks feature, this section describes requests initiated other than
	// by an API call, for example by an out of band registration. The key name
	// is a unique string to refer to each webhook, while the (optionally
	// referenced) Path Item Object describes a request that may be initiated by
	// the API provider and the expected responses. An example is available.
	Webhooks *PathItemMap `json:"webhooks,omitempty"`

	// An element to hold various schemas for the document.
	Components *Components `json:"components,omitempty"`

	// A declaration of which security mechanisms can be used across the API.
	//
	// The list of values includes alternative security requirement objects that
	// can be used.
	//
	// Only one of the security requirement objects need to be
	// satisfied to authorize a request. Individual operations can override this
	// definition.
	//
	// To make security optional, an empty security requirement ({})
	// can be included in the array.
	//
	Security *SecurityRequirementSlice `json:"security,omitempty"`

	// Additional external documentation.
	ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
}

type DuplicateAnchorError struct {
	A *Anchor
	B *Anchor
}

type Encoding struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	// The Content-Type for encoding a specific property. Default value depends
	// on the property type:
	//
	//  - for object - application/json;
	//  - for array – the default is defined based on the inner type;
	//  - for all other cases the default is application/octet-stream.
	// The value can be a specific media type (e.g. application/json), a
	// wildcard media type (e.g. image/*), or a comma-separated list of the two
	// types.
	ContentType Text `json:"contentType,omitempty"`
	// A map allowing additional information to be provided as headers, for
	// example Content-Disposition. Content-Type is described separately and
	// SHALL be ignored in this section. This property SHALL be ignored if the
	// request body media type is not a multipart.
	Headers *HeaderMap `json:"headers,omitempty"`
	// Describes how a specific property value will be serialized depending on
	// its type. See Parameter Object for details on the style property. The
	// behavior follows the same values as query parameters, including default
	// values. This property SHALL be ignored if the request body media type is
	// not application/x-www-form-urlencoded or multipart/form-data. If a value
	// is explicitly defined, then the value of contentType (implicit or
	// explicit) SHALL be ignored.
	Style Text `json:"style,omitempty"`
	// When this is true, property values of type array or object generate
	// separate parameters for each value of the array, or key-value-pair of the
	// map. For other types of properties this property has no effect. When
	// style is form, the default value is true. For all other styles, the
	// default value is false. This property SHALL be ignored if the request
	// body media type is not application/x-www-form-urlencoded or
	// multipart/form-data. If a value is explicitly defined, then the value of
	// contentType (implicit or explicit) SHALL be ignored.
	Explode *bool `json:"explode,omitempty"`
	// Determines whether the parameter value SHOULD allow reserved characters,
	// as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without
	// percent-encoding. The default value is false. This property SHALL be
	// ignored if the request body media type is not
	// application/x-www-form-urlencoded or multipart/form-data. If a value is
	// explicitly defined, then the value of contentType (implicit or explicit)
	// SHALL be ignored.
	AllowReserved *bool `json:"allowReserved,omitempty"`
}

type EncodingMap = ComponentMap[*Encoding]

type Error struct {
	Err         error
	ResourceURI uri.URI
}

type Example struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	// Short description for the example.
	Summary Text `json:"summary,omitempty"`

	// Long description for the example. CommonMark syntax MAY be used for rich
	// text representation.
	Description Text `json:"description,omitempty"`

	// Any embedded literal example. The value field and externalValue field are
	// mutually exclusive. To represent examples of media types that cannot
	// naturally represented in JSON or YAML, use a string value to contain the
	// example, escaping where necessary.
	Value jsonx.RawMessage `json:"value,omitempty"`

	// A URI that points to the literal example. This provides the capability to
	// reference examples that cannot easily be included in JSON or YAML
	// documents. The value field and externalValue field are mutually
	// exclusive. See the rules for resolving Relative References.
	ExternalValue *uri.URI `json:"externalValue,omitempty"`
}

type ExampleMap = ComponentMap[*Example]

type Extensions map[Text]jsonx.RawMessage

type ExternalDocs struct {
	Location   `json:"-"`
	Extensions `json:"-"`

	// The URL for the target documentation. This MUST be in the form of a URL.
	//
	// 	*required*
	URL *uri.URI `json:"url"`

	// A description of the target documentation. CommonMark syntax MAY be used
	// for rich text representation.
	Description Text `json:"description,omitempty"`
}

type Header struct {
	// OpenAPI extensions
	Extensions `json:"-"`
	Location   `json:"-"`

	// A brief description of the parameter. This could contain examples of use.
	// CommonMark syntax MAY be used for rich text representation.
	Description Text `json:"description,omitempty"`

	// Determines whether this parameter is mandatory. If the parameter location
	// is "path", this property is REQUIRED and its value MUST be true.
	// Otherwise, the property MAY be included and its default value is false.
	Required *bool `json:"required,omitempty"`

	// Specifies that a parameter is deprecated and SHOULD be transitioned out
	// of usage. Default value is false.
	Deprecated *bool `json:"deprecated,omitempty"`

	// Sets the ability to pass empty-valued parameters. This is valid only for
	// query parameters and allows sending a parameter with an empty value.
	// Default value is false. If style is used, and if behavior is n/a (cannot
	// be serialized), the value of allowEmptyValue SHALL be ignored. Use of
	// this property is NOT RECOMMENDED, as it is likely to be removed in a
	// later revision.
	AllowEmptyValue *bool `json:"allowEmptyValue,omitempty"`

	// Describes how the parameter value will be serialized depending on the
	// type of the parameter value.
	// Default values (based on value of in):
	// 	- for query - form;
	// 	- for path - simple;
	// 	- for header - simple;
	// 	- for cookie - form.
	Style Text `json:"style,omitempty"`

	// When this is true, parameter values of type array or object generate
	// separate parameters for each value of the array or key-value pair of the
	// map. For other types of parameters this property has no effect. When
	// style is form, the default value is true. For all other styles, the
	// default value is false.
	Explode *bool `json:"explode,omitempty"`

	// Determines whether the parameter value SHOULD allow reserved characters,
	// as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without
	// percent-encoding. This property only applies to parameters with an in
	// value of query. The default value is false.
	AllowReserved *bool `json:"allowReserved,omitempty"`

	// The schema defining the type used for the parameter.
	Schema *Schema `json:"schema,omitempty"`

	// Examples of the parameter's potential value. Each example SHOULD
	// contain a value in the correct format as specified in the parameter
	// encoding. The examples field is mutually exclusive of the example
	// field. Furthermore, if referencing a schema that contains an example,
	// the examples value SHALL override the example provided by the schema.
	Examples *ExampleMap `json:"examples,omitempty"`

	// Example of the parameter's potential value. The example SHOULD match the
	// specified schema and encoding properties if present. The example field is
	// mutually exclusive of the examples field. Furthermore, if referencing a
	// schema that contains an example, the example value SHALL override the
	// example provided by the schema. To represent examples of media types that
	// cannot naturally be represented in JSON or YAML, a string value can
	// contain the example with escaping where necessary.
	Example jsonx.RawMessage `json:"example,omitempty"`
}

type HeaderMap = ComponentMap[*Header]

type In = Text

type Info struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	// Version of the OpenAPI document (which is distinct from the OpenAPI
	// Specification version or the API implementation version).
	//
	// 	*required*
	Version Text `json:"version"`

	// The title of the API.
	//
	// 	*required*
	Title Text `json:"title"`

	// A short summary of the API.
	Summary Text `json:"summary,omitempty"`

	// A description of the API. CommonMark syntax MAY be used for rich text
	// representation.
	Description Text `json:"description,omitempty"`

	// A URL to the Terms of Service for the API. This MUST be in the form of a
	// URL.
	TermsOfService Text `json:"termsOfService,omitempty" bson:"termsOfService,omitempty"`

	// The contact information for the exposed API.
	Contact *Contact `json:"contact,omitempty" bson:"contact,omitempty"`

	// License information for the exposed API.
	License *License `json:"license,omitempty" bson:"license,omitempty"`
}

type Item[T node] struct {
	Location
	Key   Text
	Value T
}

type JSONObjEntry struct {
	Key   Text
	Value jsonx.RawMessage
}

type KeyValue[V any] struct {
	Key   Text
	Value V
}

type Kind uint16

type License struct {
	Location `json:"-"`

	// The license name used for the API.
	//
	// 	*required*
	Name Text `json:"name"`

	// An SPDX license expression for the API. The identifier field is mutually
	// exclusive of the url field.
	Identifier Text `json:"identifier,omitempty"`
	// A URL to the license used for the API. This MUST be in the form of a URL.
	// The url field is mutually exclusive of the identifier field.
	URL *uri.URI `json:"url,omitempty"`
}

type Link struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	// The name of an existing, resolvable OAS operation, as defined with a
	// unique operationId. This field is mutually exclusive of the operationRef
	// field.
	OperationID Text `json:"operationId,omitempty"`

	// A relative or absolute URI reference to an OAS operation.
	//
	// This field is mutually exclusive of the operationId field, and MUST point
	// to an Operation Object.
	OperationRef *OperationRef `json:"operationRef,omitempty"`

	// A description of the link. CommonMark syntax MAY be used for rich text
	// representation.
	Description Text `json:"description,omitempty"`

	// A map representing parameters to pass to an operation as specified with
	// operationID or identified via operationRef.
	//
	// The key is the parameter name
	// to be used, whereas the value can be a constant or an expression to be
	// evaluated and passed to the linked operation.
	//
	// The parameter name can be
	// qualified using the parameter location [{in}.]{name} for operations that
	// use the same parameter name in different locations (e.g. path.id).
	Parameters OrderedJSONObj `json:"parameters,omitempty"`

	// A literal value or {expression} to use as a request body when calling the
	// target operation.
	RequestBody jsonx.RawMessage `json:"requestBody,omitempty"`
}

type LinkMap = ComponentMap[*Link]

type LoadOpts struct {
	DefaultSchemaDialect *uri.URI
}

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

type Map[T any] struct {
	Items []KeyValue[T]
}

type MediaType struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	// The schema defining the content of the request, response, or parameter.
	Schema *Schema `json:"schema,omitempty"`
	// Example of the media type. The example object SHOULD be in the correct
	// format as specified by the media type. The example field is mutually
	// exclusive of the examples field. Furthermore, if referencing a schema
	// which contains an example, the example value SHALL override the example
	// provided by the schema.
	Example jsonx.RawMessage `json:"example,omitempty"`
	// Examples of the media type. Each example object SHOULD match the media
	// type and specified schema if present. The examples field is mutually
	// exclusive of the example field. Furthermore, if referencing a schema
	// which contains an example, the examples value SHALL override the example
	// provided by the schema.
	Examples *ExampleMap `json:"examples,omitempty"`
	// A map between a property name and its encoding information. The key,
	// being the property name, MUST exist in the schema as a property. The
	// encoding object SHALL only apply to requestBody objects when the media
	// type is multipart or application/x-www-form-urlencoded.
	Encoding *EncodingMap `json:"encoding,omitempty"`
}

type MediaTypeMap = ObjMap[*MediaType]

type Node interface {
	// AbsoluteLocation returns the absolute path of the node in URI form.
	// This includes the URI path of the resource and the JSON pointer
	// of the node.
	//
	// e.g. openapi.json#/components/schemas/Example
	AbsoluteLocation() uri.URI

	// RelativeLocation returns the path as a JSON pointer for the Node.
	RelativeLocation() jsonpointer.Pointer

	// Kind returns the Kind for the given Node
	Kind() Kind

	// Anchors returns a list of all Anchors in the Node and all descendants.
	Anchors() (*Anchors, error)

	// Refs returns a list of all Refs from the Node and all descendants.
	Refs() []Ref

	// MarshalJSON marshals JSON
	//
	// MarshalJSON satisfies the json.Marshaler interface
	MarshalJSON() ([]byte, error)
	// UnmarshalJSON unmarshals JSON
	//
	// UnmarshalJSON satisfies the json.Unmarshaler interface
	UnmarshalJSON(data []byte) error

	// UnmarshalYAML satisfies gopkg.in/yaml.v3 Marshaler interface
	MarshalYAML() (interface{}, error)

	// UnmarshalYAML satisfies gopkg.in/yaml.v3 Unmarshaler interface
	UnmarshalYAML(value *yaml.Node) error
}

type Number = jsonx.Number

type OAuthFlow struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	// The authorization URL to be used for this flow. This MUST be in the form
	// of a URL. The OAuth2 standard requires the use of TLS.
	//
	// Applies to: OAuth2 ("implicit", "authorizationCode")
	//
	// 	*required*
	AuthorizationURL Text `json:"authorizationUrl,omitempty"`
	// The token URL to be used for this flow. This MUST be in the form of a
	// URL. The OAuth2 standard requires the use of TLS.
	//
	// Applies to: OAuth2Flow ("password", "clientCredentials", "authorizationCode")
	//
	// 	*required*
	TokenURL Text `json:"tokenUrl,omitempty"`
	// The URL to be used for obtaining refresh tokens. This MUST be in the form
	// of a URL. The OAuth2 standard requires the use of TLS.
	RefreshURL Text `json:"refreshUrl,omitempty"`
	// The available scopes for the OAuth2 security scheme. A map between the
	// scope name and a short description for it. The map MAY be empty.
	//
	// 	*required*
	Scopes *Scopes `json:"scopes"`
}

type OAuthFlows struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	// Configuration for the OAuth Implicit flow
	Implicit *OAuthFlow `json:"implicit,omitempty"`
	// Configuration for the OAuth Resource Owner Password flow
	Password *OAuthFlow `json:"password,omitempty"`
	// Configuration for the OAuth Client Credentials flow. Previously called
	// application in OpenAPI 2.0.
	ClientCredentials *OAuthFlow `json:"clientCredentials,omitempty"`
	// Configuration for the OAuth Authorization Code flow. Previously called accessCode in OpenAPI 2.0.
	AuthorizationCode *OAuthFlow `json:"authorizationCode,omitempty"`
}

type ObjMap[T node] struct {
	Location
	Items []Item[T]
}

type ObjSlice[T node] struct {
	Location `json:"-"`
	Items    []T `json:"-"`
}

type Operation struct {
	// Location contains information about the location of the node in the
	// document or referenced resource
	Location   `json:"-"`
	Extensions `json:"-"`

	// Unique string used to identify the operation. The id MUST be unique among
	// all operations described in the API. The operationId value is
	// case-sensitive. Tools and libraries MAY use the operationId to uniquely
	// identify an operation, therefore, it is RECOMMENDED to follow common
	// programming naming conventions.
	OperationID Text `json:"operationId,omitempty"`

	// Declares this operation to be deprecated. Consumers SHOULD refrain from
	// usage of the declared operation. Default value is false.
	Deprecated bool `json:"deprecated,omitempty"`

	// A short summary of what the operation does.
	Summary Text `json:"summary,omitempty"`

	// A verbose explanation of the operation behavior. CommonMark syntax MAY be
	// used for rich text representation.
	Description Text `json:"description,omitempty"`

	// A list of tags for API documentation control. Tags can be used for
	// logical grouping of operations by resources or any other qualifier.
	Tags Texts `json:"tags,omitempty"`

	// A list of parameters that are applicable for this operation. If a
	// parameter is already defined at the Path Item, the new definition will
	// override it but can never remove it. The list MUST NOT include duplicated
	// parameters. A unique parameter is defined by a combination of a name and
	// location. The list can use the Reference Object to link to parameters
	// that are defined at the OpenAPI Object's components/parameters.
	Parameters *ParameterSlice `json:"parameters,omitempty"`

	// The request body applicable for this operation. The requestBody is fully
	// supported in HTTP methods where the HTTP 1.1 specification RFC7231 has
	// explicitly defined semantics for request bodies. In other cases where the
	// HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is
	// permitted but does not have well-defined semantics and SHOULD be avoided
	// if possible.
	RequestBody *Component[*RequestBody] `json:"requestBody,omitempty"`

	// The list of possible responses as they are returned from executing this
	// operation.
	Responses *ResponseMap `json:"responses,omitempty"`

	// A map of possible out-of band callbacks related to the parent operation.
	// The key is a unique identifier for the Callback Object. Each value in the
	// map is a Callback Object that describes a request that may be initiated
	// by the API provider and the expected responses.
	Callbacks *CallbacksMap `json:"callbacks,omitempty"`

	// A declaration of which security mechanisms can be used for this
	// operation. The list of values includes alternative security requirement
	// objects that can be used. Only one of the security requirement objects
	// need to be satisfied to authorize a request. To make security optional,
	// an empty security requirement ({}) can be included in the array. This
	// definition overrides any declared top-level security. To remove a
	// top-level security declaration, an empty array can be used.
	Security *SecurityRequirementMap `json:"security,omitempty"`

	// An alternative server array to service this operation. If an alternative
	// server object is specified at the Path Item Object or Root level, it will
	// be overridden by this value.
	Servers *ServerSlice `json:"servers,omitempty"`

	// externalDocs	Additional external documentation.
	ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
}

type OperationRef struct {
	Location
	Ref      *uri.URI
	Resolved *Operation
}

type OrderedJSONObj []JSONObjEntry

type Parameter struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	// The name of the parameter. Parameter names are case sensitive:
	//
	// - If In is "path", the name field MUST correspond to a template
	// expression occurring within the path field in the Paths Object.
	// See Path Templating for further information.
	//
	// - If In is "header" and the name field is "Accept", "Content-Type"
	// or "Authorization", the parameter definition SHALL be ignored.
	//
	// - For all other cases, the name corresponds to the parameter name
	// used by the in property.
	//
	//  *required*
	Name Text `json:"name"`

	// The location of the parameter. Possible values are "query", "header",
	// "path" or "cookie".
	//
	//  *required*
	In In `json:"in"`

	// A brief description of the parameter. This could contain examples of use.
	// CommonMark syntax MAY be used for rich text representation.
	Description Text `json:"description,omitempty"`

	// Determines whether this parameter is mandatory. If the parameter location
	// is "path", this property is REQUIRED and its value MUST be true.
	// Otherwise, the property MAY be included and its default value is false.
	Required *bool `json:"required,omitempty"`

	// Specifies that a parameter is deprecated and SHOULD be transitioned out
	// of usage. Default value is false.
	Deprecated bool `json:"deprecated,omitempty"`

	// Sets the ability to pass empty-valued parameters. This is valid only for
	// query parameters and allows sending a parameter with an empty value.
	// Default value is false. If style is used, and if behavior is n/a (cannot
	// be serialized), the value of allowEmptyValue SHALL be ignored. Use of
	// this property is NOT RECOMMENDED, as it is likely to be removed in a
	// later revision.
	AllowEmptyValue bool `json:"allowEmptyValue,omitempty"`

	// Describes how the parameter value will be serialized depending on the
	// type of the parameter value.
	// Default values (based on value of in):
	//  - for query - form;
	// 	- for path - simple;
	// 	- for header - simple;
	// 	- for cookie - form.
	Style Text `json:"style,omitempty"`

	// When this is true, parameter values of type array or object generate
	// separate parameters for each value of the array or key-value pair of the
	// map. For other types of parameters this property has no effect. When
	// style is form, the default value is true. For all other styles, the
	// default value is false.
	Explode bool `json:"explode,omitempty"`

	// Determines whether the parameter value SHOULD allow reserved characters,
	// as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without
	// percent-encoding. This property only applies to parameters with an in
	// value of query. The default value is false.
	AllowReserved bool `json:"allowReserved,omitempty"`

	// The schema defining the type used for the parameter.
	Schema *Schema `json:"schema,omitempty"`

	// Examples of the parameter's potential value. Each example SHOULD
	// contain a value in the correct format as specified in the parameter
	// encoding. The examples field is mutually exclusive of the example
	// field. Furthermore, if referencing a schema that contains an example,
	// the examples value SHALL override the example provided by the schema.
	Examples *ExampleMap `json:"examples,omitempty"`

	Example jsonx.RawMessage `json:"example,omitempty"`

	// For more complex scenarios, the content property can define the media
	// type and schema of the parameter. A parameter MUST contain either a
	// schema property, or a content property, but not both. When example or
	// examples are provided in conjunction with the schema object, the example
	// MUST follow the prescribed serialization strategy for the parameter.
	Content *ContentMap `json:"content,omitempty"`
}

type ParameterMap = ComponentMap[*Parameter]

type ParameterSlice = ComponentSlice[*Parameter]

type PathItem struct {
	Location   `json:"-"`
	Extensions `json:"-"`

	// An optional, string summary, intended to apply to all operations in this path.
	Summary Text `json:"summary,omitempty"`

	// An optional, string description, intended to apply to all operations in
	// this path. CommonMark syntax MAY be used for rich text representation.
	Description Text `json:"description,omitempty"`

	// A list of parameters that are applicable for all the operations described
	// under this path. These parameters can be overridden at the operation
	// level, but cannot be removed there. The list MUST NOT include duplicated
	// parameters. A unique parameter is defined by a combination of a name and
	// location. The list can use the Reference Object to link to parameters
	// that are defined at the OpenAPI Object's components/parameters.
	Parameters *ParameterSlice `json:"parameters,omitempty"`

	// A definition of a GET operation on this path.
	Get *Operation `json:"get,omitempty"`

	// A definition of a PUT operation on this path.
	Put *Operation `json:"put,omitempty"`

	// A definition of a POST operation on this path.
	Post *Operation `json:"post,omitempty"`

	// A definition of a DELETE operation on this path.
	Delete *Operation `json:"delete,omitempty"`

	// A definition of a OPTIONS operation on this path.
	Options *Operation `json:"options,omitempty"`

	// A definition of a HEAD operation on this path.
	Head *Operation `json:"head,omitempty"`

	// A definition of a PATCH operation on this path.
	Patch *Operation `json:"patch,omitempty"`

	// A definition of a TRACE operation on this path.
	Trace *Operation `json:"trace,omitempty"`

	// An alternative server array to service all operations in this path.
	Servers *ServerSlice `json:"servers,omitempty"`
}

type PathItemEntry struct {
	Key      text.Text
	PathItem *PathItem
}

type PathItemMap = ComponentMap[*PathItem]

type PathItems = ObjMap[*PathItem]

type Paths struct {
	Extensions `json:"-"`

	// Items are the Path
	PathItems `json:"-"`
}

type Ref interface {
	Node
	URI() *uri.URI
	IsResolved() bool
	ResolvedNode() Node
	// ReferencedKind returns the Kind for the referenced node
	RefKind() Kind
	// RefType returns the RefType for the reference
	RefType() RefType
}

type RefType uint8

type Reference[T refable] struct {
	// The reference identifier. This MUST be in the form of a URI.
	//
	// 	*required*
	Ref *uri.URI `json:"$ref"`

	// A short summary which by default SHOULD override that of the referenced
	// component. If the referenced object-type does not allow a summary field,
	// then this field has no effect.
	Summary Text `json:"summary,omitempty"`

	// A description which by default SHOULD override that of the referenced
	// component. CommonMark syntax MAY be used for rich text representation. If
	// the referenced object-type does not allow a description field, then this
	// field has no effect.
	Description Text `json:"description,omitempty"`

	// Location of the Reference
	Location `json:"-"`

	ReferencedKind Kind `json:"-"`

	Resolved T `json:"-"`
	// contains filtered or unexported fields
}

type Regexp struct {
	*regexp.Regexp
}

type RequestBody struct {
	Location   `json:"-"`
	Extensions `json:"-"`

	// A brief description of the request body. This could contain examples of
	// use. CommonMark syntax MAY be used for rich text representation.
	Description Text `json:"description,omitempty"`
	// The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text
	//
	// *required*
	Content *ContentMap `json:"content,omitempty"`
	// Determines if the request body is required in the request. Defaults to false.
	Required bool `json:"required,omitempty"`
}

type RequestBodyMap = ComponentMap[*RequestBody]

type ResolutionError struct {
	URI      uri.URI
	Expected Kind
	Actual   Kind
	RefType  RefType
}

type Response struct {
	// A description of the response. CommonMark syntax MAY be used for rich
	// text representation.
	//
	// *required*
	Description Text `json:"description,omitempty"`
	// Maps a header name to its definition. RFC7230 states header names are
	// case insensitive. If a response header is defined with the name
	// "Content-Type", it SHALL be ignored.
	Headers *HeaderMap `json:"headers,omitempty"`
	// A map containing descriptions of potential response payloads. The key is
	// a media type or media type range and the value describes it. For
	// responses that match multiple keys, only the most specific key is
	// applicable. e.g. text/plain overrides text/*
	Content *ContentMap `json:"content,omitempty"`
	// A map of operations links that can be followed from the response. The key
	// of the map is a short name for the link, following the naming constraints
	// of the names for Component Objects.
	Links      *LinkMap `json:"links,omitempty"`
	Extensions `json:"-"`

	Location `json:"-"`
}

type ResponseMap = ComponentMap[*Response]

type Schema struct {
	Extensions `json:"-"`
	Location   `json:"-"`

	Schema *uri.URI `json:"$schema,omitempty"`

	// The value of $id is a URI-reference without a fragment that resolves
	// against the Retrieval URI. The resulting URI is the base URI for the
	// schema.
	//
	// https://json-schema.org/understanding-json-schema/structuring.html?highlight=id#id
	ID *uri.URI `json:"$id,omitempty"`

	// A less common way to identify a subschema is to create a named anchor in
	// the schema using the $anchor keyword and using that name in the URI
	// fragment. Anchors must start with a letter followed by any number of
	// letters, digits, -, _, :, or ..
	//
	// https://json-schema.org/understanding-json-schema/structuring.html?highlight=anchor#anchor
	Anchor Text `json:"$anchor,omitempty"`

	DynamicAnchor Text `json:"$dynamicAnchor,omitempty"`

	RecursiveAnchor *bool `json:"$recursiveAnchor,omitempty"`

	// At its core, JSON *SchemaObj defines the following basic types:
	//
	// 	"string", "number", "integer", "object", "array", "boolean", "null"
	//
	// https://json-schema.org/understanding-json-schema/reference/type.html#type
	Type Types `json:"type,omitempty"`

	// The "$ref" keyword is an applicator that is used to reference a
	// statically identified schema. Its results are the results of the
	// referenced schema. [CREF5]
	//
	// The value of the "$ref" keyword MUST be a string which is a
	// URI-Reference. Resolved against the current URI base, it produces the URI
	// of the schema to apply. This resolution is safe to perform on schema
	// load, as the process of evaluating an instance cannot change how the
	// reference resolves.
	//
	// https://json-schema.org/draft/2020-12/json-schema-core.html#ref
	//
	// https://json-schema.org/understanding-json-schema/structuring.html?highlight=ref#ref
	Ref *SchemaRef `json:"$ref,omitempty"`

	// The "$dynamicRef" keyword is an applicator that allows for deferring the
	// full resolution until runtime, at which point it is resolved each time it
	// is encountered while evaluating an instance.
	//
	// https://json-schema.org/draft/2020-12/json-schema-core.html#dynamic-ref
	DynamicRef *SchemaRef `json:"$dynamicRef,omitempty"`

	RecursiveRef *SchemaRef `json:"$recursiveRef,omitempty"`

	// The format keyword allows for basic semantic identification of certain Kinds of string values that are commonly used. For example, because JSON doesn’t have a “DateTime” type, dates need to be encoded as strings. format allows the schema author to indicate that the string value should be interpreted as a date. By default, format is just an annotation and does not effect validation.
	//
	// Optionally, validator implementations can provide a configuration option to
	// enable format to function as an assertion rather than just an annotation.
	// That means that validation will fail if, for example, a value with a date
	// format isn’t in a form that can be parsed as a date. This can allow values to
	// be constrained beyond what the other tools in JSON *SchemaObj, including Regular
	// Expressions can do.
	//
	// https://json-schema.org/understanding-json-schema/reference/string.html#format
	Format Text `json:"format,omitempty"`

	// The const keyword is used to restrict a value to a single value.
	//
	// https://json-schema.org/understanding-json-schema/reference/generic.html?highlight=const#constant-values
	Const jsonx.RawMessage `json:"const,omitempty"`

	Required Texts `json:"required,omitempty"`

	Properties *SchemaMap `json:"properties,omitempty"`

	// The enum keyword is used to restrict a value to a fixed set of values. It
	// must be an array with at least one element, where each element is unique.
	//
	// https://json-schema.org/understanding-json-schema/reference/generic.html?highlight=const#enumerated-values
	Enum Texts `json:"enum,omitempty"`

	// The $comment keyword is strictly intended for adding comments to a
	// schema. Its value must always be a string. Unlike the annotations title,
	// description, and examples, JSON schema implementations aren’t allowed to
	// attach any meaning or behavior to it whatsoever, and may even strip them
	// at any time. Therefore, they are useful for leaving notes to future
	// editors of a JSON schema, but should not be used to communicate to users
	// of the schema.
	//
	// https://json-schema.org/understanding-json-schema/reference/generic.html?highlight=const#comments
	Comments Text `json:"$comment,omitempty"`

	// The not keyword declares that an instance validates if it doesn’t
	// validate against the given subschema.
	//
	// https://json-schema.org/understanding-json-schema/reference/combining.html?highlight=not#not
	Not *Schema `json:"not,omitempty"`

	// validate against allOf, the given data must be valid against all of the
	// given subschemas.
	//
	// https://json-schema.org/understanding-json-schema/reference/combining.html?highlight=anyof#anyof
	AllOf *SchemaSlice `json:"allOf,omitempty"`

	// validate against anyOf, the given data must be valid against any (one or
	// more) of the given subschemas.
	//
	// https://json-schema.org/understanding-json-schema/reference/combining.html?highlight=allof#allof
	AnyOf *SchemaSlice `json:"anyOf,omitempty"`

	// alidate against oneOf, the given data must be valid against exactly one of the given subschemas.
	//
	// https://json-schema.org/understanding-json-schema/reference/combining.html?highlight=oneof#oneof
	OneOf *SchemaSlice `json:"oneOf,omitempty"`

	// if, then and else keywords allow the application of a subschema based on
	// the outcome of another schema, much like the if/then/else constructs
	// you’ve probably seen in traditional programming languages.
	//
	// https://json-schema.org/understanding-json-schema/reference/conditionals.html#if-then-else
	If *Schema `json:"if,omitempty"`

	// https://json-schema.org/understanding-json-schema/reference/conditionals.html#if-then-else
	Then *Schema `json:"then,omitempty"`

	Else *Schema `json:"else,omitempty"`

	MinProperties *Number `json:"minProperties,omitempty"`

	MaxProperties *Number `json:"maxProperties,omitempty"`

	PropertyNames *Schema `json:"propertyNames,omitempty"`

	RegexProperties *bool `json:"regexProperties,omitempty"`

	PatternProperties *SchemaMap `json:"patternProperties,omitempty"`

	AdditionalProperties *Schema `json:"additionalProperties,omitempty"`

	// The dependentRequired keyword conditionally requires that certain
	// properties must be present if a given property is present in an object.
	// For example, suppose we have a schema representing a customer. If you
	// have their credit card number, you also want to ensure you have a billing
	// address. If you don’t have their credit card number, a billing address
	// would not be required. We represent this dependency of one property on
	// another using the dependentRequired keyword. The value of the
	// dependentRequired keyword is an object. Each entry in the object maps
	// from the name of a property, p, to an array of strings listing properties
	// that are required if p is present.
	DependentRequired *Map[Texts] `json:"dependentRequired,omitempty"`

	DependentSchemas *SchemaMap `json:"dependentSchemas,omitempty"`

	UnevaluatedProperties *Schema `json:"unevaluatedProperties,omitempty"`

	UniqueItems *bool `json:"uniqueItems,omitempty"`

	// List validation is useful for arrays of arbitrary length where each item
	// matches the same schema. For this kind of array, set the items keyword to
	// a single schema that will be used to validate all of the items in the
	// array.
	//
	// https://json-schema.org/understanding-json-schema/reference/array.html#items
	Items *Schema `json:"items,omitempty"`

	UnevaluatedItems *Schema `json:"unevaluatedItems,omitempty"`

	AdditionalItems *Schema `json:"additionalItems,omitempty"`

	PrefixItems *SchemaSlice `json:"prefixItems,omitempty"`

	Contains *Schema `json:"contains,omitempty"`

	MinContains *Number `json:"minContains,omitempty"`

	MaxContains *Number `json:"maxContains,omitempty"`

	MinLength *Number `json:"minLength,omitempty"`

	MaxLength *Number `json:"maxLength,omitempty"`

	Pattern *Regexp `json:"pattern,omitempty"`

	ContentEncoding Text `json:"contentEncoding,omitempty"`

	ContentMediaType Text `json:"contentMediaType,omitempty"`

	Minimum *Number `json:"minimum,omitempty"`

	ExclusiveMinimum *Number `json:"exclusiveMinimum,omitempty"`

	Maximum *Number `json:"maximum,omitempty"`

	ExclusiveMaximum *Number `json:"exclusiveMaximum,omitempty"`

	MultipleOf *Number `json:"multipleOf,omitempty"`

	Title Text `json:"title,omitempty"`

	Description Text `json:"description,omitempty"`

	Default jsonx.RawMessage `json:"default,omitempty"`

	ReadOnly *bool `json:"readOnly,omitempty"`

	WriteOnly *bool `json:"writeOnly,omitempty"`

	Examples []jsonx.RawMessage `json:"examples,omitempty"`

	Example jsonx.RawMessage `json:"example,omitempty"`

	Deprecated *bool `json:"deprecated,omitempty"`

	ExternalDocs Text `json:"externalDocs,omitempty"`

	// When request bodies or response payloads may be one of a number of
	// different schemas, a discriminator object can be used to aid in
	// serialization, deserialization, and validation. The discriminator is a
	// specific object in a schema which is used to inform the consumer of the
	// document of an alternative schema based on the value associated with it.
	//
	// This object MAY be extended with Specification Extensions.
	//
	// The discriminator object is legal only when using one of the composite
	// keywords oneOf, anyOf, allOf.
	//
	// 3.1:
	//
	// https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#discriminatorObject
	//
	// 3.0:
	//
	// https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#discriminatorObject
	Discriminator *Discriminator `json:"discriminator,omitempty"`

	// This MAY be used only on properties schemas. It has no effect on root
	// schemas. Adds additional metadata to describe the XML representation of
	// this property.
	XML *XML `json:"xml,omitempty"`

	// The "$defs" keyword reserves a location for schema authors to inline
	// re-usable JSON Schemas into a more general schema. The keyword does not
	// directly affect the validation result.
	//
	// This keyword's value MUST be an object. Each member value of this object
	// MUST be a valid JSON *SchemaObj.
	//
	// https://json-schema.org/draft/2020-12/json-schema-core.html#defs
	//
	// https://json-schema.org/understanding-json-schema/structuring.html?highlight=defs#defs
	Definitions *SchemaMap `json:"$defs,omitempty"`

	Keywords map[Text]jsonx.RawMessage `json:"-"`
}

type SchemaItem struct {
	Key    Text
	Schema *Schema
}

type SchemaMap struct {
	Location
	Items []SchemaItem
}

type SchemaRef struct {
	Location
	Ref      *uri.URI `json:"-"`
	Resolved *Schema  `json:"-"`

	SchemaRefKind SchemaRefType `json:"-"`
}

type SchemaRefType uint8

type SchemaSlice struct {
	Location
	Items []*Schema
}

type Scope struct {
	Location `json:"-"`
	Key      Text `json:"-"`
	Value    Text `json:"-"`
}