Consider revising the structure of Exception responses

[ghobona]

There was a suggestion to consider revising the structure of Exception responses, so that they could be as informative as those from OWS Common.

Currently the structure is as shown at https://github.com/opengeospatial/oapi_common/blob/master/core/openapi/schemas/exception.yaml

One suggestion is to have an array of descriptions.

The 'code' property is not well defined and it appears to duplicate the role of the HTTP status code.

Suggestion that there would be a recommendation to use the JSON Schema for exception responses, and the Guide would provide more information.

[pomakis]

I think this is a "Common-Part 1" issue (as apposed to "Common-Part 2"). It's certainly not specific to collections.

[pomakis]

I propose the following schema for the body of OGC API responses with an HTTP 4xx or 5xx status code:

{
  "type": "object",
  "required": [ "type", "reason" ],
  "properties": {
    "type": {
      "enum": [ "OgcApiExceptionReport" ]
    },
    "reason" {
      "type": "array",
      "items": {
        "type": "object",
        "required": [ "description" ],
        "properties": { "type": "string" }
      }
      "minItems": 1
    }
  }
}

The first (and required) element of the "reason" array should be the primary or most general reason for the exception. If the client wants a single, concise string to report to the user, this is the one to report. Further elements in the array can be used to provide drill-down reasons.

Examples:

{
  "type": "OgcApiExceptionReport",
  "reason": [
    { "description": "Illegal value specified for parameter \"bbox\"" },
    { "description": "Cannot parse string \"df\" as a floating-point value" }
  ]
}

{
  "type": "OgcApiExceptionReport",
  "reason": [
    { "description": "Illegal value specified for parameter \"geodata\"" },
    { "description": "No such collection \"coastlines\"" }
  ]
}

The reason I propose an array of objects with a single "description" string is to allow for future or vendor-specific fields such as (e.g.):

{
  "type": "OgcApiExceptionReport",
  "reason": [
    {
      "description": "Illegal value specified for parameter \"bbox\"",
      "traceInfo": {
        "filename": "ogcApi_common.c",
        "function": "OgcApi_GetRequestBbox()",
        "line": 465
      }
    },
    {
      "description": "Cannot parse string \"df\" as a floating-point value",
      "traceInfo": {
        "filename": "cw_str.c",
        "function": "CwStr_ParseDouble()",
        "line": 2561
      }
    }
  ]
}

This exception-report format should be a recommendation rather than a requirement since for some servers and/or error cases it may not be possible or feasible to generate this form of output. A client application can easily sniff out whether or not it has received such an exception report by checking that the Content Type of the response is "application/json" and that there's a top-level "type": "OgcApiExceptionReport" property.

This, of course, describes JSON responses only. Presumably format negotiation should be honoured where feasible when generating the body of an HTTP 4xx or 5xx response. For example, if the client requested HTML (through the Accept header, an "f" parameter or whatever), then an HTML exception report should be returned if feasible.

[jerstlouis]

@pomakis

A few comments.

Shouldn't the trace info support multiple stack frames? A single frame might often be quite useless without the higher up context.

Should reason be plural since it's an array?
How about details instead of reason? It's hard for a server to know the true reason why an error occurs, but it can provide some additional details about it :)

I still think it's a good thing to specify the HTTP code in there... This way if you save only the JSON error log and save it to inspect later, or file it in a bug report, you're sure the HTTP status code is preserved.

[pomakis]

I made "reason" singular rather than plural because I see it as a single reason with possibly multiple levels of detail. But I'm equally fine with "details".

I'm not sure what you mean by "multiple stack frames". An error typically happens for a single specific reason.

I'm okay with having a (redundant) "httpStatus" property. I personally see it as pointless, but I won't object if others see value in it.

[ghobona]

Thanks @pomakis . Label changed to Common-Part 1.

[jerstlouis]

@pomakis I much prefer details.

Re: trace info I mean being able to list a call stack with multiple levels of sourceFile:lineNo so you know what function/line invoked CwStr_ParseDouble().

I see value in httpStatus in the JSON.

[pomakis]

Re: trace info I mean being able to list a call stack with multiple levels of sourceFile:lineNo so you know what function/line invoked CwStr_ParseDouble().

Ah, that was only an example of a future or vendor-specific extension. I'm not proposing adding anything like a "traceInfo" property at this point.

[pomakis]

So now (with a couple of other schema corrections) we have:

{
  "type": "object",
  "required": [ "type", "details" ],
  "properties": {
    "type": {
      "enum": [ "OgcApiExceptionReport" ]
    },
    "httpStatus": {
      "type": "integer"
    },
    "details": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [ "description" ],
        "properties": {
          "description": {
            "type": "string"
          }
        }
      },
      "minItems": 1
    }
  }
}

[pomakis]

I have upgraded CubeWerx's test implementation at

https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa

to report exceptions using this schema.

[cmheazel]

This issue was resolved in issue #73

[joanma747]

The resolution in #73 applies: "API-Common Part 1 - the exception schema has been updated to conform with RFC 7807. This schema will be updated to conform with the revised version of RFC 7807 once it is finalized." Will be also applied to part 2 collections. In telco 2021-02-22

[cmheazel]

API-Common Part 2 is now in-line with Part 1.

[aaime]

A note that the current definition of exception:
https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/exception.yaml
is inconsistent with the Features API one:
http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/exception.yaml

So I guess that implementations of OGC API Features should either:

• Not declare conformance with OGC API Common
• Report all fields, with eventually duplicate information (e.g., same value for code and type, and some of the same information in description and title/detail

[cmheazel]

See issue #73
The resolution was to align with IETF RFC 7807. Since RFC 7807 is being revised, we accept that we will have to update both Common and Features once the RFC 7807 (or its replacement) is finalized.