Should JSON schema be used to describe Problem Details Object?

[sdatspun2]

Should JSON schema (https://json-schema.org/specification.html) be used to describe Problem Details Object?

[simonplend]

I think it would be very beneficial for an official JSON schema to be created for Problem Details objects. A couple of use cases immediately come to mind:

• As documentation of the required shape of a Problem Details object
• As something which APIs could validate their responses against before they are sent back to the client e.g. https://www.fastify.io/docs/latest/Validation-and-Serialization/#serialization

[sazzer]

The thing that makes this awkward is twofold:

• All of the defined fields are optional
• Arbitrary other fields can be added as needed

So the best that a schema can achieve is to define the types of the 5 defined fields - depending on other issues being discussed - but the client still can't rely on the shape because of the above.

On Mon, 1 Feb 2021, 19:24 Simon Plenderleith, notifications@github.com wrote:

I think it would be very beneficial for an official JSON schema to be created for Problem Details objects. A couple of use cases immediately come to mind:

• As documentation of the required shape of a Problem Details object
• As something which APIs could validate their responses against before they are sent back to the client e.g. https://www.fastify.io/docs/latest/Validation-and-Serialization/#serialization

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/ietf-wg-httpapi/rfc7807bis/issues/8#issuecomment-771097841, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAQEGGVPNIP3CU2RG5XX6DS435YPANCNFSM4W3QNADA .

[simonplend]

• All of the defined fields are optional

This is true, but what awkwardness do you feel this introduces?

• Arbitrary other fields can be added as needed

JSON Schema allows you to effectively extend schemas (through use of the allOf and $ref keywords). This would allow users to define a schema which extends a base Problem Details JSON schema. User defined schemas would then be free to define any "extension" fields e.g.

{
  "allOf": [{ "$ref": "https://example.com/schemas/problem-details-object.json" }],
  "properties": {
    "extension_field": { "type": "string" }
  }
}

[sazzer]

The "awkwardness" - and it was a bad choice of words :( - is that a generic JSON Schema for Problem Details will validate almost any object, whether it's actually a Problem Details or not. The only thing it would catch is if there are fields present matching the 5 standard names but with incompatible types. E.g. a response with a status field that was a string.

The ability to define your own schema for specific problem responses would be a huge win, but then there needs to be some way for the client to know which schema to use. Presumably that would be the Link header with a rel of described-by, though having clients able to determine the correct schema based on the type field would also be fantastically useful - and would then mean you can define that certain values for type automatically have certain other required structure in the payload.

[simonplend]

The "awkwardness" - and it was a bad choice of words :( - is that a generic JSON Schema for Problem Details will validate almost any object, whether it's actually a Problem Details or not. The only thing it would catch is if there are fields present matching the 5 standard names but with incompatible types. E.g. a response with a status field that was a string.

Thanks for clarifying - I understand what you mean now. Specifying "additionalProperties": false on the base schema wouldn't be possible as it would prevent any extension fields being added by a user defined schema which extends it. It would be down to the user defined schema to specify "additionalProperties": false - certainly not ideal.

The ability to define your own schema for specific problem responses would be a huge win, but then there needs to be some way for the client to know which schema to use. Presumably that would be the Link header with a rel of described-by, though having clients able to determine the correct schema based on the type field would also be fantastically useful - and would then mean you can define that certain values for type automatically have certain other required structure in the payload.

This is a really interesting use case. How are you imagining the client might use the schema for a specific problem response once it has retrieved it?

[sazzer]

This is a really interesting use case. How are you imagining the client might use the schema for a specific problem response once it has retrieved it?

I'd not thought that far ahead :)

However - to make up some potential uses :)

At the very least you could use it to ensure that the response payload was valid. If the schema says that a particular field is mandatory, you can expect it to always be there. Things like that. Potentially that can be used by languages like TypeScript to give better access to the payload values in a typesafe manner.

Potentially though, it could also make use of things like default to reduce the payload size. The schema is likely incredibly cacheable, and any values that are unlikely to change can then be omitted from the actual Problem payload, the schema gives them default values, and the client still sees all of the correct values with less network traffic. Very useful if clients are on low bandwidth connections.

[mnot]

WRT using schemas for (effectively) compression -- that feels like premature optimisation, and implies a requirement to process the schema, which is going to orphan clients that don't want that burden.

That aside, I think adding a schema in an appendix makes sense. We should defer this until we discuss all the other changes, though.

[awwright]

I don't see any problem at all with specifying a JSON Schema. It would be a simple, but useful, one. And being able to specify a profile for a Problem document also seems like a potentially useful feature. For example, it would allow servers to describe what each of the custom properties in the problem document means.

With respect to using defaults to omit keywords: The semantics of "properties" doesn't actually let you use "default" to fill in missing values. This is a known issue.

[serialseb]

How would you handle the non-normative nature of the schema? Or are we talking about adding in appendices normative schemas? If yes, shoudl this apply to hydra/ld, rdfs over xml, xsd, json schema, where do we find that repository and what is the process of updating them if they are normative?

[asbjornu]

A JSON Schema, just like A JSON-LD Conext (see #10), must be non-normative, imho. They would be provided as a convenience to implementers to help adoption of the format and to avoid fragmentation.

[sdatspun2]

Pl review https://github.com/ietf-wg-httpapi/rfc7807bis/pull/18.