Documentation
¶
Overview ¶
Package metaschema enumerates every possible edit of an OpenAPI document: each field location in the OpenAPI object model, paired with the syntactic edit actions applicable at that location.
The enumeration is derived independently of the checker's rules, which is the point of the package: it is the yardstick the rules are measured against (see checker/coverage). It comes by reflection from the kin-openapi types oasdiff parses specs into, so a field added upstream shows up as new edits without a manual update here.
Actions are syntactic (add, remove, set, unset, change, increase, decrease), not verdicts: whether an edit is breaking is the checker's judgment. Polarity is the syntactic position in the document (request, response, shared, document); semantic direction inversions (callbacks, webhooks, not-schemas, readOnly/writeOnly) are likewise the checker's business. The exception is NonContracts, which records the fields whose edits cannot change which payloads are valid: that is a fact about the object model, so it belongs with the model.
Schema is a recursive node: the walk stops when a type reappears on the current path, so an edit like paths.*.*.requestBody.content.*.schema.maxLength stands for that keyword at any nesting depth inside the request body schema.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var NonContracts = []NonContract{
{"**.$ref", "a $ref is resolved at load time; the diff compares resolved content"},
{"**.servers.**", "server URLs are deployment metadata, not part of the request/response contract"},
{"**.links.**", "links document relationships between operations; they do not change accepted payloads"},
{"openapi", "the OpenAPI dialect version governs parsing, not the API contract"},
{"jsonSchemaDialect", "schema dialect governs parsing, not the API contract"},
{"info", "the info object is required metadata; its presence is a validation concern"},
{"info.version:set,unset", "version is required; presence changes are validation errors, value changes are checked (api-version rules)"},
{"**.parameters.*.name", "parameters are identified by (name, in); a rename surfaces as parameter remove + add"},
{"**.parameters.*.in", "parameters are identified by (name, in); a location change surfaces as parameter remove + add"},
{"**.headers.*.name", "a header is identified by its map key; the name field is forbidden on Header objects"},
{"**.headers.*.in", "a header is identified by its map key; the in field is forbidden on Header objects"},
{"**.allowEmptyValue", "allowEmptyValue is deprecated by the OpenAPI spec, which advises against its use"},
{"**.schema.$id", "reference-resolution keyword; its effect is visible in the resolved schemas the diff compares"},
{"**.schema.$anchor", "reference-resolution keyword"},
{"**.schema.$dynamicAnchor", "reference-resolution keyword"},
{"**.schema.$dynamicRef", "reference-resolution keyword"},
{"**.schema.$schema", "schema dialect declaration, governs validation semantics at parse time"},
{"**.schema.$defs.**", "$defs holds definitions that take effect only where referenced"},
{"**.schema.$comment", "comments carry no validation semantics"},
}
Functions ¶
func MatchLocation ¶
MatchLocation reports whether a rule's location pattern matches an edit's location. Pattern segments: "**" matches any run of segments (including none), "*" matches exactly one segment, anything else matches literally (so "*" in an edit's location is matched by "*" or "**" in the pattern).
func MatchPattern ¶
MatchPattern reports whether a waiver-style pattern (a location glob with an optional ":action[,action...]" restriction) covers the edit.
func NonContractReason ¶
NonContractReason reports why an edit cannot change which payloads are valid: it edits an annotation, a specification extension, or a field listed in NonContracts, which is read in its listed order so a specific pattern must precede a general one. The second result is false for an edit that can.
Types ¶
type Action ¶
type Action string
Action is a syntactic edit applicable at a location: what can literally happen to the field in the document, independent of whether it breaks clients.
const ( ActionAdd Action = "add" // add a map entry, list element, or set member ActionRemove Action = "remove" // remove a map entry, list element, or set member ActionSet Action = "set" // the field appears where it was absent ActionUnset Action = "unset" // the field disappears ActionChange Action = "change" // the field's value changes to another value ActionIncrease Action = "increase" // an ordered value grows ActionDecrease Action = "decrease" // an ordered value shrinks )
type Claim ¶
Claim is a rule's statement of which edits it covers: a location pattern (see MatchLocation) plus the actions it reports there.
func ParseClaim ¶
ParseClaim parses "pattern:action[,action...]", e.g. "paths.*.*.requestBody.content.*.schema.maxLength:decrease,unset". The pattern is a location pattern (see MatchLocation); a rule's claims usually spell one concrete location, with the wildcards available for covering a family of locations at once.
type Edit ¶
type Edit struct {
Location string
Action Action
Polarity Polarity
Annotation bool // spec-defined metadata (description, summary, ...) with no effect on accepted payloads
Extension bool // an x-* specification extension
}
Edit is one way an OpenAPI document can be modified: an Action applied at a Location.
type NonContract ¶
type NonContract struct {
// Pattern is a location glob (see MatchLocation), optionally restricted
// to actions with ":action[,action...]"; without the suffix it covers
// every action at the location.
Pattern string
Reason string
}
NonContract marks a family of possible edits as outside the wire contract: changing these fields never changes which payloads are valid, so the coverage audit does not expect checks for them. Unlike a coverage waiver in the checker, an entry here is a fact about the OpenAPI object model itself, independent of which checks exist.
Source Files