Json schema required properties vs sparse fieldsets exclusion

1

Hi,
what is the expected behaviour if a field is a required properties in the JSON schema for validation, but EXCLUDED in the client request’s sparse fieldset? e.g.,

say an Articles resource has this JSON Schema definition, wherein “title” is the required properties of the “attributes”

{
  "type": "object",
  "required": ["id", "type", "attributes"],
  "properties": {
    "id": {...},
    "type": {...},
    "attributes": {
      "type": "object",
      "required": ["title"],
      "properties": {
        "title": {...},
        "body": {...},
        "created": {..}
      }
    }
  }
}

but in a client request, the “title” field is EXCLUDED, like

GET /articles?include=author&fields[articles]=body

and according to the spec,

If a client requests a restricted set of fields for a given resource type, 
an endpoint MUST NOT include additional fields in resource objects of that type in its response.

Question:
What should be the expected behaviour in this scenario? i.e.,

  • should that be classified as Bad Request? otherwise, if return data based on the spec, the server would violate the API contract and fail the schema validation?
2

The schema required for a request to create a resource can (and often should be) different from the schema required to describe a retrieved representation.

-Fred

3

The schema required for a request to create a resource can (and often should be) different from the schema required to describe a retrieved representation.

hmm, sorry, I might not understand it correctly, but not sure how it’s relevant to the resource’s create schema. i.e., unless it’s implying that the schema for the GET response should ONLY have optional properties for the JSON:API attributes/fields,

  • would the original question still apply? i.e., there’s always a possibility that a resource’s JSON Schema required properties is excluded in a client’s JSON:API sparse fieldsets? (regardless if the GET response schema is the same as the POST schema or not?)
4

What’s required for creation affects the POST request used to create; the response needs to allow anything in attributes or relationships to be omitted, due to the include query parameter.

Ultimately, it can make sense to use JSON schema to describe the transfer format, but the schema doesn’t really apply to the underlying resource (or, a separate schema might make sense for that, if your data model really is a pile of JSON:API stuff).

I hope this makes more sense.

-Fred

5

the response needs to allow anything in attributes or relationships to be omitted, due to the include query parameter.

thanks, that’s kinda what I tried to confirm.

6

If you wish to refuse to return the object without a particular property, but also wish to support the fields sub-setting, then I would return an error code if the mandatory fields are not listed as fields.

I would not suggest 400 Bad Request, because the query was well formed (i.e. assuming it meets your api schema). I appreciate not everyone will agree with me :). I prefer to give a response implying “your request was syntactically correct but I’m not willing to execute it”

IMO 422 Unprocessable Entity logically aligns best. Unless you wish to steer clear of WebDAV inspired codes for some reason.

11.2. 422 Unprocessable Entity The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415(Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.

In my system we tend also to use 403 forbidden, which I think also works OK in your case.

Or of course, you could allow the fields to be all optional and allow all field restrictions.

1 Like
7

Thanks PeaDubYa,

and I agree 422 makes more sense than 400.

you could allow the fields to be all optional and allow all field restrictions.

yeah, I think my issue with a JSON Schema object with all optional properties is that, by default, while processing the response, clients need to do a null check on every fields, vs with required properties, one knows those fields MUST not be null.

So it kinda felt like needing to change the semantics of an instance’s JSON Schema just because of adopting or complying with JSON:API…