attempting to register produces strange validation error messages about regexes

[cmungall]

I'm trying to register https://api.monarchinitiative.org/api/swagger.json

I get this, which is fairly opaque:

OAS3] '': 'basePath', 'consumes', 'definitions', 'produces', 'responses', 'swagger' do not match any of the regexes: '^x-'

Because I'm somewhat familiar with OpenAPI I know this is something to do with x- fields, but I'm still at a loss as to how to change my flask code to fix this (and I don't want to have to keep a separate description in sync). And I'm relatively experienced, others coming to this will be more puzzled.

Ideally this would link to a FAQ, but I think overall it would be better if SmartAPI were more tolerant. What does it matter if there are some additional fields it doesn't know about? Why should this block registration?

I know we have a current entry for the monarch biolink instance which comes from here https://github.com/NCATS-Tangerine/translator-api-registry/blob/master/biolink/openapi.yml

but this looks like it has been heavily tweaked from the source, and in the intervening time we have added new routes

[micheldumontier]

Hi Chris.
First, you seem to be generating a openApi v2 document, rather than a openApi v3 document. The current implementation of smartAPI registry is for v3 documents.
Second, there are syntax errors in your v2 document, which does not validate against the swagger 2.0 schema. you can check for more detailed errors using validation toolsets, or just trying to load it into the swagger 2.0 editor - https://editor.swagger.io/
m.

[newgene]

@cmungall, I confirm what @micheldumontier said, this error msg is just indicating that "swagger" is not a recognized field in OAS3. It needs to be converted from OpenAPI v2 to v3 first.

[cmungall]

Thanks. My main point here is that is that it is more difficult than it should be for people to register their API. Do you have any logs showing how many people come to the site to try to register and are not successful? I am committed to using SmartAPI and I find it difficult. I think if you want to try and bring in people who don't have any requirement to register it needs to be easier.

Specifically

1. Provide more informative error messages
2. Provide automatic conversion and help. Some people may be using OA2 because it will take effort to migrate their existing framework
3. Be more liberal in what is accepted

The last point is important. I was able to fix the majority of the errors the swagger editor pointed out. However, some are quite obscure and may be the result of issues in the underlying framework used. None of them are of any consequence from the point of view of registration with SmartAPI or from the ability to use a wide variety of OpenAPI/Swagger conformant tooling such as code generators and the main swagger UI. Why not simply accept any OpenAPI v2 or v3 document that is syntactically well formed and has a meaningful subset of metadata fields filled in. You can provide a dashboard in the registry that shows which APIs are failing which conformance tests, but you will still have them registered.

[micheldumontier]

@cmungall Thanks for the feedback.

1. more informative error messages. @newgene can comment on how the validation is done and whether this is possible with existing libraries. the alternative, i think, is that we point users to the OAS3 editor with their document loaded so they can see the messages and work through them.
2. automatic conversion. maybe we can point people to the tools to do the conversion... but some parts are really quite different, especially for the smartAPI @ OAS3. in any case, the system acts on document URLs... so users would have to store that document at that location if they want it periodically reindexed.
3. be more liberal. I'm not convinced that the smartAPI repository should store non-conforming documents, primarily because we pass these documents to other tools and services, including the UI for the repository. If the documents are not syntactically correct, then we won't be able to retrieve the expected metadata to enable search and visualization of results. This would be all bad and any repository that has a submission format would expect valid submissions. It's really up to the submitters to ensure they have valid documents!

• we don't accept a v2 document because it affects how we index the documents and provide search services. so early on, I don't think we need to support legacy documents and we should just encourage developers to move to v3.

• APIs failing. this is a good suggestion. @newgene shall we create an issue for this?

[newgene]

@cmungall @micheldumontier my comments below:

• Validation error msg.
  The validation at the API submission form is considered as a last-step "gate keeper". When you are at the development step of your API metadata, you don't want to reply on that for fixing all the metadata errors. We expect our users to work on their metadata using the API metadata Editor first, solve all the issues there and then submit. The validation is mostly to prevent people make accidental edits and break the syntax.

  The error msg was produced from the json-schema validation library, in general, we don't want to mess with it to customize the error msg. From the API metadata Editor, you are most likely to get the similar error msg. It's true, something the error msg is misleading, but people typically get used to it and know what it actually means after a few tries.

  Current SmartAPI web app does lack enough documentation text. We are working on that. For example, we can add some text to tell users to try editor to fix the validation errors.

• Invalid API metadata entry.

  Yes, this is something in my mind as well. We will first do something like daily-refreshing (or a commit hook is even better) of each registered API metadata, at each refresh, the validation check will be run and then we can label validate or failed. No need to put this on an issue, it's something has been planned.