reference

func Parse ¶

func Parse(data []byte) (*Document, error)

Parse decodes an OpenAPI 3.x document from YAML or JSON and normalizes the 3.0/3.1 differences described on Schema. Every failure is an ez.EINVALID error whose message says what is wrong with the input.

func New ¶

func New(spec []byte, opts Options) (*Page, error)

New parses spec (YAML or JSON) and renders it with opts.

func Diff ¶

func Diff(base, head *Document) *Report

Diff compares two documents structurally: operations by method and path, schemas property by property after allOf flattening and ref resolution. Flattening keeps the tightest of the bounds allOf members set, and the keywords written beside a $ref apply together with the model it names, on a schema and on each allOf member alike.

Where both sides refer to the same model, under any spelling of the reference, as a $ref or as single-member allOf wrappers nested around one, with only keywords beside the reference and on each wrapper that give it no structure of its own, that is none of properties, required, items, enum, oneOf, anyOf, not, discriminator and additionalProperties, the model is not expanded: what applies there, the keywords with the model, is compared, the model itself once on its own, and every operation or model that reaches a changed model through references is reported as changed. The use reports a change only when its own keywords change what applies there, compared with the model as the head document has it, so a change to the model alone is reported in the model only; it then reports what applied there before, its keywords with the model as the base document has it, against what applies after. Any other shape is compared in full, such as an allOf of a reference and other members, a reference or a wrapper with structure beside it, or a base reference that leads in the head document to another model than the head side does, and a change inside the model then shows both there and in the model. Two sides whose references in those shapes name the same component, though, refer to that component as the model, also when on one side it only refers to another model, as a component with nothing but a reference does until it gets a keyword of its own, which is then reported once, in that component. A type on one side only, where both sides have oneOf or anyOf variants, as beside a reference to a model that is a oneOf and states no type, is no change when it restates the variants, whether the model is expanded or not: every variant states a type, each of the variant's non-null types is one the type names, an integer counting as a number, and no variant lets null through that the type refuses. Otherwise, as beside variants of string and integer, beside nullable variants, or beside a reference to a model that states no type and has no variants, it is compared like any type.

An allOf of two or more members is nullable when the schema itself says so, or when a member does and every member lets null through, as one that is nullable or that states none of type, enum, const, oneOf, anyOf and not does; a single member, as in the 3.0 spelling of a nullable reference, passes its nullable on.

These limits follow. enum, pattern, multipleOf, const and not, and the oneOf and anyOf lists, like default and the other keywords that cannot be combined across allOf members, are compared as the first one found, the schema's own and then its members' in order, so the list of a second member is not compared. Each keyword is compared on its own, so a change another keyword makes moot is still reported with its own flag: a maxLength changed under an enum whose values all meet both, bounds that admit no value changed for others that admit none either, a const added under an enum of that one value, a minProperties of 1 added where a required property was dropped. A schema with nullable and an enum or const without null is read as letting null through, so nullable removed there is breaking in a request though neither side accepts null, and a oneOf in which two variants let null through is read as letting null through, though the oneOf then refuses it. A schema with a not is read as refusing null, so nullable removed beside a not breaks a request, and given beside one breaks a response, whatever the not refuses. A type of only null is read as the type null, made nullable, so {type: string} or {} to {type: null} reads type changed to null, which narrows, beside made nullable, and the reverse widens, as does {type: null} to {type: [string, null]}, and a oneOf or anyOf of only {type: null} reads as {type: null} does. Given by an allOf member, as in {allOf: [{type: null}]}, or {allOf: [{$ref: N}]} with N {type: null}, it is read as nullable with no type, so {type: string} to that reads type changed from string to any, which widens, though only null is then accepted, and {type: null} to that reads type changed from null to any, breaking a response, though the two say the same. Beside a $ref it is not read as a type either, so {$ref: S} to {$ref: S, type: null}, with S {type: string}, reads made nullable only, which breaks a response only, though nothing is accepted then. Each keyword is compared on its own, so {enum: [null]} or {const: null} to {type: null} reads type changed from any to null, breaking a request, though each accepts only null, and variants given beside type: null narrow, breaking a request only. A {type: null} variant is folded into nullable and is not seen as a type beside the type of its parent, and an enum of only null is read as an enum, not as a type of null. A not is compared as written, see below, so any change inside it is reported once, as not changed, and a model either side names under an odd number of nots, those inside variants counted, that changed is reported where the outermost not stands, or, for a not in a variant of a list whose variants changed otherwise, where that list stands, as not changed: model M changed, its changes judged strictly and with their flags swapped; under an even number it reads model M changed, its changes still judged strictly, with their flags as they are. Judged strictly, enum values added and additional properties allowed again widen the model, and a format added narrows it, one dropped widens it and one changed does both. An optional property added is not judged strictly, though it narrows a model that allows other properties, so under a not in a response it breaks nothing: M: {type: object, properties: {a}} gaining b: {type: integer} refuses {"b": "s"}, which {not: {$ref: M}} then accepts. A type is read as object from properties and additionalProperties and as array from items where none is stated, so a stated type removed beside them is not reported, though the schema then accepts any value; only whether a nullable change is breaking reads no type there. patternProperties is not read, so a property removed from an object that allows no other properties breaks a request even when a pattern still accepts it. Variants added to a oneOf are read as widening, as for an anyOf, though a value that newly matches two of them is refused, a variant listed more or fewer times in a oneOf, which changes the values that match exactly one, breaks nothing, and a list of the same length is compared by position, so variants that were only reordered are reported as changed where they now stand. A comparison that walks references in place, as one of models renamed between the documents, or one through an allOf that joins a model to other members or a reference with structure beside it, which are compared in place even where the documents are the same, can take long: a chain of renamed models in which each refers twice to the next is compared once for every path through it, twice as many with each model; a model whose properties each join it to a bound through an allOf is compared once for every order of those properties, as the walk's cycle guard only stops a schema met again on the same path, so ten such properties take about ten seconds and eleven two minutes, and where each joins it to a not of itself instead, as allOf: [{$ref: M}, {not: {$ref: M}}], the models the nots name are recorded as used at every such path, so memory grows as fast as time: nine take 2 seconds and 0.4 GB, ten 20 seconds and 4.5 GB; a chain of models in which each refers to the next from a property, with structure beside the reference, such as properties, is compared at each model for the rest of the chain, n²/2 schemas for n models, about a second for 2,000, and where what is beside the references changed, the change is reported at every level of every model above it, 2,001,001 changes for 2,000 models, which takes 0.3 seconds and 0.5 GB for 500 models, 2.3 seconds and 3.4 GB for 1,000, and 32 seconds and 24 GB for 2,000; and a chain of models each of which is itself a reference to the next with structure beside it, M0: {$ref: M1, properties: {...}}, takes time cubic in its length, as each model is flattened to the end of the chain, whether or not the documents are the same: seconds for 500 models, tens of seconds for 1,000 and minutes for 2,000, where the same chain written as allOf: [{$ref: M1}, {properties: {...}}] took about as long before too, 2 to 3 seconds for 500 models. A model M changed (through ...) entry names the first 50 of the models it changed through and counts the others. A model that no operation reaches, or that only something the head document added refers to, such as a new operation, property or variant, has no recorded use in a request or a response, so in the Models section, and in the count of breaking changes, each of its changes is breaking when it would break either. A model is used where an operation reaches it also where it is compared in place, its changes then listed there too, as for a property that switched to it from a component that is gone, or one that joins it to other members by an allOf or has structure beside its reference, and so is a component that only refers to another model, as X: {$ref: M} or {allOf: [{$ref: M}]} does, where a reference to it is used, also where one switched to it, or from it, which uses it in the context of the switch, though the use is reported under the model it names. An operation that uses a model reports model M changed with the flag the model's change has in its context, also when keywords at the use mask that change there, as a maxLength of 3 beside a reference does a model's maxLength lowered from 10 to 5.

Breaking changes follow oasdiff. A schema change that narrows the values accepted breaks a request, where a client sending what used to be valid is now refused, and not a response; one that widens them breaks a response, where a client may receive what it was never told to expect, and not a request. Narrowing: a raised minimum or lowered maximum (an exclusive bound is tighter than an inclusive one at the same value, and on a schema of type integer each bound is first taken as the inclusive bound that admits the same integers, so minimum: 1 and exclusiveMinimum: 0 are the same); a raised minLength, minItems or minProperties; a lowered maxLength, maxItems or maxProperties; any of these bounds added, except a minLength, minItems or minProperties of 0, which every value meets; a pattern, multipleOf or const added; uniqueItems set; a type stated where there was none; an enum where there was none, or enum values removed; nullable removed from a schema that then refuses null; a not added; additionalProperties: false, or the false schema written as {not: {}}, with nothing but annotations beside the not or under it, on an object that allowed other properties; items: false, or {not: {}}, on an array that allowed items. Widening: the reverse bound changes, any bound removed, again except a minLength, minItems or minProperties of 0; a pattern, multipleOf or const removed; uniqueItems unset; a type dropped; an enum dropped; nullable added to a schema that refused null; a not dropped; items allowed again. Between two nots, the schemas under them are compared as written, a $ref the same as another where it names the same component, whose model is not compared there, properties, required names, types and enum values in any order, and extensions left out: written the same, they report nothing; different only in annotations, title, description, default, example, examples, deprecated, readOnly and writeOnly, not changed breaks neither; different otherwise, not changed breaks both, as which way a change under a not moves is not worked out, also where only a reference was renamed to a model written the same. Otherwise, a change from one stated type to another, but for a type of only null, see above, and a pattern, multipleOf or const replaced by a different one, break both; enum values added to an enum, additional properties allowed again, as a new response property is, a format change and a default changed, added or removed break neither, and so does a nullable change on a schema that lets null through on both sides, such as one that states no type. When the type changes between integer and number, a bound's detail gives the bound the integer side admitted beside the one written, as in minimum lowered from 0.5 (1 for integers) to 0.7. The schemas of the additional properties of two objects that allow them are compared like any other schemas, under <key>, with the empty schema, which allows any value, standing for additionalProperties: true, {} or none at all, so no change between those three is reported; the items of two schemas of the same type are compared the same way, with the empty schema standing for items absent.

oneOf and anyOf variants are compared by position where both sides have lists of the same keyword and length, each keyword on its own. Any other change of variants is judged from the variants as written, without comparing them, a $ref the same as another when it names the same component, properties, required names, types and enum values in any order, and annotations left out, and breaks both, as which way it moved cannot be told, except in these cases. Variants only added to a list widen, and only removed narrow, and the same variants with one listed more or fewer times break neither. Variants given where there were none, with nothing beside them but annotations and nullable, in place of a schema written as one of them, widen, and dropped back to such a schema narrow; a change of nullable is reported on its own. Variants given beside other keywords narrow, as a value must then match one of them too, and dropped from beside them widen. anyOf turned into oneOf with the same variants narrows, and the reverse widens. The models that the variants kept, written the same on both sides, refer to are recorded as used there, so a change to one reaches the use; a variant added or removed is judged by the change of variants alone, as no client sent or received it there before, or will after. The keywords beside the variants are compared on their own, with their own flags. A 3.1 union of one schema and {type: null}, which Parse folds into that schema made nullable, is compared as the list of that one variant, under the keyword of the other side's variants, where the other side lists variants and the one schema has none of its own once flattened, so a variant added beside it reads as added, as in the 3.0 spelling, and oneOf: [S, I] to anyOf: [S, {type: null}] reads one of variants removed. Where the one schema has variants of its own, the two are compared as they are, as before, so anyOf: [{$ref: U}, {type: null}], with U a oneOf, to the same list with a variant added reads one of variants changed to any of, breaking both, though it only widens.

The other breaking changes: a removed operation; a removed (or renamed) response property, or a property removed from an object that allows no other properties, or whose additionalProperties schema limits values and is not written as the property's schema was, annotations left out and a $ref the same as another where it names the same component, which breaks a request that still sends it too, also where that schema accepts every value the property's did, as the two are not compared, while where it is written so and the object allowed no other properties before, the models that schema names are used there, so their changes reach the request; a removed response header, or one no longer required; a response property no longer required, which a response may now leave out; a new required request property, parameter or request body; an existing request property, parameter or request body made required, also a name required where no property of that name is declared. A response header named Content-Type is not compared, as OpenAPI says its definition is ignored. Everything else is a non-breaking change.