formatters

package
v1.17.0 Latest Latest
Warning

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

 Go to latest Published: May 28, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package formatters transforms oasdiff output into various formats for display and integration.

Overview

The formatters package provides a unified interface for rendering diff results, changelog, and breaking changes in multiple output formats suitable for different use cases.

Usage

Get a formatter and render output: 

formatter, err := formatters.Lookup("json", formatters.FormatterOpts{Language: "en"})
output, err := formatter.RenderChangelog(changes, formatters.RenderOpts{}, baseVersion, revisionVersion)

Available Formats

  • yaml: YAML output for programmatic consumption
  • json: JSON output for programmatic consumption
  • text: Human-readable text output for terminals
  • markup/markdown: Markdown format for documentation
  • singleline: One-line-per-change format for parsing
  • html: HTML format for web display
  • githubactions: GitHub Actions workflow command format (::error, ::warning)
  • junit: JUnit XML format for CI/CD test reporting

Formatter Interface

All formatters implement the Formatter interface with methods:

  • RenderDiff: render a diff report
  • RenderSummary: render a summary of changes
  • RenderChangelog: render breaking changes and changelog
  • RenderChecks: render available check rules
  • RenderFlatten: render a flattened spec

Localization

Formatters support localization through the Language option in FormatterOpts. Change messages are translated using the checker/localizations package.

Output Types

Use SupportedOutputs() to check which output types a formatter supports:

  • OutputDiff, OutputSummary, OutputChangelog, OutputChecks, OutputFlatten

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ComputeFingerprint added in v1.16.0 

func ComputeFingerprint(id, operation, path string, args []any) string

ComputeFingerprint produces a short, stable identifier for a change or finding. It is used to match the same logical item across spec versions (carry-forward of review state in oasdiff-service) and to look up review records at view time. The changelog and validate commands share it so a downstream tool can match findings produced by either.

Inputs are the structured rule arguments rather than the rendered text: rendered text varies with locale and copy edits to the message templates, which would silently invalidate every stored fingerprint. The args carry the same per-change disambiguation power without that fragility.

func ExecuteHtmlTemplate 

func ExecuteHtmlTemplate(tmpl *template.Template, changes ChangesByGroup, baseVersion, revisionVersion string, diffEmpty, isBreaking bool) ([]byte, error)

func ExecuteTextTemplate 

func ExecuteTextTemplate(tmpl *template.Template, changes ChangesByGroup, baseVersion, revisionVersion string, diffEmpty, isBreaking bool) ([]byte, error)

func GetSupportedFormats 

func GetSupportedFormats() []string

func GetSupportedTemplateFormats added in v1.11.5 

func GetSupportedTemplateFormats() []string

func HtmlTemplateFuncs added in v1.12.5 

func HtmlTemplateFuncs() template.FuncMap

HtmlTemplateFuncs returns the FuncMap available to HTML changelog templates.

func MarkupTemplateFuncs added in v1.12.5 

func MarkupTemplateFuncs() template.FuncMap

MarkupTemplateFuncs returns the FuncMap available to Markup changelog templates.

func SupportedFormatsByContentType 

func SupportedFormatsByContentType(output Output) []string

Types

type Change 

type Change struct {
	Id             string          `json:"id,omitempty" yaml:"id,omitempty"`
	Text           string          `json:"text,omitempty" yaml:"text,omitempty"`
	Comment        string          `json:"comment,omitempty" yaml:"comment,omitempty"`
	Level          checker.Level   `json:"level" yaml:"level"`
	Operation      string          `json:"operation,omitempty" yaml:"operation,omitempty"`
	OperationId    string          `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Path           string          `json:"path,omitempty" yaml:"path,omitempty"`
	Source         string          `json:"source,omitempty" yaml:"source,omitempty"`
	Section        string          `json:"section,omitempty" yaml:"section,omitempty"`
	IsBreaking     bool            `json:"-" yaml:"-"`
	Attributes     map[string]any  `json:"attributes,omitempty" yaml:"attributes,omitempty"`
	BaseSource     *checker.Source `json:"baseSource,omitempty" yaml:"baseSource,omitempty"`
	RevisionSource *checker.Source `json:"revisionSource,omitempty" yaml:"revisionSource,omitempty"`
	Fingerprint    string          `json:"fingerprint,omitempty" yaml:"fingerprint,omitempty"`
}

type ChangeGroup added in v1.12.5 

type ChangeGroup struct {
	Section   string
	Path      string
	Operation string
}

type Changes 

type Changes []Change

func NewChanges 

func NewChanges(originalChanges checker.Changes, l checker.Localizer) Changes

type ChangesByGroup added in v1.12.5 

type ChangesByGroup map[ChangeGroup]*Changes

func GroupChanges 

func GroupChanges(changes checker.Changes, l checker.Localizer) ChangesByGroup

type Check 

type Check struct {
	Id          string `json:"id" yaml:"id"`
	Level       string `json:"level" yaml:"level"`
	Direction   string `json:"direction" yaml:"direction"`
	Location    string `json:"location" yaml:"location"`
	Action      string `json:"action" yaml:"action"`
	Description string `json:"description" yaml:"description"`
	Mitigation  string `json:"mitigation,omitempty" yaml:"mitigation,omitempty"`
}

type Checks 

type Checks []Check

func (Checks) SortFunc added in v1.11.10 

func (checks Checks) SortFunc(a, b Check) int

type Finding added in v1.16.0 

type Finding struct {
	Id          string        `yaml:"id"                    json:"id"`
	Text        string        `yaml:"text"                  json:"text"`
	Comment     string        `yaml:"comment,omitempty"     json:"comment,omitempty"`
	Level       checker.Level `yaml:"level"                 json:"level"`
	Operation   string        `yaml:"operation,omitempty"   json:"operation,omitempty"`
	Path        string        `yaml:"path,omitempty"        json:"path,omitempty"`
	Section     string        `yaml:"section"               json:"section"`
	Source      Source        `yaml:"source"                json:"source"`
	Fingerprint string        `yaml:"fingerprint"           json:"fingerprint"`
}

Finding is a single spec-validation finding produced by the `validate` command.

Comment, Operation, and Path use omitempty because doc-root findings (e.g. info-version-required) have no operation/path scope.

Source.Line and Source.Column are populated when the loader tracks origins and the underlying error carries the offending element's location; both are 0 for doc-root fields with no per-key origin.

Fingerprint is a stable 12-char identifier (see ComputeFingerprint) that lets a downstream tool match the same logical finding across base/revision spec versions.

type Findings added in v1.16.0 

type Findings []Finding

func (Findings) GetLevelCount added in v1.16.0 

func (findings Findings) GetLevelCount() map[checker.Level]int

GetLevelCount returns the number of findings at each severity level, mirroring checker.Changes.GetLevelCount.

func (Findings) HasLevelOrHigher added in v1.16.0 

func (findings Findings) HasLevelOrHigher(level checker.Level) bool

HasLevelOrHigher reports whether any finding is at least as severe as level, mirroring checker.Changes.HasLevelOrHigher. Used to decide the validate command's exit code against its --fail-on threshold.

type Format 

type Format string
const (
	FormatYAML          Format = "yaml"
	FormatJSON          Format = "json"
	FormatText          Format = "text"
	FormatMarkup        Format = "markup"
	FormatMarkdown      Format = "markdown"
	FormatSingleLine    Format = "singleline"
	FormatHTML          Format = "html"
	FormatGithubActions Format = "githubactions"
	FormatJUnit         Format = "junit"
	FormatSarif         Format = "sarif"
)

type Formatter 

type Formatter interface {
	RenderDiff(diff *diff.Diff, opts RenderOpts) ([]byte, error)
	RenderSummary(diff *diff.Diff, opts RenderOpts) ([]byte, error)
	RenderChangelog(changes checker.Changes, opts RenderOpts, baseVersion, revisionVersion string) ([]byte, error)
	RenderChecks(checks Checks, opts RenderOpts) ([]byte, error)
	RenderFlatten(spec *openapi3.T, opts RenderOpts) ([]byte, error)
	RenderValidate(findings Findings, opts RenderOpts) ([]byte, error)
	SupportedOutputs() []Output
	SupportsTemplate() bool
}

Formatter is a common interface for output formatters

func Lookup 

func Lookup(format string, opts FormatterOpts) (Formatter, error)

Lookup returns a formatter by its name

type FormatterOpts 

type FormatterOpts struct {
	Language string
}

FormatterOpts can be used to pass properties to the formatter (e.g. colors)

func DefaultFormatterOpts 

func DefaultFormatterOpts() FormatterOpts

DefaultFormatterOpts returns the default formatter options (e.g. colors, CI mode, etc.)

type GitHubActionsFormatter 

type GitHubActionsFormatter struct {
	Localizer checker.Localizer
	// contains filtered or unexported fields
}

func (GitHubActionsFormatter) RenderChangelog 

func (f GitHubActionsFormatter) RenderChangelog(changes checker.Changes, opts RenderOpts, _, _ string) ([]byte, error)

func (GitHubActionsFormatter) RenderChecks 

func (f GitHubActionsFormatter) RenderChecks(Checks, RenderOpts) ([]byte, error)

func (GitHubActionsFormatter) RenderDiff 

func (f GitHubActionsFormatter) RenderDiff(*diff.Diff, RenderOpts) ([]byte, error)

func (GitHubActionsFormatter) RenderFlatten 

func (f GitHubActionsFormatter) RenderFlatten(*openapi3.T, RenderOpts) ([]byte, error)

func (GitHubActionsFormatter) RenderSummary 

func (f GitHubActionsFormatter) RenderSummary(*diff.Diff, RenderOpts) ([]byte, error)

func (GitHubActionsFormatter) RenderValidate added in v1.16.0 

func (f GitHubActionsFormatter) RenderValidate(findings Findings, opts RenderOpts) ([]byte, error)

RenderValidate emits one GitHub Actions annotation per finding so the oasdiff-action validate wrapper can surface violations inline on the PR's Files Changed tab, and publishes per-severity counts as step outputs. Findings carry exact file/line/column, which the annotation uses to anchor itself.

func (GitHubActionsFormatter) SupportedOutputs 

func (f GitHubActionsFormatter) SupportedOutputs() []Output

func (GitHubActionsFormatter) SupportsTemplate added in v1.11.5 

func (f GitHubActionsFormatter) SupportsTemplate() bool

type GroupEntry added in v1.12.5 

type GroupEntry struct {
	Group   ChangeGroup
	Changes *Changes
}

GroupEntry is a Group+Changes pair used in sorted template iteration.

type HTMLFormatter 

type HTMLFormatter struct {
	Localizer checker.Localizer
	// contains filtered or unexported fields
}

func (HTMLFormatter) RenderChangelog 

func (f HTMLFormatter) RenderChangelog(changes checker.Changes, opts RenderOpts, baseVersion, revisionVersion string) ([]byte, error)

func (HTMLFormatter) RenderChecks 

func (f HTMLFormatter) RenderChecks(Checks, RenderOpts) ([]byte, error)

func (HTMLFormatter) RenderDiff 

func (f HTMLFormatter) RenderDiff(diff *diff.Diff, opts RenderOpts) ([]byte, error)

func (HTMLFormatter) RenderFlatten 

func (f HTMLFormatter) RenderFlatten(*openapi3.T, RenderOpts) ([]byte, error)

func (HTMLFormatter) RenderSummary 

func (f HTMLFormatter) RenderSummary(*diff.Diff, RenderOpts) ([]byte, error)

func (HTMLFormatter) RenderValidate added in v1.16.0 

func (f HTMLFormatter) RenderValidate(Findings, RenderOpts) ([]byte, error)

func (HTMLFormatter) SupportedOutputs 

func (f HTMLFormatter) SupportedOutputs() []Output

func (HTMLFormatter) SupportsTemplate added in v1.11.5 

func (f HTMLFormatter) SupportsTemplate() bool

type JSONFormatter 

type JSONFormatter struct {
	Localizer checker.Localizer
	// contains filtered or unexported fields
}

func (JSONFormatter) RenderChangelog 

func (f JSONFormatter) RenderChangelog(changes checker.Changes, opts RenderOpts, _, _ string) ([]byte, error)

func (JSONFormatter) RenderChecks 

func (f JSONFormatter) RenderChecks(checks Checks, opts RenderOpts) ([]byte, error)

func (JSONFormatter) RenderDiff 

func (f JSONFormatter) RenderDiff(diff *diff.Diff, opts RenderOpts) ([]byte, error)

func (JSONFormatter) RenderFlatten 

func (f JSONFormatter) RenderFlatten(spec *openapi3.T, opts RenderOpts) ([]byte, error)

func (JSONFormatter) RenderSummary 

func (f JSONFormatter) RenderSummary(diff *diff.Diff, opts RenderOpts) ([]byte, error)

func (JSONFormatter) RenderValidate added in v1.16.0 

func (f JSONFormatter) RenderValidate(findings Findings, opts RenderOpts) ([]byte, error)

func (JSONFormatter) SupportedOutputs 

func (f JSONFormatter) SupportedOutputs() []Output

func (JSONFormatter) SupportsTemplate added in v1.11.5 

func (f JSONFormatter) SupportsTemplate() bool

type JUnitFailure 

type JUnitFailure struct {
	Message string `xml:"message,attr"`
	CDATA   string `xml:",innerxml"`
}

type JUnitFormatter 

type JUnitFormatter struct {
	Localizer checker.Localizer
	// contains filtered or unexported fields
}

func (JUnitFormatter) RenderChangelog 

func (f JUnitFormatter) RenderChangelog(changes checker.Changes, opts RenderOpts, _, _ string) ([]byte, error)

func (JUnitFormatter) RenderChecks 

func (f JUnitFormatter) RenderChecks(Checks, RenderOpts) ([]byte, error)

func (JUnitFormatter) RenderDiff 

func (f JUnitFormatter) RenderDiff(*diff.Diff, RenderOpts) ([]byte, error)

func (JUnitFormatter) RenderFlatten 

func (f JUnitFormatter) RenderFlatten(*openapi3.T, RenderOpts) ([]byte, error)

func (JUnitFormatter) RenderSummary 

func (f JUnitFormatter) RenderSummary(*diff.Diff, RenderOpts) ([]byte, error)

func (JUnitFormatter) RenderValidate added in v1.16.0 

func (f JUnitFormatter) RenderValidate(Findings, RenderOpts) ([]byte, error)

func (JUnitFormatter) SupportedOutputs 

func (f JUnitFormatter) SupportedOutputs() []Output

func (JUnitFormatter) SupportsTemplate added in v1.11.5 

func (f JUnitFormatter) SupportsTemplate() bool

type JUnitTestCase 

type JUnitTestCase struct {
	Name      string        `xml:"name,attr"`
	Classname string        `xml:"classname,attr"`
	Time      string        `xml:"time,attr"`
	Failure   *JUnitFailure `xml:"failure,omitempty"`
}

type JUnitTestSuite 

type JUnitTestSuite struct {
	XMLName   xml.Name        `xml:"testsuite"`
	Package   string          `xml:"package,attr"`
	Time      string          `xml:"time,attr"`
	Tests     int             `xml:"tests,attr"`
	Errors    int             `xml:"errors,attr"`
	Failures  int             `xml:"failures,attr"`
	Name      string          `xml:"name,attr"`
	TestCases []JUnitTestCase `xml:"testcase"`
}

type JUnitTestSuites 

type JUnitTestSuites struct {
	XMLName    xml.Name         `xml:"testsuites"`
	TestSuites []JUnitTestSuite `xml:"testsuites"`
}

type MarkupFormatter 

type MarkupFormatter struct {
	Localizer checker.Localizer
	// contains filtered or unexported fields
}

func (MarkupFormatter) RenderChangelog 

func (f MarkupFormatter) RenderChangelog(changes checker.Changes, opts RenderOpts, baseVersion, revisionVersion string) ([]byte, error)

func (MarkupFormatter) RenderChecks 

func (f MarkupFormatter) RenderChecks(Checks, RenderOpts) ([]byte, error)

func (MarkupFormatter) RenderDiff 

func (f MarkupFormatter) RenderDiff(diff *diff.Diff, opts RenderOpts) ([]byte, error)

func (MarkupFormatter) RenderFlatten 

func (f MarkupFormatter) RenderFlatten(*openapi3.T, RenderOpts) ([]byte, error)

func (MarkupFormatter) RenderSummary 

func (f MarkupFormatter) RenderSummary(*diff.Diff, RenderOpts) ([]byte, error)

func (MarkupFormatter) RenderValidate added in v1.16.0 

func (f MarkupFormatter) RenderValidate(Findings, RenderOpts) ([]byte, error)

func (MarkupFormatter) SupportedOutputs 

func (f MarkupFormatter) SupportedOutputs() []Output

func (MarkupFormatter) SupportsTemplate added in v1.11.5 

func (f MarkupFormatter) SupportsTemplate() bool

type Output 

type Output int
const (
	OutputDiff Output = iota
	OutputSummary
	OutputChangelog
	OutputChecks
	OutputFlatten
	OutputValidate
)

type RenderOpts 

type RenderOpts struct {
	ColorMode    checker.ColorMode
	WrapInObject bool   // wrap the output in a JSON object with the key "changes"
	TemplatePath string // path to custom template file for changelog generation
	DiffEmpty    bool   // true when the underlying diff found no changes at all
	IsBreaking   bool   // true when invoked via `oasdiff breaking` (vs `changelog`); affects empty-result wording
}

RenderOpts can be used to pass properties to the renderer method

func NewRenderOpts 

func NewRenderOpts() RenderOpts

type SingleLineFormatter 

type SingleLineFormatter struct {
	Localizer checker.Localizer
	// contains filtered or unexported fields
}

func (SingleLineFormatter) RenderChangelog 

func (f SingleLineFormatter) RenderChangelog(changes checker.Changes, opts RenderOpts, _, _ string) ([]byte, error)

func (SingleLineFormatter) RenderChecks 

func (f SingleLineFormatter) RenderChecks(Checks, RenderOpts) ([]byte, error)

func (SingleLineFormatter) RenderDiff 

func (f SingleLineFormatter) RenderDiff(*diff.Diff, RenderOpts) ([]byte, error)

func (SingleLineFormatter) RenderFlatten 

func (f SingleLineFormatter) RenderFlatten(*openapi3.T, RenderOpts) ([]byte, error)

func (SingleLineFormatter) RenderSummary 

func (f SingleLineFormatter) RenderSummary(*diff.Diff, RenderOpts) ([]byte, error)

func (SingleLineFormatter) RenderValidate added in v1.16.0 

func (f SingleLineFormatter) RenderValidate(Findings, RenderOpts) ([]byte, error)

func (SingleLineFormatter) SupportedOutputs 

func (f SingleLineFormatter) SupportedOutputs() []Output

func (SingleLineFormatter) SupportsTemplate added in v1.11.5 

func (f SingleLineFormatter) SupportsTemplate() bool

type Source added in v1.16.0 

type Source struct {
	File   string `yaml:"file"             json:"file"`
	Line   int    `yaml:"line,omitempty"   json:"line,omitempty"`
	Column int    `yaml:"column,omitempty" json:"column,omitempty"`
}

Source identifies the spec location of a finding. File is the spec path; Line and Column come from origin tracking and are 0 for doc-root findings that have no per-key origin.

type TEXTFormatter 

type TEXTFormatter struct {
	Localizer checker.Localizer
	// contains filtered or unexported fields
}

func (TEXTFormatter) RenderChangelog 

func (f TEXTFormatter) RenderChangelog(changes checker.Changes, opts RenderOpts, _, _ string) ([]byte, error)

func (TEXTFormatter) RenderChecks 

func (f TEXTFormatter) RenderChecks(checks Checks, opts RenderOpts) ([]byte, error)

func (TEXTFormatter) RenderDiff 

func (f TEXTFormatter) RenderDiff(diff *diff.Diff, opts RenderOpts) ([]byte, error)

func (TEXTFormatter) RenderFlatten 

func (f TEXTFormatter) RenderFlatten(*openapi3.T, RenderOpts) ([]byte, error)

func (TEXTFormatter) RenderSummary 

func (f TEXTFormatter) RenderSummary(*diff.Diff, RenderOpts) ([]byte, error)

func (TEXTFormatter) RenderValidate added in v1.16.0 

func (f TEXTFormatter) RenderValidate(findings Findings, opts RenderOpts) ([]byte, error)

RenderValidate emits a summary line ("N findings: ...") followed by one changelog-style block per finding. Each block is: 

error	[<rule-id>] at <file:line:column>
	<text>

Findings with operation context add an "in API METHOD /path" line and indent the message one level deeper. Level is colorized and the rule ID rendered yellow when --color is on, matching changelog / breaking.

func (TEXTFormatter) SupportedOutputs 

func (f TEXTFormatter) SupportedOutputs() []Output

func (TEXTFormatter) SupportsTemplate added in v1.11.5 

func (f TEXTFormatter) SupportsTemplate() bool

type TemplateData 

type TemplateData struct {
	GroupedChanges  ChangesByGroup
	BaseVersion     string
	RevisionVersion string
	DiffEmpty       bool
	IsBreaking      bool
}

func (TemplateData) APIChanges 

func (t TemplateData) APIChanges() ChangesByGroup

APIChanges returns GroupedChanges. Deprecated: Use .GroupedChanges in templates instead. Kept for backward compatibility with custom templates.

func (TemplateData) GetVersionTitle added in v1.11.4 

func (t TemplateData) GetVersionTitle() string

type YAMLFormatter 

type YAMLFormatter struct {
	Localizer checker.Localizer
	// contains filtered or unexported fields
}

func (YAMLFormatter) RenderChangelog 

func (f YAMLFormatter) RenderChangelog(changes checker.Changes, opts RenderOpts, _, _ string) ([]byte, error)

func (YAMLFormatter) RenderChecks 

func (f YAMLFormatter) RenderChecks(checks Checks, opts RenderOpts) ([]byte, error)

func (YAMLFormatter) RenderDiff 

func (f YAMLFormatter) RenderDiff(diff *diff.Diff, opts RenderOpts) ([]byte, error)

func (YAMLFormatter) RenderFlatten 

func (f YAMLFormatter) RenderFlatten(spec *openapi3.T, opts RenderOpts) ([]byte, error)

func (YAMLFormatter) RenderSummary 

func (f YAMLFormatter) RenderSummary(diff *diff.Diff, opts RenderOpts) ([]byte, error)

func (YAMLFormatter) RenderValidate added in v1.16.0 

func (f YAMLFormatter) RenderValidate(findings Findings, opts RenderOpts) ([]byte, error)

func (YAMLFormatter) SupportedOutputs 

func (f YAMLFormatter) SupportedOutputs() []Output

func (YAMLFormatter) SupportsTemplate added in v1.11.5 

func (f YAMLFormatter) SupportsTemplate() bool

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.