Cannot easily define server errors generic to all methods

[BelfordZ]

At the moment, if you have server-defined errors that can be returned by any of the methods, you would have to $ref the error(s) in each method you have.

This amounts to a lot of repetition.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[peol]

Hi. I see this was queued to be discussed, has there been any decisions how this should be handled? We're facing this issue currently and it's not feasible for us to inline 20+ errors in 100+ methods unfortunately. If we can help with e.g. a proposal, would that be interesting to you?

[shanejonas]

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

[zcstarr]

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?

[peol]

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 :)

👍

[BelfordZ]

@peol thank you for bringing it back up.

We try not to solve problems no one is having, so this really helps.

Im happy to make a PR adding this, and Im also happy to help you in putting one together if thats something you are interesting in doing. It should be fairly straight forward, you can find instructions if needed in the CONTRIBUTING.md

[BelfordZ]

To summarize the proposed solution:

1. we would be adding a new field to components called ErrorGroups
2. method.errors accepts an array of errors, which can be intermixed with ErrorGroups, where the resulting error set, once normalized, yields the union of all errors provided.

[peol]

Thank you @BelfordZ — I got to be honest, I'm not super savvy at schemas so if it's not too much trouble for you I'd appreciate your help here. Let me know if you do not have the bandwidth right now and I'll take a swing at it, of course!