overlay

package
v1.37.0 Latest Latest
Warning

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

 Go to latest Published: Jan 3, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package overlay provides support for OpenAPI Overlay Specification v1.0.0.

The OpenAPI Overlay Specification provides a standardized mechanism for augmenting OpenAPI documents through targeted transformations. Overlays use JSONPath expressions to select specific locations in an OpenAPI document and apply updates or removals.

Quick Start

Apply an overlay using functional options (recommended): 

result, err := overlay.ApplyWithOptions(
    overlay.WithSpecFilePath("openapi.yaml"),
    overlay.WithOverlayFilePath("changes.yaml"),
)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Applied %d changes\n", result.ActionsApplied)

Or use a reusable Applier instance: 

a := overlay.NewApplier()
a.StrictTargets = true
result, err := a.Apply("openapi.yaml", "changes.yaml")

Overlay Document Structure

An overlay document contains:

  • overlay: The specification version (must be "1.0.0")
  • info: Metadata with title and version
  • extends: Optional URI of the target document
  • actions: Ordered list of transformation actions

Example overlay document: 

overlay: 1.0.0
info:
  title: Production Customizations
  version: 1.0.0
actions:
  - target: $.info
    update:
      title: Production API
      x-environment: production
  - target: $.paths[?@.x-internal==true]
    remove: true

Action Types

Update actions merge content into matched nodes:

  • For objects: Properties are recursively merged
  • For arrays: The update value is appended
  • Same-name properties are replaced, new properties are added

Remove actions delete matched nodes from their parent container. When both update and remove are specified, remove takes precedence.

JSONPath Support

This package includes a built-in JSONPath implementation supporting:

  • Basic navigation: $.info, $.paths['/users']
  • Wildcards: $.paths.*, $.paths.*.*
  • Array indices: $.servers[0], $.servers[-1]
  • Simple filters: $.paths[?@.x-internal==true]
  • Compound filters: $.paths[?@.deprecated==true && @.x-internal==false]
  • Recursive descent: $..description (find all descriptions at any depth)

Dry-Run Preview

Preview overlay changes without modifying the document: 

result, _ := overlay.DryRunWithOptions(
    overlay.WithSpecFilePath("openapi.yaml"),
    overlay.WithOverlayFilePath("changes.yaml"),
)
for _, change := range result.Changes {
    fmt.Printf("Would %s %d nodes at %s\n",
        change.Operation, change.MatchCount, change.Target)
}

Validation

Overlays can be validated before application: 

o, _ := overlay.ParseOverlayFile("changes.yaml")
if errs := overlay.Validate(o); len(errs) > 0 {
    for _, err := range errs {
        fmt.Println(err)
    }
}

Structured Warnings

The overlay package provides structured warnings through the ApplyWarning type, which includes detailed context about non-fatal issues encountered during overlay application. Each warning has a category, action index, and target JSONPath for programmatic handling.

Access structured warnings from the result: 

result, _ := overlay.ApplyWithOptions(
    overlay.WithSpecFilePath("openapi.yaml"),
    overlay.WithOverlayFilePath("changes.yaml"),
)
for _, w := range result.StructuredWarnings {
    fmt.Printf("[%s] %s\n", w.Category, w.Message)
    if w.HasLocation() {
        fmt.Printf("  at %s\n", w.Location())
    }
}

Filter warnings by category: 

noMatches := result.StructuredWarnings.ByCategory(overlay.WarnNoMatch)

Warning categories include:

  • WarnNoMatch: Action target matched no nodes in the document
  • WarnActionError: Error executing an action (with cause)

For backward compatibility, warnings are also available as []string via result.Warnings.

The overlay package integrates with other oastools packages:

Example

Example demonstrates applying an overlay using functional options. 

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/overlay"
	"github.com/erraggy/oastools/parser"
)

func main() {
	// Create a simple OpenAPI document
	doc := map[string]any{
		"openapi": "3.0.3",
		"info": map[string]any{
			"title":   "My API",
			"version": "1.0.0",
		},
		"paths": map[string]any{},
	}

	// Create a simple overlay
	o := &overlay.Overlay{
		Version: "1.0.0",
		Info: overlay.Info{
			Title:   "Update API Title",
			Version: "1.0.0",
		},
		Actions: []overlay.Action{
			{
				Target: "$.info",
				Update: map[string]any{
					"title":         "Production API",
					"x-environment": "production",
				},
			},
		},
	}

	// Create a mock parse result
	parseResult := &parser.ParseResult{
		Document:     doc,
		SourceFormat: parser.SourceFormatYAML,
	}

	// Apply the overlay
	result, err := overlay.ApplyWithOptions(
		overlay.WithSpecParsed(*parseResult),
		overlay.WithOverlayParsed(o),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Check results
	fmt.Printf("Actions applied: %d\n", result.ActionsApplied)
	fmt.Printf("Actions skipped: %d\n", result.ActionsSkipped)

	// Access the modified document
	resultDoc := result.Document.(map[string]any)
	info := resultDoc["info"].(map[string]any)
	fmt.Printf("New title: %s\n", info["title"])

}

Output:

Actions applied: 1
Actions skipped: 0
New title: Production API
Example (CompoundFilter)

Example_compoundFilter demonstrates using && and || in filter expressions. 

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/overlay"
	"github.com/erraggy/oastools/parser"
)

func main() {
	// Create a document with various operation states
	doc := map[string]any{
		"openapi": "3.0.3",
		"info":    map[string]any{"title": "API", "version": "1.0.0"},
		"paths": map[string]any{
			"/deprecated-internal": map[string]any{
				"deprecated": true,
				"x-internal": true,
				"get":        map[string]any{"summary": "Old internal endpoint"},
			},
			"/deprecated-public": map[string]any{
				"deprecated": true,
				"x-internal": false,
				"get":        map[string]any{"summary": "Old public endpoint"},
			},
			"/active-internal": map[string]any{
				"deprecated": false,
				"x-internal": true,
				"get":        map[string]any{"summary": "Active internal endpoint"},
			},
			"/active-public": map[string]any{
				"deprecated": false,
				"x-internal": false,
				"get":        map[string]any{"summary": "Active public endpoint"},
			},
		},
	}

	// Use compound filter: deprecated AND internal
	o := &overlay.Overlay{
		Version: "1.0.0",
		Info:    overlay.Info{Title: "Filter Test", Version: "1.0.0"},
		Actions: []overlay.Action{
			{
				Target: "$.paths[?@.deprecated==true && @.x-internal==true]",
				Update: map[string]any{"x-removal-scheduled": "2025-01-01"},
			},
		},
	}

	parseResult := &parser.ParseResult{
		Document:     doc,
		SourceFormat: parser.SourceFormatYAML,
	}

	result, err := overlay.DryRunWithOptions(
		overlay.WithSpecParsed(*parseResult),
		overlay.WithOverlayParsed(o),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Compound filter (deprecated && internal) matched: %d path(s)\n", result.Changes[0].MatchCount)

}

Output:

Compound filter (deprecated && internal) matched: 1 path(s)
Example (DryRun)

Example_dryRun demonstrates previewing overlay changes without applying them. 

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/overlay"
	"github.com/erraggy/oastools/parser"
)

func main() {
	// Create a document
	doc := map[string]any{
		"openapi": "3.0.3",
		"info":    map[string]any{"title": "API", "version": "1.0.0"},
		"paths": map[string]any{
			"/users": map[string]any{
				"get": map[string]any{"summary": "List users"},
			},
		},
	}

	// Create overlay with multiple actions
	o := &overlay.Overlay{
		Version: "1.0.0",
		Info:    overlay.Info{Title: "Preview Changes", Version: "1.0.0"},
		Actions: []overlay.Action{
			{
				Target: "$.info",
				Update: map[string]any{"x-version": "v2"},
			},
			{
				Target: "$.paths.*",
				Update: map[string]any{"x-tested": true},
			},
		},
	}

	parseResult := &parser.ParseResult{
		Document:     doc,
		SourceFormat: parser.SourceFormatYAML,
	}

	// Preview changes without applying
	result, err := overlay.DryRunWithOptions(
		overlay.WithSpecParsed(*parseResult),
		overlay.WithOverlayParsed(o),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Would apply: %d actions\n", result.WouldApply)
	fmt.Printf("Would skip: %d actions\n", result.WouldSkip)
	for _, change := range result.Changes {
		fmt.Printf("- %s %d node(s) at %s\n", change.Operation, change.MatchCount, change.Target)
	}

}

Output:

Would apply: 2 actions
Would skip: 0 actions
- update 1 node(s) at $.info
- update 1 node(s) at $.paths.*
Example (ParseOverlay)

Example_parseOverlay demonstrates parsing an overlay from YAML. 

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/overlay"
)

func main() {
	yamlData := []byte(`
overlay: 1.0.0
info:
  title: My Overlay
  version: 1.0.0
actions:
  - target: $.info.title
    update: Updated Title
`)

	o, err := overlay.ParseOverlay(yamlData)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Overlay version: %s\n", o.Version)
	fmt.Printf("Overlay title: %s\n", o.Info.Title)
	fmt.Printf("Number of actions: %d\n", len(o.Actions))

}

Output:

Overlay version: 1.0.0
Overlay title: My Overlay
Number of actions: 1
Example (RecursiveDescent)

Example_recursiveDescent demonstrates using $.. to find fields at any depth. 

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/overlay"
	"github.com/erraggy/oastools/parser"
)

func main() {
	// Create a document with descriptions at multiple levels
	doc := map[string]any{
		"openapi": "3.0.3",
		"info": map[string]any{
			"title":       "API",
			"version":     "1.0.0",
			"description": "Top-level description",
		},
		"paths": map[string]any{
			"/users": map[string]any{
				"get": map[string]any{
					"summary":     "List users",
					"description": "Operation description",
					"responses": map[string]any{
						"200": map[string]any{
							"description": "Success response",
						},
					},
				},
			},
		},
	}

	// Update ALL descriptions at any depth using recursive descent
	o := &overlay.Overlay{
		Version: "1.0.0",
		Info:    overlay.Info{Title: "Update Descriptions", Version: "1.0.0"},
		Actions: []overlay.Action{
			{
				Target: "$..description",
				Update: "Updated by overlay",
			},
		},
	}

	parseResult := &parser.ParseResult{
		Document:     doc,
		SourceFormat: parser.SourceFormatYAML,
	}

	// Use dry-run to see how many descriptions would be updated
	result, err := overlay.DryRunWithOptions(
		overlay.WithSpecParsed(*parseResult),
		overlay.WithOverlayParsed(o),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Recursive descent found: %d descriptions\n", result.Changes[0].MatchCount)

}

Output:

Recursive descent found: 3 descriptions
Example (RemoveAction)

Example_removeAction demonstrates using remove actions. 

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/overlay"
	"github.com/erraggy/oastools/parser"
)

func main() {
	// Create a document with internal paths
	doc := map[string]any{
		"openapi": "3.0.3",
		"info":    map[string]any{"title": "API", "version": "1.0.0"},
		"paths": map[string]any{
			"/public": map[string]any{
				"x-internal": false,
				"get":        map[string]any{"summary": "Public endpoint"},
			},
			"/internal": map[string]any{
				"x-internal": true,
				"get":        map[string]any{"summary": "Internal endpoint"},
			},
		},
	}

	// Create overlay to remove internal paths
	o := &overlay.Overlay{
		Version: "1.0.0",
		Info:    overlay.Info{Title: "Remove Internal", Version: "1.0.0"},
		Actions: []overlay.Action{
			{
				Target: "$.paths[?@.x-internal==true]",
				Remove: true,
			},
		},
	}

	parseResult := &parser.ParseResult{
		Document:     doc,
		SourceFormat: parser.SourceFormatYAML,
	}

	result, err := overlay.ApplyWithOptions(
		overlay.WithSpecParsed(*parseResult),
		overlay.WithOverlayParsed(o),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Check remaining paths
	resultDoc := result.Document.(map[string]any)
	paths := resultDoc["paths"].(map[string]any)

	fmt.Printf("Remaining paths: %d\n", len(paths))
	for path := range paths {
		fmt.Printf("- %s\n", path)
	}

}

Output:

Remaining paths: 1
- /public
Example (Validate)

Example_validate demonstrates validating an overlay document. 

package main

import (
	"fmt"

	"github.com/erraggy/oastools/overlay"
)

func main() {
	// Create an invalid overlay (missing required fields)
	o := &overlay.Overlay{
		Version: "1.0.0",
		Info: overlay.Info{
			Title: "Test Overlay",
			// Missing Version
		},
		Actions: []overlay.Action{}, // Empty actions
	}

	// Validate the overlay
	errs := overlay.Validate(o)

	fmt.Printf("Validation errors: %d\n", len(errs))
	for _, err := range errs {
		fmt.Println(err.Message)
	}

}

Output:

Validation errors: 2
version is required
at least one action is required

Index

Examples

Constants

View Source 
const SupportedVersion = "1.0.0"

SupportedVersion is the overlay specification version supported by this implementation.

Variables

This section is empty.

Functions

func IsOverlayDocument 

func IsOverlayDocument(data []byte) bool

IsOverlayDocument checks if the given bytes appear to be an overlay document.

This is a heuristic check that looks for the "overlay" version field. Returns true if the document looks like an overlay, false otherwise.

func IsValid 

func IsValid(o *Overlay) bool

IsValid is a convenience function that returns true if the overlay has no validation errors.

func MarshalOverlay 

func MarshalOverlay(o *Overlay) ([]byte, error)

MarshalOverlay serializes an overlay to YAML bytes.

func ReparseDocument 

func ReparseDocument(original *parser.ParseResult, doc any) (*parser.ParseResult, error)

ReparseDocument re-parses an overlaid document to restore typed structures.

After overlay application, the document becomes a map[string]any. Packages that need typed documents (*parser.OAS2Document or *parser.OAS3Document) can use this function to serialize to YAML and re-parse to restore the typed structure. The original ParseResult's metadata (SourcePath, SourceFormat) is preserved.

Types

type Action 

type Action struct {
	// Target is a JSONPath expression selecting nodes to operate on.
	// This field is required.
	Target string `yaml:"target" json:"target"`

	// Description is an optional human-readable explanation of the action.
	// CommonMark syntax may be used for rich text representation.
	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	// Update specifies content to merge with selected nodes.
	// For objects, properties are recursively merged.
	// For arrays, the update value is appended.
	Update any `yaml:"update,omitempty" json:"update,omitempty"`

	// Remove, when true, removes the target from its parent.
	// Remove takes precedence over Update when both are specified.
	Remove bool `yaml:"remove,omitempty" json:"remove,omitempty"`
}

Action represents a single transformation action in an overlay.

Each action targets specific locations in the OpenAPI document using JSONPath expressions and either updates or removes the matched nodes.

type Applier 

type Applier struct {
	// StrictTargets causes Apply to return an error if any target matches no nodes.
	StrictTargets bool
}

Applier applies overlays to OpenAPI documents.

func NewApplier 

func NewApplier() *Applier

NewApplier creates a new Applier with default settings.

func (*Applier) Apply 

func (a *Applier) Apply(specPath, overlayPath string) (*ApplyResult, error)

Apply applies an overlay to an OpenAPI specification file.

The function parses the specification, applies the overlay transformations, and returns the result. Actions are applied sequentially in order.

func (*Applier) ApplyParsed 

func (a *Applier) ApplyParsed(spec *parser.ParseResult, o *Overlay) (*ApplyResult, error)

ApplyParsed applies an overlay to an already-parsed specification.

This method is useful when you have already parsed the specification or want to apply multiple overlays to the same document.

func (*Applier) DryRun 

func (a *Applier) DryRun(spec *parser.ParseResult, o *Overlay) (*DryRunResult, error)

DryRun previews overlay application without modifying the document.

This method evaluates the overlay against the specification and returns information about what changes would be made, without actually applying them. Useful for previewing changes before committing to them.

type ApplyError 

type ApplyError struct {
	// ActionIndex is the zero-based index of the action that failed.
	ActionIndex int

	// Target is the JSONPath expression that was being evaluated.
	Target string

	// Cause is the underlying error.
	Cause error
}

ApplyError represents an error during overlay application.

func (*ApplyError) Error 

func (e *ApplyError) Error() string

Error implements the error interface.

func (*ApplyError) Unwrap 

func (e *ApplyError) Unwrap() error

Unwrap returns the underlying error for errors.Is/As support.

type ApplyResult 

type ApplyResult struct {
	// Document is the transformed OpenAPI document.
	Document any

	// SourceFormat is the original document format (YAML or JSON).
	SourceFormat parser.SourceFormat

	// ActionsApplied is the number of actions that were successfully applied.
	ActionsApplied int

	// ActionsSkipped is the number of actions that were skipped (e.g., no matches).
	ActionsSkipped int

	// Changes records details of each applied change.
	Changes []ChangeRecord

	// Warnings contains non-fatal issues encountered during application (for backward compatibility).
	Warnings []string

	// StructuredWarnings contains detailed warning information with context.
	StructuredWarnings ApplyWarnings
}

ApplyResult contains the result of applying an overlay to a document.

func ApplyWithOptions 

func ApplyWithOptions(opts ...Option) (*ApplyResult, error)

ApplyWithOptions applies an overlay to a specification using functional options.

This is the recommended API for most use cases. It provides a clean, fluent interface for configuring overlay application.

Example: 

result, err := overlay.ApplyWithOptions(
    overlay.WithSpecFilePath("openapi.yaml"),
    overlay.WithOverlayFilePath("changes.yaml"),
    overlay.WithStrictTargets(true),
)

func (*ApplyResult) AddWarning added in v1.35.0 

func (r *ApplyResult) AddWarning(w *ApplyWarning)

AddWarning adds a structured warning and populates the legacy Warnings slice.

func (*ApplyResult) HasChanges 

func (r *ApplyResult) HasChanges() bool

HasChanges returns true if any actions were applied.

func (*ApplyResult) HasWarnings 

func (r *ApplyResult) HasWarnings() bool

HasWarnings returns true if any warnings were generated.

type ApplyWarning added in v1.35.0 

type ApplyWarning struct {
	// Category identifies the type of warning.
	Category OverlayWarningCategory
	// ActionIndex is the zero-based index of the action.
	ActionIndex int
	// Target is the JSONPath expression.
	Target string
	// Message describes the warning.
	Message string
	// Cause is the underlying error, if applicable.
	Cause error
}

ApplyWarning represents a structured warning from overlay application. It provides detailed context about non-fatal issues encountered during application.

func NewActionErrorWarning added in v1.35.0 

func NewActionErrorWarning(actionIndex int, target string, cause error) *ApplyWarning

NewActionErrorWarning creates a warning when an action execution fails.

func NewNoMatchWarning added in v1.35.0 

func NewNoMatchWarning(actionIndex int, target string) *ApplyWarning

NewNoMatchWarning creates a warning when an action target matches no nodes.

func (*ApplyWarning) HasLocation added in v1.35.0 

func (w *ApplyWarning) HasLocation() bool

HasLocation returns true if this warning has valid action context. An ActionIndex of -1 indicates no location context is available.

func (*ApplyWarning) Location added in v1.35.0 

func (w *ApplyWarning) Location() string

Location returns the action location.

func (*ApplyWarning) String added in v1.35.0 

func (w *ApplyWarning) String() string

String returns a formatted warning message.

func (*ApplyWarning) Unwrap added in v1.35.0 

func (w *ApplyWarning) Unwrap() error

Unwrap returns the underlying error for errors.Is/As support.

type ApplyWarnings added in v1.35.0 

type ApplyWarnings []*ApplyWarning

ApplyWarnings is a collection of ApplyWarning.

func (ApplyWarnings) ByCategory added in v1.35.0 

func (ws ApplyWarnings) ByCategory(cat OverlayWarningCategory) ApplyWarnings

ByCategory filters warnings by category.

func (ApplyWarnings) Strings added in v1.35.0 

func (ws ApplyWarnings) Strings() []string

Strings returns warning messages for backward compatibility.

type ChangeRecord 

type ChangeRecord struct {
	// ActionIndex is the zero-based index of the action in the overlay.
	ActionIndex int

	// Target is the JSONPath expression that was evaluated.
	Target string

	// Operation describes what was done: "update", "remove", or "append".
	Operation string

	// MatchCount is the number of nodes matched by the target.
	MatchCount int
}

ChangeRecord describes a single change made during overlay application.

type DryRunResult 

type DryRunResult struct {
	// WouldApply is the number of actions that would be successfully applied.
	WouldApply int

	// WouldSkip is the number of actions that would be skipped (e.g., no matches).
	WouldSkip int

	// Changes lists the proposed changes that would be made.
	Changes []ProposedChange

	// Warnings contains non-fatal issues that would occur during application (for backward compatibility).
	Warnings []string

	// StructuredWarnings contains detailed warning information with context.
	StructuredWarnings ApplyWarnings
}

DryRunResult contains the result of a dry-run overlay preview.

A dry-run evaluates the overlay without modifying the document, allowing users to see what changes would be made.

func DryRunWithOptions 

func DryRunWithOptions(opts ...Option) (*DryRunResult, error)

DryRunWithOptions previews overlay application using functional options.

Example: 

result, err := overlay.DryRunWithOptions(
    overlay.WithSpecFilePath("openapi.yaml"),
    overlay.WithOverlayFilePath("changes.yaml"),
)
for _, change := range result.Changes {
    fmt.Printf("Would %s %d nodes at %s\n", change.Operation, change.MatchCount, change.Target)
}

func (*DryRunResult) AddWarning added in v1.35.0 

func (r *DryRunResult) AddWarning(w *ApplyWarning)

AddWarning adds a structured warning and populates the legacy Warnings slice.

func (*DryRunResult) HasChanges 

func (r *DryRunResult) HasChanges() bool

HasChanges returns true if any changes would be made.

func (*DryRunResult) HasWarnings 

func (r *DryRunResult) HasWarnings() bool

HasWarnings returns true if any warnings would occur.

type Info 

type Info struct {
	// Title is the human-readable name of the overlay.
	// This field is required.
	Title string `yaml:"title" json:"title"`

	// Version is the version of the overlay document.
	// This field is required.
	Version string `yaml:"version" json:"version"`
}

Info contains metadata about an overlay document.

type Option 

type Option func(*applyConfig) error

Option is a function that configures an overlay application operation.

func WithOverlayFilePath 

func WithOverlayFilePath(path string) Option

WithOverlayFilePath specifies a file path as the overlay input source.

func WithOverlayParsed 

func WithOverlayParsed(o *Overlay) Option

WithOverlayParsed specifies an already-parsed overlay as the input source.

func WithSpecFilePath 

func WithSpecFilePath(path string) Option

WithSpecFilePath specifies a file path or URL as the specification input source.

func WithSpecParsed 

func WithSpecParsed(result parser.ParseResult) Option

WithSpecParsed specifies an already-parsed specification as the input source.

func WithStrictTargets 

func WithStrictTargets(strict bool) Option

WithStrictTargets enables strict mode where unmatched targets cause errors.

By default, actions with targets that match no nodes are skipped with a warning. When strict mode is enabled, such actions cause an error instead.

type Overlay 

type Overlay struct {
	// Version is the overlay specification version (e.g., "1.0.0").
	// This field is required.
	Version string `yaml:"overlay" json:"overlay"`

	// Info contains metadata about the overlay.
	// This field is required.
	Info Info `yaml:"info" json:"info"`

	// Extends is an optional URI reference to the target OpenAPI document.
	// When specified, it indicates which document this overlay is designed for.
	Extends string `yaml:"extends,omitempty" json:"extends,omitempty"`

	// Actions is the ordered list of transformation actions.
	// At least one action is required.
	Actions []Action `yaml:"actions" json:"actions"`
}

Overlay represents an OpenAPI Overlay document (v1.0.0).

The Overlay specification provides a standardized mechanism for augmenting OpenAPI documents through targeted transformations using JSONPath expressions.

func ParseOverlay 

func ParseOverlay(data []byte) (*Overlay, error)

ParseOverlay parses an overlay document from YAML or JSON bytes.

The function automatically detects the format (JSON or YAML) and parses accordingly. Returns the parsed Overlay or an error if parsing fails.

func ParseOverlayFile 

func ParseOverlayFile(path string) (*Overlay, error)

ParseOverlayFile parses an overlay document from a file path.

The function reads the file and parses it as an overlay document. Supports both YAML (.yaml, .yml) and JSON (.json) files.

func ParseOverlaySingle 

func ParseOverlaySingle(o *Overlay, file *string) (*Overlay, error)

ParseOverlaySingle is a helper that returns an overlay from either an instance or a file path.

This is useful for packages that integrate with overlay support and need to handle both pre-parsed overlays and overlay file paths. If the overlay instance is provided, it is returned directly. If only the file path is provided, the overlay is parsed from the file. Returns nil if neither is provided.

type OverlayWarningCategory added in v1.35.0 

type OverlayWarningCategory string

OverlayWarningCategory identifies the type of overlay warning. This type is distinct from joiner.WarningCategory to avoid confusion when both packages are imported. 

const (
	// WarnNoMatch indicates an action target matched no nodes.
	WarnNoMatch OverlayWarningCategory = "no_match"
	// WarnActionError indicates an error executing an action.
	WarnActionError OverlayWarningCategory = "action_error"
)

type ParseError 

type ParseError struct {
	// Path is the file path or source identifier.
	Path string

	// Cause is the underlying error.
	Cause error
}

ParseError represents an error during overlay document parsing.

func (*ParseError) Error 

func (e *ParseError) Error() string

Error implements the error interface.

func (*ParseError) Unwrap 

func (e *ParseError) Unwrap() error

Unwrap returns the underlying error for errors.Is/As support.

type ProposedChange 

type ProposedChange struct {
	// ActionIndex is the zero-based index of the action in the overlay.
	ActionIndex int

	// Target is the JSONPath expression that was evaluated.
	Target string

	// Description is the action's description, if provided.
	Description string

	// Operation describes what would be done: "update", "remove", "replace", or "append".
	Operation string

	// MatchCount is the number of nodes that would be affected.
	MatchCount int

	// MatchedPaths lists the JSONPath locations of matched nodes (up to 10).
	MatchedPaths []string
}

ProposedChange describes a change that would be made during overlay application.

type ValidationError 

type ValidationError struct {
	// Field is the name of the field with the error.
	Field string

	// Path is the location in the overlay document (e.g., "actions[0].target").
	Path string

	// Message describes the validation error.
	Message string
}

ValidationError represents an error in the overlay document structure.

func Validate 

func Validate(o *Overlay) []ValidationError

Validate checks an overlay document for structural errors.

Returns a slice of validation errors. An empty slice indicates the overlay is valid. Validation checks include:

  • Required fields (overlay version, info.title, info.version, actions)
  • Supported overlay version (currently only 1.0.0)
  • Valid JSONPath syntax in action targets
  • Actions have either update or remove (or both)

func (ValidationError) Error 

func (e ValidationError) Error() string

Error implements the error interface.

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.