spec: Cannot easily define server errors generic to all methods

@shanejonas and I were talking about this today, and we think a solution that might be an easier and cleaner option, that might be better to support the ecosystem by just extending errors to support json pointers. @shanejonas has some more thoughts he’ll drop here later

@BelfordZ Awesome, definitely! I’ll dig into it and verify with our use case next week when I am back, and then get back to you if that sounds OK?

Happy holidays!

My thought here is that perhaps we don’t need a top level default errors field. If we make errors composable, where we can create error groupings. Then for each method you’d be able

"method": ...,
"errors": [
          {
            "$ref": "#/errors/DefaultErrorGroup"
          },
          {
            "$ref": "#/components/errors/customMethodError"
          }
        ],

This would then allow us to be specific vs. having a hierarchical precedence for errors. I think with configuration and specification having scenarios where parts of the configuration are overridden adds a lot of cognitive load. I.e. at first glance you it becomes hard to figure out what’s happening.

I’m curious if this scenario would work for you. I think it would in your case it would be 20 methods that are then updated with a single default ErrorGroup that you would be able to then append custom method specific errors to when needed. Updating would then involve updating the errorGroup. This would also allow you to opt out of certain methods implementing the error group.

What do you think?

@BelfordZ Sorry about the slow response, been busy with the adjusted work situation with covid-19 and all that… I’m sure you are too. I don’t exactly follow what you mean with ‘a script that preprocesses your document’. Do you mean for testing purposes? We generate our spec in runtime so it’s almost like that today, I just haven’t had time to follow up until now. Using oneOf works great from what I can tell, granted that the schema allows it (today, an error cannot be defined as a list of oneOf I believe).

Keep safe!

I’m not going to have time to brainstorm on this one, sorry.

Thank you for re-opening the issue and the quick proposal! I think this is a good approach and actually exactly how I tried to solve it before noticing the spec wouldn’t allow it 😃

👍

Hi, thanks for commenting with your issue, I think the proposal would be something close to the language around servers and servers.method, except it would be joining instead of overriding the errors that are on the method.

Another short term remedy is to use $refs to at least provide minimal code re-use:

        "errors": [
          {
            "$ref": "#/components/errors/bar"
          },
          {
            "$ref": "#/components/errors/foo"
          }
        ],

Some addition thoughts on this:

Error Groups:

If there was a way to combine groups of errors, we wouldn’t need to have a root errors, we could just combine them. @zcstarr can maybe elaborate on this