Skip to content

[api-diff] OAS specification extension changes classifcation #24

@b41ex

Description

@b41ex

Changes classification for OAS specification extensions are not supported in api-diff.
Moreover, previously api-unifier throwed away OAS specification extensions.
After implementation of Netcracker/qubership-apihub-api-unifier#1, OAS extensions are now preserved during normalization and with classification rules for them not supported in api-diff it results in incorrect changes identification/classification in some cases (see e.g. Netcracker/qubership-apihub#263)

The question is—how should they be classified?

There are several aspects to this:

  • The compatibility suite currently marks them as non-breaking (though this is explicitly stated in only a couple of places, while in reality, extensions can be used in many more).
  • There's also an opinion that they should actually be unclassified, since we don’t know how extensions are used—meaning changes in their values could be breaking, non-breaking, or risky, depending on their semantics.
  • On the other hand, the spec lists around 20 places where extensions can be added, and in some cases (e.g., the info object, external documentation object), annotation seems like the most fitting classification.

Right now, I think the classification should depend on which object the extension is under—it should be either unclassified or annotation. Need a design for this.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

Status

Ready for Dev

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions