-
-
Notifications
You must be signed in to change notification settings - Fork 579
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Validation errors in various specs #540
Comments
Yes, there are some errors the validator used historically in this project does not spot. Unfortunately it will be quite a lot of work to move away from it. |
Ok, that makes sense, thanks. It doesn't block me at all, so I'm not too worried, I mainly just filed this for reference later. Even if the current validator doesn't validate this automatically, is there a reason these can't be fixed up by hand? I'm going to be doing a bunch of openapi work at the moment, so I'd be happy to chip in. |
I think we can fix up the |
If you're planning on integrating with the directory, please feel free to PR against the README whenever is appropriate. Just FYI, the definitions which originate in non-OpenAPI 2.0 format (primarily Amazon AWS and Google Cloud Services) will be updated to OpenAPI 3.0 by May, |
Update: we now no longer use the more lax OpenAPI v2.0 validator. All issues except |
Hi, I have been testing the ApiGuru dataset today using openapi-schema-validator and out of 2278 unique items (taking only the latest versions) it resulted in 7 failures:
A full description of the errors can be found at: https://github.com/seriousme/openapi-schema-validator/blob/master/test/realworld/failed.json openapi-schema-validator uses the OpenApi.org json schemas and AJV to validate specs. Can you confirm that these errors are errors in the API's and not in the schemas/validation ? Kind regards, |
I did some more analysis:
"400":
$ref: "#/responses/FailedPrecondition"
description: Individual has related resources and cannot be deleted A response needs to contain either a $ref or a description, not both
- description: Must be the content of a tar archive compressed with gzip. The
archive must include a file called 'Dockerfile' at its root. It may
include any number of other files which will be accessible in the
build context.
in: body
name: file
required: true
type: file OpenApi 3.x requires file uploads to be a requestBody type,
"/itv/subscription/status/{platform}":
get:
"400":
description: Bad request.
schema:
$ref: "#/components/schemas/ServiceError"
"404":
description: Not found.
schema:
$ref: "#/components/schemas/ServiceError"
"415":
description: Unsupported Media Type
schema:
$ref: "#/components/schemas/ServiceError"
"500":
description: Internal server error.
schema:
$ref: "#/components/schemas/ServiceError"
default:
description: Service error.
schema:
$ref: "#/components/schemas/ServiceError"
description: Returns status of latest payment intent.
operationId: getSubscriptionStatus
parameters: https://github.com/APIs-guru/openapi-directory/blob/main/APIs/britbox.co.uk/3.730.281-ref-1-39-0/openapi.yaml#L6668-L6691
securitySchemes:
access_token:
bearerFormat: null
scheme: bearer
type: http https://github.com/APIs-guru/openapi-directory/blob/main/APIs/keycloak.local/1/openapi.yaml#L8642-L8646
/apod:
get:
descriptions: Returns the picture of the day
parameters: https://github.com/APIs-guru/openapi-directory/blob/main/APIs/nasa.gov/apod/1.0.0/openapi.yaml#L35-L38
schema:
additionalProperties:
$ref: "#/definitions/CliOption"
originalRef: CliOption
type: object https://github.com/APIs-guru/openapi-directory/blob/main/APIs/openapi-generator.tech/5.1.1/swagger.yaml#L59-L63
CloudArchivedFiles:
additionalProperties: false
properties:
archive_files:
additionalItems: true
description: An explanation about the purpose of this instance.
items:
... This spec is 5.1Mb so GitHub won't link to linenumbers, however there are some issues with Hope this helps. Kind regards, |
@seriousme thank you for the report and analysis. When you are processing files named |
According to the 3.0 spec, additional properties in a reference object are ignored (not disallowed). |
According to the v3.0 spec:
|
@seriousme britbox, keycloak and nasa/apod definitions fixed. Many thanks. |
You're welcome !
My tooling does not look at filenames but checks for the contents the toplevel "swagger" or "openapi" property in the spec, so the error is probably right, but my interpretation of the error was wrong ;-)
Yikes, not a smart move of the spec makers to call it the same but spec it differently. I checked the 3.0.0 schema and it does cover this difference in schema. So there must be some other issue. I will try to do some more digging on this one ;-) But there is good news: it is fixed in 3.1.0 ;-) To summarize, I still need to figure out why:
do not match the official OpenApi JSON schema definitions. Kind regards, |
Did some more digging as promised :-) ato.gov.auI loaded the The text of the spec says indeed:
https://spec.openapis.org/oas/v3.0.0#reference-object
https://github.com/seriousme/openapi-schema-validator/blob/master/schemas/v3.0/schema.json#L53-L64 openapi-generator.techSame explanation as for the bluemix.net:containersLoading the
This matches the Swagger 2.0 spec section 6.4.9.1 Fixed Fields
and
and the zoom.usAgain the loading the spec up into swagger editor gives a better explanation of what is wrong:
The schema only breaks at the Hope this helps ! Hans |
This also is not an error, in v3.0.0 requestBodies on methods which have undefined behaviour are ignored. Thanks for spotting the Path |
Thanks for the quick reply ! (and your patience ;-)) I did a test and you are completely right on the additionalProperties (not that I doubted that ;-)). If I supply AJV draft 4 (the schema validator I use) with the schema: {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [
"$ref"
],
"patternProperties": {
"^\\$ref$": {
"type": "string",
"format": "uri-reference"
}
}
} Then: {
"$ref": "#/ref",
"description": "my description",
"originalRef": "original"
} Is valid ! So the combination of I think I solved the mystery: The v2.0 specification says:
https://spec.openapis.org/oas/v2.0#reference-object And the V2.0 JSON schema is also quite strict on this one: "jsonReference": {
"type": "object",
"required": [
"$ref"
],
"additionalProperties": false,
"properties": {
"$ref": {
"type": "string"
}
}
} Kind regards, |
I'm using https://github.com/Mermade/oas-kit/blob/master/packages/swagger2openapi/README.md to batch convert specs to OpenAPI v3. In doing so, I'm seeing quite a few specs with errors.
It's possible that these are an issue in that tool, but having checked a few cases they do appear to be legitimate errors to me. For example, many of the Azure specs reference files like
apimusers.json
, which don't exist anywhere in this repo, and quite a few specs do usecollectionFormat
with non-array parameters, which is indeed invalid.Here's the list:
Edit: should be fixed
archive.org/search/1.0.0/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arrayarchive.org/wayback/1.0.0/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arraytraccar.org/4.3/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arraygoogleapis.com/bigquerydatatransfer/v1/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arraysimplyrets.com/1.0.0/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arraygoogleapis.com/cloudiot/v1/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arraynetlicensing.io/2.x/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arrayzalando.com/v1.0/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arrayazure.com/applicationinsights-swagger/2018-04-20/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arrayazure.com/cognitiveservices-Face/1.0/swagger.yaml
: (Patchable) collectionFormat is only applicable to param.type arrayEdit: should be fixed
geneea.com/1.0/swagger.yaml
: Could not resolve reference #/definitions/Information%20about%20a%20user%20account.clarify.io/1.3.7/swagger.yaml
: Could not resolve reference #/definitions/Ref%20(of%20Bundle)taggun.io/1.2.90/swagger.yaml
: Could not resolve reference #/definitions/Model%201semantria.com/4.0/swagger.yaml
: Could not resolve reference #/definitions/Request%20classclever-cloud.com/1.0.0/swagger.yaml
: Could not resolve reference #/definitions/Transaction%20Idje-apis.com/2.0.0.0/swagger.yaml
: Could not resolve reference #/definitions/JE.Api.Payments.Contracts.StatusCode%60%5B%5BJE.Api.Payments.Contracts.CheckingOut.AuthorisationReasonTypes,%20JE.Api.Payments.Contracts,%20Version=6.16.0.0,%20Culture=neutral,%20PublicKeyToken=null%5D%5Depa.gov/case/1.0.0/swagger.yaml
: (Patchable) parameter.type is mandatory for non-body parametersEdit: should be fixed - Reported upstream some time ago
OpenBankingUK/opendata-api-spec-compiled#1
openbanking.org.uk/v1.3/swagger.yaml
: (Patchable) "Status Code" is not a valid headerWider Azure problem - probably missing / mis-referenced files in source repo
azure.com/apimanagement-apimissues/2018-01-01/swagger.yaml
: Could not resolve reference ./apimapis.json#/definitions/IssueContractazure.com/apimanagement-apimissues/2018-06-01-preview/swagger.yaml
: Could not resolve reference ./apimapis.json#/definitions/IssueContractazure.com/azsadmin-RegionHealth/2016-05-01/swagger.yaml
: Could not resolve reference #/definitions/Alertazure.com/apimanagement-apimgroups/2016-10-10/swagger.yaml
: Could not resolve reference ./apimusers.json#/definitions/UserContractazure.com/apimanagement-apimusers/2016-10-10/swagger.yaml
: Could not resolve reference ./apimgroups.json#/definitions/GroupContractazure.com/apimanagement-apimusers/2017-03-01/swagger.yaml
: Could not resolve reference ./apimgroups.json#/definitions/GroupContractazure.com/apimanagement-apimdiagnostics/2018-01-01/swagger.yaml
: Could not resolve reference ./apimloggers.json#/definitions/LoggerContractazure.com/apimanagement-apimdiagnostics/2017-03-01/swagger.yaml
: Could not resolve reference ./apimloggers.json#/definitions/LoggerContractazure.com/apimanagement-apimapis/2016-10-10/swagger.yaml
: Could not resolve reference ./apimproducts.json#/definitions/ProductContractazure.com/apimanagement-apimgroups/2018-06-01-preview/swagger.yaml
: Could not resolve reference ./apimusers.json#/definitions/UserContractazure.com/apimanagement-apimgroups/2017-03-01/swagger.yaml
: Could not resolve reference ./apimusers.json#/definitions/UserContractazure.com/apimanagement-apimgroups/2018-01-01/swagger.yaml
: Could not resolve reference ./apimusers.json#/definitions/UserContractazure.com/apimanagement-apimproducts/2016-10-10/swagger.yaml
: Could not resolve reference ./apimapis.json#/definitions/ApiContractazure.com/apimanagement-apimusers/2018-06-01-preview/swagger.yaml
: Could not resolve reference ./apimgroups.json#/definitions/GroupContractazure.com/apimanagement-apimusers/2018-01-01/swagger.yaml
: Could not resolve reference ./apimgroups.json#/definitions/GroupContractazure.com/apimanagement-apimapis/2017-03-01/swagger.yaml
: Could not resolve reference ./apimproducts.json#/definitions/ProductContractazure.com/apimanagement-apimproducts/2017-03-01/swagger.yaml
: Could not resolve reference ./apimapis.json#/definitions/ApiContractazure.com/apimanagement-apimtags/2018-01-01/swagger.yaml
: Could not resolve reference ./apimtagresources.json#/definitions/TagResourceContractazure.com/apimanagement-apimtags/2018-06-01-preview/swagger.yaml
: Could not resolve reference ./apimtagresources.json#/definitions/TagResourceContractazure.com/apimanagement-apimtags/2017-03-01/swagger.yaml
: Could not resolve reference ./apimtagresources.json#/definitions/TagResourceContractazure.com/apimanagement-apimproducts/2018-01-01/swagger.yaml
: Could not resolve reference ./apimapis.json#/definitions/ApiContractazure.com/apimanagement-apimproducts/2018-06-01-preview/swagger.yaml
: Could not resolve reference ./apimapis.json#/definitions/ApiContractazure.com/apimanagement-apimapis/2018-01-01/swagger.yaml
: Could not resolve reference ./apimdiagnostics.json#/definitions/DiagnosticContractazure.com/apimanagement-apimapis/2018-06-01-preview/swagger.yaml
: Could not resolve reference ./apimdiagnostics.json#/definitions/DiagnosticContractThe text was updated successfully, but these errors were encountered: