Definition of Problem Details error types

[farshidtz]

The directory uses RFC7807 Problem Details for error responses.

Example Problem Details taken from RFC7807:

{
    "type": "https://example.com/probs/out-of-credit",
    "title": "You do not have enough credit.",
    "detail": "Your current balance is 30, but that costs 50.",
    "instance": "/account/12345/msgs/abc",
    ...
}

For now, the discovery spec omits type which defaults to "about:blank" and in this case title should be set to HTTP status text. Example validation error from the wot-discovery/#validation:

{
    "title": "Bad Request",
    "status": 400,
    "detail": "The input did not pass the JSON Schema validation",
    "instance": "/errors/30585584-cce2-4d04-8079-67b33ffdafbc",
    "validationErrors": [
        {
            "field": "(root)",
            "description": "security is required"
        },
        {
            "field": "properties.status.forms.0.href",
            "description": "Invalid type. Expected: string, given: integer"
        }
    ]
}

The Problem Details error type field is a URI reference. From RFC7807:

A URI reference that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type

We could use type to map the occurred error to a WoT-specific error class. Other WoT TFs have also raised the lack of WoT-specific error types:

• Error conditions for form requests wot-thing-description#303
• Error Handling wot-scripting-api#200.

I think the discovery spec may be the right place to define error types. Example types could be:

• https://www.w3.org/TR/wot-discovery#ValidationError
• https://www.w3.org/TR/wot-discovery#SerializationError
• https://www.w3.org/TR/wot-discovery#QueryError (e.g. jsonpath syntax error, missing/invalid query argument)
• https://www.w3.org/TR/wot-discovery#NotFoundError
• https://www.w3.org/TR/wot-discovery#NotAuthenticatedError
• https://www.w3.org/TR/wot-discovery#NotAuthorizedError

We could have a Errors section in the spec with subsection for each of the above to provide further description and examples. With the equivalent section ids, the above URLs will anchor at the right subsection.

[mmccool]

• Should be aligned with error classes used by Scripting API (Error Handling wot-scripting-api#200)
• Should use data schemas for error responses in Directory TM/TD; this will be a lot easier after this PR is merged: Update AdditionalExpectedResponses with named data schemas wot-thing-description#1130
• THIS issue is about defining protocol-independent error types; if we use "problem details", then URLs above can be in "type" field
• feel we still need to have error codes for HTTP and any other protocols we support (CoAP, etc).
• probably want to allow directory to omit the problem details in some cases, e.g. for security, esp for authentication errors. Fingerprinting risk... for now, let's put it in, and then have security review, and we can add security considerations for when we might want to omit detailed responses
• Scripting API needs to review and may want to refer to our definitions (so we don't have redundant/contradictory definitions in more than one place) - if we do this PR, need to create an issue in Scripting (and maybe a PR) to update and align

[mmccool]

@farshidtz will make a PR

[mmccool]

Why is this labelled a stretch goal? Should we not aim for 1.0 with this? Adding "Discuss" label, will put it in that category for the F2F.