ir

package
v0.7.3 Latest Latest
Warning

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

 Go to latest Published: Jul 28, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package ir defines the JSON IR schema consumed by apigen emitters.

Index

Constants

View Source 
const CurrentSchemaVersion = "v4"

CurrentSchemaVersion is the supported JSON IR schema version.

View Source 
const ResponseShapeExtensionKey = "x-apigen-response-shape"

ResponseShapeExtensionKey stores APIGen-owned response shape metadata.

Variables

This section is empty.

Functions

func CLICommandString 

func CLICommandString(cli *CLI) string

CLICommandString renders a CLI command path as a space-delimited string.

func JSONPointerSegments added in v0.5.1 

func JSONPointerSegments(pointer string) ([]string, error)

JSONPointerSegments parses and unescapes an RFC 6901 pointer.

func JoinAPIPath 

func JoinAPIPath(basePath string, endpointPath string) string

JoinAPIPath combines a contract base path with an authored endpoint path.

func Normalize 

func Normalize(doc *Document) error

Normalize applies deterministic ordering for generation.

func NormalizedSchemaRefName 

func NormalizedSchemaRefName(schema SchemaRef) (string, bool)

NormalizedSchemaRefName resolves a schema ref to a registry key.

func OrderedPropertyNames 

func OrderedPropertyNames(schema Schema) []string

OrderedPropertyNames returns a deterministic property order for a schema.

func PathParameterNames 

func PathParameterNames(path string) []string

PathParameterNames extracts ordered "{param}" names from an endpoint path.

func ResolveRequestBodySchemaName added in v0.1.1 

func ResolveRequestBodySchemaName(doc Document, endpoint Endpoint) (string, bool)

ResolveRequestBodySchemaName returns the concrete request body schema name when present.

func Validate 

func Validate(doc Document) error

Validate checks required fields and uniqueness constraints.

func ValidateBasePath 

func ValidateBasePath(basePath string) error

ValidateBasePath checks APIGen API base path formatting.

Types

type API 

type API struct {
	BasePath string `json:"base_path"`
}

API contains APIGen-owned API metadata.

type AdditionalProperties 

type AdditionalProperties struct {
	Any    bool       `json:"any,omitempty"`
	Schema *SchemaRef `json:"schema,omitempty"`
}

AdditionalProperties captures OpenAPI object-map semantics for inline schema refs.

type BodyContent added in v0.3.2 

type BodyContent struct {
	ContentType string          `json:"content_type"`
	BodyKind    string          `json:"body_kind"`
	Schema      *SchemaRef      `json:"schema,omitempty"`
	AnyOf       []SchemaRef     `json:"any_of,omitempty"`
	Parts       []MultipartPart `json:"parts,omitempty"`
	Example     any             `json:"example,omitempty"`
}

BodyContent describes one media type variant for a request or response body.

func PrimaryRequestBodyContent added in v0.3.2 

func PrimaryRequestBodyContent(endpoint Endpoint) (BodyContent, bool)

PrimaryRequestBodyContent returns the preferred content entry for generated server and CLI code paths that can use only one request representation.

func PrimaryResponseContent added in v0.3.2 

func PrimaryResponseContent(response Response) (BodyContent, bool)

PrimaryResponseContent returns the preferred content entry for generated server and CLI code paths that can use only one response representation.

type CLI 

type CLI struct {
	Command    []string       `json:"command,omitempty"`
	Args       []CLIArg       `json:"args,omitempty"`
	BodyInput  string         `json:"body_input,omitempty"`
	Confirm    string         `json:"confirm,omitempty"`
	Output     *CLIOutput     `json:"output,omitempty"`
	Pagination *CLIPagination `json:"pagination,omitempty"`
}

CLI describes APIGen-owned CLI metadata for one operation.

func CloneCLI 

func CloneCLI(in *CLI) *CLI

CloneCLI returns a deep copy of CLI metadata.

type CLIArg 

type CLIArg struct {
	Source      string `json:"source"`
	Name        string `json:"name"`
	DisplayName string `json:"display_name,omitempty"`
}

CLIArg binds one positional CLI argument to a request source field.

type CLIOutput 

type CLIOutput struct {
	Mode         string   `json:"mode,omitempty"`
	TableColumns []string `json:"table_columns,omitempty"`
	QuietFields  []string `json:"quiet_fields,omitempty"`
}

CLIOutput controls generated response rendering.

type CLIPagination 

type CLIPagination struct {
	ItemsField         string `json:"items_field,omitempty"`
	NextPageTokenField string `json:"next_page_token_field,omitempty"`
}

CLIPagination declares the collection envelope used for --all style paging.

type Contract added in v0.4.0 

type Contract struct {
	Name        string         `json:"name"`
	Schema      SchemaRef      `json:"schema"`
	Kind        string         `json:"kind,omitempty"`
	Tags        []string       `json:"tags,omitempty"`
	Description string         `json:"description,omitempty"`
	Extensions  map[string]any `json:"extensions,omitempty"`
}

Contract describes one data-contract root.

type Discriminator added in v0.5.0 

type Discriminator struct {
	PropertyName string            `json:"property_name"`
	Mapping      map[string]string `json:"mapping"`
}

Discriminator selects one schema alternative using an object property.

type Document 

type Document struct {
	SchemaVersion   string            `json:"schema_version"`
	API             API               `json:"api"`
	Info            Info              `json:"info"`
	OpenAPI         OpenAPI           `json:"openapi,omitempty"`
	Servers         []Server          `json:"servers,omitempty"`
	Tags            []Tag             `json:"tags,omitempty"`
	Schemas         map[string]Schema `json:"schemas,omitempty"`
	Contracts       []Contract        `json:"contracts,omitempty"`
	Endpoints       []Endpoint        `json:"endpoints,omitempty"`
	TransportErrors *TransportErrors  `json:"transport_errors,omitempty"`
	Extensions      map[string]any    `json:"extensions,omitempty"`
}

Document is the root JSON IR payload.

func Load 

func Load(path string) (Document, error)

Load parses and validates an IR document from disk.

type Endpoint 

type Endpoint struct {
	Method      string                `json:"method"`
	Path        string                `json:"path"`
	OperationID string                `json:"operation_id"`
	Namespace   string                `json:"namespace,omitempty"`
	Summary     string                `json:"summary,omitempty"`
	Description string                `json:"description,omitempty"`
	Tags        []string              `json:"tags,omitempty"`
	Parameters  []Parameter           `json:"parameters,omitempty"`
	RequestBody *RequestBody          `json:"request_body,omitempty"`
	Responses   []Response            `json:"responses"`
	CLI         *CLI                  `json:"cli,omitempty"`
	Tool        *Tool                 `json:"tool,omitempty"`
	Security    []SecurityRequirement `json:"security,omitempty"`
	Extensions  map[string]any        `json:"extensions,omitempty"`
}

Endpoint describes one API operation. 

type Header struct {
	Name        string    `json:"name"`
	Required    bool      `json:"required,omitempty"`
	Description string    `json:"description,omitempty"`
	Schema      SchemaRef `json:"schema"`
}

Header describes one response header.

type Info 

type Info struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
	Namespace   string `json:"namespace,omitempty"`
}

Info contains API metadata.

type MultipartPart added in v0.3.2 

type MultipartPart struct {
	Name        string     `json:"name"`
	WireName    string     `json:"wire_name,omitempty"`
	PartKind    string     `json:"part_kind,omitempty"`
	Repeated    bool       `json:"repeated,omitempty"`
	Required    bool       `json:"required,omitempty"`
	Description string     `json:"description,omitempty"`
	ContentType string     `json:"content_type,omitempty"`
	BodyKind    string     `json:"body_kind,omitempty"`
	Filename    bool       `json:"filename,omitempty"`
	Schema      *SchemaRef `json:"schema,omitempty"`
}

MultipartPart describes one part in a multipart body.

type OpenAPI 

type OpenAPI struct {
	Version         string                    `json:"version,omitempty"`
	TagOrder        []string                  `json:"tag_order,omitempty"`
	Security        []SecurityRequirement     `json:"security,omitempty"`
	SecuritySchemes map[string]SecurityScheme `json:"security_schemes,omitempty"`
}

OpenAPI contains canonical OpenAPI document metadata that is not directly represented by the generator-oriented endpoint/schema model.

type Parameter 

type Parameter struct {
	Name        string    `json:"name"`
	In          string    `json:"in"`
	Required    bool      `json:"required,omitempty"`
	Description string    `json:"description,omitempty"`
	Example     any       `json:"example,omitempty"`
	Explode     *bool     `json:"explode,omitempty"`
	Schema      SchemaRef `json:"schema"`
}

Parameter describes an operation parameter.

type RequestBody 

type RequestBody struct {
	Required    bool          `json:"required,omitempty"`
	Description string        `json:"description,omitempty"`
	Contents    []BodyContent `json:"contents,omitempty"`
}

RequestBody describes the operation request payload.

type ResolvedObjectProperty added in v0.5.1 

type ResolvedObjectProperty struct {
	Property SchemaProperty
	Required bool
}

ResolvedObjectProperty is one property from an inherited object or from the compatible common surface of every variant in an object-shaped union.

func ResolveCommonObjectProperty added in v0.5.3 

func ResolveCommonObjectProperty(doc Document, refs []SchemaRef, name string) (ResolvedObjectProperty, bool, error)

ResolveCommonObjectProperty resolves one compatible property shared by each object schema reference.

func ResolveObjectProperty added in v0.5.1 

func ResolveObjectProperty(doc Document, ref SchemaRef, name string) (ResolvedObjectProperty, bool, error)

ResolveObjectProperty resolves a property through object inheritance and discriminated unions. A union property is available only when every variant declares it with compatible wire types.

type Response 

type Response struct {
	StatusCode  int            `json:"status_code"`
	Description string         `json:"description"`
	Headers     []Header       `json:"headers,omitempty"`
	Contents    []BodyContent  `json:"contents,omitempty"`
	Extensions  map[string]any `json:"extensions,omitempty"`
}

Response describes one operation response.

func SuccessResponse 

func SuccessResponse(endpoint Endpoint) (*Response, bool)

SuccessResponse returns the preferred success response for CLI generation.

type ResponseShape 

type ResponseShape struct {
	Kind     string `json:"kind"`
	BodyType string `json:"body_type,omitempty"`
}

ResponseShape describes the APIGen-owned response transport shape.

func ResponseShapeMetadata 

func ResponseShapeMetadata(response Response) (ResponseShape, bool, error)

ResponseShapeMetadata extracts typed APIGen response-shape metadata.

type Schema 

type Schema struct {
	Type          string                    `json:"type"`
	Namespace     string                    `json:"namespace,omitempty"`
	Title         string                    `json:"title,omitempty"`
	Description   string                    `json:"description,omitempty"`
	Example       any                       `json:"example,omitempty"`
	Properties    map[string]SchemaProperty `json:"properties,omitempty"`
	PropertyOrder []string                  `json:"property_order,omitempty"`
	Required      []string                  `json:"required,omitempty"`
	Items         *SchemaRef                `json:"items,omitempty"`
	Base          *SchemaRef                `json:"base,omitempty"`
	OneOf         []SchemaRef               `json:"one_of,omitempty"`
	Discriminator *Discriminator            `json:"discriminator,omitempty"`
	Enum          []string                  `json:"enum,omitempty"`
	Extensions    map[string]any            `json:"extensions,omitempty"`
}

Schema is a JSON schema subset used by apigen.

func FlattenObjectSchema added in v0.5.1 

func FlattenObjectSchema(doc Document, schema Schema) Schema

FlattenObjectSchema returns an object schema with inherited properties and requirements merged into one deterministic view. Child properties override inherited properties while keeping the inherited field position.

func ResolveCommonObjectSchema added in v0.5.3 

func ResolveCommonObjectSchema(doc Document, refs []SchemaRef) (Schema, bool)

ResolveCommonObjectSchema returns the deterministic object surface shared by every schema reference. Properties that are absent or incompatible in any branch are excluded from the common view.

func ResolveObjectSchema added in v0.5.1 

func ResolveObjectSchema(doc Document, ref SchemaRef) (Schema, bool)

ResolveObjectSchema returns the deterministic object surface visible on an inherited object or object-shaped union. Variant-only and incompatible union properties are intentionally excluded.

func ResolveRequestBodySchema 

func ResolveRequestBodySchema(doc Document, endpoint Endpoint) (Schema, bool)

ResolveRequestBodySchema returns the concrete request body schema when present.

func ResolveResponseBodySchema 

func ResolveResponseBodySchema(doc Document, response Response) (Schema, bool)

ResolveResponseBodySchema returns the schema used for the CLI-visible success body.

func ResolveSchema 

func ResolveSchema(doc Document, schemaRef SchemaRef) (Schema, bool)

ResolveSchema returns the concrete schema referenced by the schema ref.

type SchemaProperty 

type SchemaProperty struct {
	Description string         `json:"description,omitempty"`
	Example     any            `json:"example,omitempty"`
	Schema      SchemaRef      `json:"schema"`
	Extensions  map[string]any `json:"extensions,omitempty"`
}

SchemaProperty describes one schema property.

type SchemaRef 

type SchemaRef struct {
	Ref                  string                `json:"ref,omitempty"`
	Type                 string                `json:"type,omitempty"`
	Format               string                `json:"format,omitempty"`
	Enum                 []string              `json:"enum,omitempty"`
	Minimum              *float64              `json:"minimum,omitempty"`
	Maximum              *float64              `json:"maximum,omitempty"`
	MinLength            *int                  `json:"min_length,omitempty"`
	MaxLength            *int                  `json:"max_length,omitempty"`
	Items                *SchemaRef            `json:"items,omitempty"`
	AdditionalProperties *AdditionalProperties `json:"additional_properties,omitempty"`
}

SchemaRef references or describes a schema.

func ResolveObjectArrayItemSchemas added in v0.5.3 

func ResolveObjectArrayItemSchemas(doc Document, ref SchemaRef, name string) ([]SchemaRef, bool, error)

ResolveObjectArrayItemSchemas retains the item schema from each object or union branch instead of collapsing heterogeneous arrays to array<any>.

func ResolveResponseBodySchemaRef added in v0.5.1 

func ResolveResponseBodySchemaRef(response Response) (SchemaRef, bool)

ResolveResponseBodySchemaRef returns the schema reference used for the CLI-visible JSON success body.

func ResolveSchemaPointer added in v0.5.1 

func ResolveSchemaPointer(doc Document, scope SchemaRef, pointer string) (SchemaRef, bool, error)

ResolveSchemaPointer resolves an RFC 6901 property pointer against an object surface and reports whether any traversed property or map entry is optional.

func SchemaProjectionKind added in v0.5.1 

func SchemaProjectionKind(doc Document, ref SchemaRef) (string, SchemaRef)

SchemaProjectionKind classifies a projection source and returns the scope used for nested selections.

func ToolSuccessSchema added in v0.5.1 

func ToolSuccessSchema(endpoint Endpoint) (SchemaRef, string, bool, error)

ToolSuccessSchema selects the single compatible schema exposed by all 2xx JSON representations. Other response media remain part of the endpoint contract but do not participate in agent-tool output derivation.

type SecurityRequirement 

type SecurityRequirement map[string][]string

SecurityRequirement is an OpenAPI security requirement object.

type SecurityScheme 

type SecurityScheme struct {
	Type   string `json:"type"`
	In     string `json:"in,omitempty"`
	Name   string `json:"name,omitempty"`
	Scheme string `json:"scheme,omitempty"`
}

SecurityScheme describes one named OpenAPI security scheme.

type Server 

type Server struct {
	URL         string                    `json:"url"`
	Description string                    `json:"description,omitempty"`
	Variables   map[string]ServerVariable `json:"variables,omitempty"`
}

Server describes a server URL entry.

type ServerVariable 

type ServerVariable struct {
	Default     string   `json:"default,omitempty"`
	Description string   `json:"description,omitempty"`
	Enum        []string `json:"enum,omitempty"`
}

ServerVariable describes an OpenAPI server variable.

type Tag 

type Tag struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

Tag describes a logical operation grouping.

type Tool added in v0.4.0 

type Tool struct {
	Name         string         `json:"name"`
	Description  string         `json:"description,omitempty"`
	Effect       string         `json:"effect"`
	Confirmation string         `json:"confirmation,omitempty"`
	Tags         []string       `json:"tags,omitempty"`
	Input        *ToolInput     `json:"input,omitempty"`
	Output       ToolOutput     `json:"output"`
	Metadata     map[string]any `json:"metadata,omitempty"`
}

Tool describes an SDK-neutral agent tool projected from an endpoint.

type ToolCursor added in v0.4.0 

type ToolCursor struct {
	Source        string `json:"source"`
	Target        string `json:"target,omitempty"`
	HasMoreTarget string `json:"has_more_target,omitempty"`
}

ToolCursor exposes pagination state in a stable tool result shape.

type ToolInput added in v0.4.0 

type ToolInput struct {
	Fields []ToolInputField `json:"fields,omitempty"`
}

ToolInput customizes how endpoint fields become tool arguments.

type ToolInputField added in v0.4.0 

type ToolInputField struct {
	Source      string `json:"source"`
	Name        string `json:"name"`
	Mode        string `json:"mode,omitempty"`
	Alias       string `json:"alias,omitempty"`
	ContextKey  string `json:"context_key,omitempty"`
	Description string `json:"description,omitempty"`
	Default     any    `json:"default,omitempty"`
}

ToolInputField overrides one endpoint parameter or request body field.

type ToolOutput added in v0.4.0 

type ToolOutput struct {
	Mode   string           `json:"mode"`
	Select []ToolProjection `json:"select,omitempty"`
	Cursor *ToolCursor      `json:"cursor,omitempty"`
}

ToolOutput describes the successful response presented to an agent.

type ToolProjection added in v0.4.0 

type ToolProjection struct {
	Source  string           `json:"source"`
	Target  string           `json:"target,omitempty"`
	Select  []ToolProjection `json:"select,omitempty"`
	CountAs string           `json:"count_as,omitempty"`
}

ToolProjection recursively selects one response value.

type TransportErrors added in v0.5.0 

type TransportErrors struct {
	Schema      SchemaRef                   `json:"schema"`
	ContentType string                      `json:"content_type"`
	Failures    map[string]TransportFailure `json:"failures"`
}

TransportErrors defines generated HTTP transport failure contracts.

type TransportFailure added in v0.5.0 

type TransportFailure struct {
	StatusCode   int    `json:"status_code"`
	Code         string `json:"code"`
	PublicDetail string `json:"public_detail"`
}

TransportFailure maps a stable failure kind to public wire behavior.

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.