model

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Dec 9, 2025 License: Apache-2.0 Imports: 0 Imported by: 0

Documentation

Overview

Package model provides version-agnostic intermediate representation (IR) types for OpenAPI specifications. These types serve as the internal data model that can be projected to specific OpenAPI versions (3.0.x or 3.1.x).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Additional 

type Additional struct {
	// Allow controls whether additional properties are allowed.
	// If nil, the behavior is unspecified (defaults to true in JSON Schema).
	// If Schema is non-nil, it takes precedence over Allow.
	Allow *bool

	// Schema defines the schema for additional properties.
	// If set, this takes precedence over Allow.
	Schema *Schema
}

Additional represents additionalProperties configuration for objects.

The semantics are:

  • nil => not specified (JSON Schema default: true)
  • Allow != nil && *Allow == false && Schema == nil => additionalProperties: false (strict)
  • Allow != nil && *Allow == true && Schema == nil => additionalProperties: true (explicit allow-all)
  • Schema != nil => additionalProperties: <schema> (takes precedence over Allow)

func AdditionalPropsSchema 

func AdditionalPropsSchema(s *Schema) *Additional

AdditionalPropsSchema returns an Additional that allows additional properties matching the given schema.

func NoAdditionalProps 

func NoAdditionalProps() *Additional

NoAdditionalProps returns an Additional that disallows additional properties.

type Bound 

type Bound struct {
	Value     float64
	Exclusive bool
}

Bound represents a numeric bound (minimum or maximum) with exclusive flag.

In OpenAPI 3.0, exclusive bounds are represented as boolean flags:

  • minimum: 10, exclusiveMinimum: true

In OpenAPI 3.1, exclusive bounds are represented as numeric values:

  • exclusiveMinimum: 10 (instead of minimum: 10)

type Callback 

type Callback struct {
	PathItems  map[string]*PathItem
	Extensions map[string]any
}

Callback represents a callback definition (3.0+).

type Components 

type Components struct {
	Schemas         map[string]*Schema
	SecuritySchemes map[string]*SecurityScheme
	Extensions      map[string]any
}

Components holds reusable components.

type Contact 

type Contact struct {
	Name       string
	URL        string
	Email      string
	Extensions map[string]any
}

Contact provides contact information for the API.

type Discriminator 

type Discriminator struct {
	PropertyName string
	Mapping      map[string]string
}

Discriminator is used for polymorphism in oneOf/allOf compositions.

type Encoding 

type Encoding struct {
	ContentType   string
	Headers       map[string]*Header
	Style         string
	Explode       bool
	AllowReserved bool
	Extensions    map[string]any
}

Encoding describes encoding for a single schema property.

type Example 

type Example struct {
	Summary       string
	Description   string
	Value         any
	ExternalValue string
	Extensions    map[string]any
}

Example represents an example value with optional description.

type ExternalDocs 

type ExternalDocs struct {
	Description string
	URL         string
	Extensions  map[string]any
}

ExternalDocs provides external documentation links. 

type Header struct {
	Description string
	Required    bool
	Deprecated  bool
	Style       string
	Explode     bool
	Schema      *Schema
	Example     any
	Examples    map[string]*Example
	Content     map[string]*MediaType
	Extensions  map[string]any
}

Header represents a response header.

type Info 

type Info struct {
	Title          string
	Summary        string // 3.1+ only: short summary of the API
	Description    string
	TermsOfService string
	Version        string
	Contact        *Contact
	License        *License
	Extensions     map[string]any
}

Info provides metadata about the API.

type Kind 

type Kind uint8

Kind represents a JSON Schema type kind. 

const (
	KindUnknown Kind = iota
	KindNull
	KindBoolean
	KindInteger
	KindNumber
	KindString
	KindObject
	KindArray
)

type License 

type License struct {
	Name       string // REQUIRED. The license name used for the API.
	Identifier string // SPDX license expression (OpenAPI 3.1+). Mutually exclusive with URL.
	URL        string // A URI for the license (OpenAPI 3.0). Mutually exclusive with Identifier.
	Extensions map[string]any
}

License provides license information for the API. 

type Link struct {
	OperationRef string
	OperationID  string
	Parameters   map[string]any
	RequestBody  any
	Description  string
	Server       *Server
	Extensions   map[string]any
}

Link represents a possible design-time link for a response.

type MediaType 

type MediaType struct {
	Schema     *Schema
	Example    any
	Examples   map[string]*Example
	Encoding   map[string]*Encoding
	Extensions map[string]any
}

MediaType provides schema and examples for a specific content type.

type OAuthFlow 

type OAuthFlow struct {
	AuthorizationURL string            // REQUIRED for implicit, authorizationCode
	TokenURL         string            // REQUIRED for password, clientCredentials, authorizationCode
	RefreshURL       string            // Optional URL for obtaining refresh tokens
	Scopes           map[string]string // REQUIRED. Map of scope name to description (can be empty)
	Extensions       map[string]any
}

OAuthFlow contains configuration details for a supported OAuth Flow.

type OAuthFlows 

type OAuthFlows struct {
	Implicit          *OAuthFlow // Configuration for the OAuth Implicit flow
	Password          *OAuthFlow // Configuration for the OAuth Resource Owner Password flow
	ClientCredentials *OAuthFlow // Configuration for the OAuth Client Credentials flow
	AuthorizationCode *OAuthFlow // Configuration for the OAuth Authorization Code flow
	Extensions        map[string]any
}

OAuthFlows allows configuration of the supported OAuth Flows.

type Operation 

type Operation struct {
	Tags        []string
	Summary     string
	Description string
	OperationID string
	Parameters  []Parameter
	RequestBody *RequestBody
	Responses   map[string]*Response
	Callbacks   map[string]*Callback
	Deprecated  bool
	Security    []SecurityRequirement
	Extensions  map[string]any
}

Operation describes a single API operation on a path.

type Parameter 

type Parameter struct {
	Name            string
	In              string // query, path, header, cookie
	Description     string
	Required        bool
	Deprecated      bool
	AllowEmptyValue bool
	Style           string
	Explode         bool
	AllowReserved   bool
	Schema          *Schema
	Example         any
	Examples        map[string]*Example // 3.1 style
	Content         map[string]*MediaType
	Extensions      map[string]any
}

Parameter describes a single operation parameter.

type PathItem 

type PathItem struct {
	Summary     string
	Description string
	Get         *Operation
	Put         *Operation
	Post        *Operation
	Delete      *Operation
	Options     *Operation
	Head        *Operation
	Patch       *Operation
	Parameters  []Parameter
	Extensions  map[string]any
}

PathItem represents the operations available on a single path.

type RequestBody 

type RequestBody struct {
	Description string
	Required    bool
	Content     map[string]*MediaType
	Extensions  map[string]any
}

RequestBody describes a single request body.

type Response 

type Response struct {
	Description string
	Content     map[string]*MediaType
	Headers     map[string]*Header
	Links       map[string]*Link
	Extensions  map[string]any
}

Response describes a single response from an API operation.

type Schema 

type Schema struct {
	// Ref is a logical reference to a component schema.
	// Projectors will resolve this to the appropriate $ref format.
	Ref string

	// Kind is the JSON Schema type kind.
	Kind Kind

	// Nullable indicates if the value can be null.
	// In 3.0: represented as nullable: true
	// In 3.1: represented as type: ["T", "null"]
	Nullable bool

	// Title provides a title for the schema.
	Title string

	// Description provides documentation for the schema.
	Description string

	// Format provides additional type information (e.g., "date-time", "email", "int64").
	Format string

	// ContentEncoding specifies the encoding for binary data (OAS 3.1).
	// Common values: "base64", "base64url"
	// In 3.0: converted to format: "byte"
	// In 3.1: output as contentEncoding
	ContentEncoding string

	// ContentMediaType specifies the media type of binary content (OAS 3.1).
	// Example: "image/png", "application/octet-stream"
	// In 3.0: omitted (not supported)
	// In 3.1: output as contentMediaType
	ContentMediaType string

	// Deprecated marks the schema as deprecated.
	Deprecated bool

	// ReadOnly indicates the value is read-only.
	ReadOnly bool

	// WriteOnly indicates the value is write-only.
	WriteOnly bool

	// Example provides a single example value (3.0 style).
	Example any

	// Examples provides multiple example values (3.1 style).
	// If both Example and Examples are set, projectors will prefer Examples for 3.1.
	Examples []any

	// Pattern is a regex pattern for string validation.
	Pattern string

	// MinLength is the minimum string length.
	MinLength *int

	// MaxLength is the maximum string length.
	MaxLength *int

	// Minimum is the minimum numeric value (with exclusive flag).
	// Projectors will convert this to version-specific format.
	Minimum *Bound

	// Maximum is the maximum numeric value (with exclusive flag).
	// Projectors will convert this to version-specific format.
	Maximum *Bound

	// MultipleOf constrains numbers to be multiples of this value.
	MultipleOf *float64

	// Items defines the item schema for arrays.
	Items *Schema

	// MinItems is the minimum number of items in an array.
	MinItems *int

	// MaxItems is the maximum number of items in an array.
	MaxItems *int

	// UniqueItems indicates array items must be unique.
	UniqueItems bool

	// Properties defines object properties.
	Properties map[string]*Schema

	// Required lists required property names (for type "object").
	Required []string

	// Additional controls additionalProperties behavior.
	// See Additional type documentation for semantics.
	Additional *Additional

	// PatternProps defines pattern-based properties (3.1 feature).
	// In 3.0, this will be dropped with a warning.
	PatternProps map[string]*Schema

	// Unevaluated defines unevaluatedProperties schema (3.1 feature).
	// In 3.0, this will be dropped with a warning.
	Unevaluated *Schema

	// MinProperties is the minimum number of properties in an object.
	MinProperties *int

	// MaxProperties is the maximum number of properties in an object.
	MaxProperties *int

	// AllOf represents an allOf composition.
	AllOf []*Schema

	// AnyOf represents an anyOf composition.
	AnyOf []*Schema

	// OneOf represents a oneOf composition.
	OneOf []*Schema

	// Not represents a not composition.
	Not *Schema

	// Enum lists allowed values for the schema.
	Enum []any

	// Const is a constant value (3.1 feature).
	// In 3.0, this will be converted to enum: [const] with a warning.
	Const any

	// Default is the default value for the schema.
	Default any

	// Discriminator is used for polymorphism (optional).
	Discriminator *Discriminator

	// XML provides XML serialization hints (optional).
	XML *XML

	// ExternalDocs provides external documentation links (optional).
	ExternalDocs *ExternalDocs

	// Extensions contains specification extensions (fields prefixed with x-).
	Extensions map[string]any
}

Schema represents a version-agnostic JSON Schema in the intermediate representation.

This IR is a superset of features needed for both OpenAPI 3.0.x and 3.1.x. Version-specific differences are handled by projectors in the export package.

type SecurityRequirement 

type SecurityRequirement map[string][]string

SecurityRequirement lists required security schemes for an operation.

type SecurityScheme 

type SecurityScheme struct {
	Type             string // http, apiKey, oauth2, openIdConnect, mutualTLS (3.1+)
	Description      string
	Name             string      // for apiKey
	In               string      // header, query, cookie (for apiKey)
	Scheme           string      // bearer, basic (for http)
	BearerFormat     string      // JWT (for http bearer)
	Flows            *OAuthFlows // for oauth2
	OpenIDConnectURL string      // for openIdConnect
	Extensions       map[string]any
}

SecurityScheme defines a security scheme.

type Server 

type Server struct {
	URL         string
	Description string
	Variables   map[string]*ServerVariable // Server variable substitution for URL template
	Extensions  map[string]any
}

Server represents a server URL and optional description.

type ServerVariable 

type ServerVariable struct {
	Enum        []string // Enumeration of allowed values (optional)
	Default     string   // REQUIRED. Default value for substitution
	Description string   // Optional description
	Extensions  map[string]any
}

ServerVariable represents a variable for server URL template substitution.

type Spec 

type Spec struct {
	// Info contains API metadata (title, version, description, contact, license).
	Info Info

	// Servers lists available server URLs for the API.
	Servers []Server

	// Paths maps path patterns to PathItem objects containing operations.
	Paths map[string]*PathItem

	// Components holds reusable schemas, security schemes, etc.
	Components *Components

	// Webhooks defines webhook endpoints (3.1 feature).
	// In 3.0, this will be dropped with a warning.
	Webhooks map[string]*PathItem

	// Tags provides additional metadata for operations.
	Tags []Tag

	// Security defines global security requirements applied to all operations.
	Security []SecurityRequirement

	// ExternalDocs provides external documentation links.
	ExternalDocs *ExternalDocs

	// Extensions contains specification extensions (fields prefixed with x-).
	Extensions map[string]any
}

Spec represents a version-agnostic OpenAPI specification.

This model supports all features from both OpenAPI 3.0.x and 3.1.x. Version-specific differences are handled by projectors in the export package.

type Tag 

type Tag struct {
	Name         string
	Description  string
	ExternalDocs *ExternalDocs
	Extensions   map[string]any
}

Tag adds metadata to a tag.

type XML 

type XML struct {
	Name      string
	Namespace string
	Prefix    string
	Attribute bool
	Wrapped   bool
}

XML provides XML serialization hints.

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.