Comments (19)
@bartkummel I think we'd be open to a configuration option for this. That might be tricky to design in a general manner, but we could start with something that enables your use case and grow it from there as needed.
Maybe a configuration like:
"allowedStringFormats": [ "uuid", "other" ]
Another option is to disable the invalid_type_format_pair
rule altogether, but I'm guessing you want to keep that rule on for its benefits in catching other issues.
from openapi-validator.
@apestov Sure, that's how I interpreted it.
from openapi-validator.
You could use a pattern
. This StackOverflow post recommends a number of different regex's that describe UUIDs.
from openapi-validator.
I think we should be letting users know when they aren't using an explicitly defined format but an error
might be too extreme, since the spec declares users "MAY" use other formats. Perhaps this should be a warning
.
@mkistler What are your thoughts?
from openapi-validator.
The OpenAPI spec allows any value for format
, but values other than the "well defined" values in the OpenAPI spec are ambiguous and thus must be discouraged.
from openapi-validator.
@mkistler Because it is allowed, I think it should be marked as a warning, not an error.
from openapi-validator.
That's not the criteria that we use to decide error vs warning. There's a long list issues we flag as errors that are allowed by the spec.
"no_array_responses": "error",
"no_parameter_description": "error",
"invalid_type_format_pair": "error",
"content_type_parameter": "error", // allowed in v2
"accept_type_parameter": "error", // allowed in
"no_empty_descriptions": "error",
"no_consumes_for_put_or_post": "error",
We flag things as errors when they are 1) common sources of error, 2) generally correctable without huge effort.
Arbitrary values in "format" have been very common in WDC API docs and they cause significant problems in the SDKs, since they result in incorrect types for parameters or properties. I know of no strong argument for using non-standard "format" values, and I am unaware of any effort that is needed to change them other than to edit the API doc.
from openapi-validator.
@mkistler Perhaps it would be better to allow users to whitelist some format types? In case 'I know what I am doing'.
from openapi-validator.
We will be adding some types -- specifically identifier
and crn
-- soon.
Re: "I know what I am doing", I think the more important question is: "Does everyone know what you are doing?" format: gobbledegook
might be perfectly clear to you, but the API doc is meant as a communication mechanism to others.
from openapi-validator.
Well, it depends on particular situation. In my case we use Marshmallow which has explicit uuid type of schema field and write docs in Openapi format for internal use. In such situation uuid format looks ok. May be when we publish the API to the outer world it will be not true, but now 'everyone knows' :)
from openapi-validator.
@mkistler We use uuid
quite often in OpenTripModel, see for yourself in our sources. I see the point you're making. But the fact is, you are stricter than the OAS standard. There is value in that, for sure. But there are also many use cases where that's simply too strict. Would it be an idea to introduce two modes of operation? Like "strict" and "standard" or something like that?
from openapi-validator.
@mkistler Exactly. I've disabled the rule for now, but it would be nice to have something like you suggest.
from openapi-validator.
What do you think if extract to config all allowed type+format pairs for primitive types? Like
"validPrimitiveTypeFormatPairs": {
"integer": ["int32", "int64"],
"number": ["float", "double"],
"string": ["byte", "binary", "date", "date-time", "password"],
"boolean": []
}
e.g. for cases of using ahead OAI/OpenAPI-Specification#845
from openapi-validator.
@apestov I assume your example is the default then? So we can add e.g. uuid
to the string
list in our own configuration file? Sounds good to me!
from openapi-validator.
@bartkummel It's more like a proposal that may (or may not) feet the openapi-validator project approaches.
@mkistler @dpopp07 What do you think? If it sounds ok I can try to prepare a PR.
from openapi-validator.
I think I would prefer an approach that only extended the list of allowed type+format values.
There is a well-defined set of type+format pairs in the spec, and I don't see any value in generating messages for any of these. So a design that would let the user (in all likelihood unintentionally) drop these from the "allowed" list only creates an opportunity for people to shoot themselves in the foot.
from openapi-validator.
That make sense.
Yes, the question would be there a case (project) that would like to have more strict restrictions than linter has by default at the moment or will have by default in some future versions?
It probably could be imagined that some project would like to allow only int64
with no int32
for integer format, while I don't have a particular case for.
from openapi-validator.
Could someone point me at a doc or give a pointer as to the best openapi v3 way to define fields as UUIDs using the standard "5 groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters" format so that the "Property type+format is not well-defined." error is not raised? Is this possible right now in Openapi v3?
from openapi-validator.
Thanks @mkistler - I completely missed that in the Swagger docs here: https://swagger.io/docs/specification/data-models/data-types/#pattern
from openapi-validator.
Related Issues (20)
- collections missing from the openapi-ruleset in version 0.45.3 HOT 5
- Outdated info in ruleset doc HOT 5
- Support for authenticated additional Openapi definitions HOT 1
- missing-required-property rule failed at anyOf required options HOT 1
- v1.0 Community Feedback HOT 3
- Error when I use a customized rule HOT 7
- feature request: Find a way to extend the spectral default ruleset without installing it local HOT 1
- A dependency of this repository contains a critical VM escape vulnerability HOT 5
- Incorrect validation results for the ibm-parameter-casing-convention rule with camelCase HOT 3
- Support Request: how can a rule ignore parameters with a specific name? HOT 3
- ibm-etag-header crashes linter on incorrect specification HOT 4
- Failed to resolve entry for package "ibm-openapi-validator HOT 2
- Rule "ibm-success-response-example" fails for some operations but not others HOT 3
- support for RPC style HTTP calls HOT 4
- Update documentation to reflect latest recommendations HOT 4
- ibm-parameter-description rule should skip responses.links.{name}.parameters HOT 3
- Runtime error for SCIM-compliant schema (object containing $ref attribute) HOT 4
- Fix test failures with Node 20 HOT 3
- BUG: 'Enum values must be snake case' on enums like '400', '500' HOT 4
- Error running lint-openapi since v1.18.1 HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from openapi-validator.