Azure / Azure/azure-sdk-tools

[Breaking Change] Some validation errors are useless at a glance and often require separate tools to understand

Open
#5,713 2 comments 0 reactions 0 assignees View on GitHub
Breaking Changes Central-EngSys Spec PR Tools
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
143

Description

Many of our validation errors are pretty self-explanatory, but some like below are confusing at best and useless at a glance at worst:

![image](https://user-images.githubusercontent.com/1532486/225400817-7b688e45-9f64-4b24-98f2-302de335b8bb.png)

1. Because there are two different base version comparisons, when validation mentions "old" or "new" - which version? Validations with links are much more helpful.
2. Why do only some validation errors have links? Seems they all could / should.
3. Barring links for all validations, can you at least tell us what model? Properties like `id` are prolific so a validation error mentioning only "id" isn't useful.

Ideally, swagger authors are able to determine what they need to fix (or otherwise get an exemption on / explain) but I look at numerous swagger diffs a day and I can't really make heads or tails of these issues without having to use the OpenAPI Diff tool which is slow and often fails.

Contributor guide

Open the contributing guide

Research direction

Start by examining the validation output shown in the issue and comparing it with the OpenAPI Diff tool’s more informative results for Swagger diffs. Done means validation errors consistently identify the relevant base-version comparison, link to useful context where possible, and name the model when properties such as id are ambiguous.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.