Creating new resources and validating with JSON Schema

[mvdstam]

The official JSON API Schema (as described at http://jsonapi.org/schema) explicitly expects the ID field to be sent by clients when creating new resources. This conflicts with the following example (pulled from the official documentation):

POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "photos",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "relationships": {
      "photographer": {
        "data": { "type": "people", "id": "9" }
      }
    }
  }
}

When I validate the above to the official JSON Schema document, validation fails. Perhaps a seperate JSON Schema document can be provided solely for creating new resources, where the ID field is optional?

[ethanresnick]

See #851, which is another reason not to use the published schema to validate incoming requests. Basically, that schema is only for validating output/response documents, and we're already thinking about whether to create a separate one for incoming requests (or just to keep a single one, but make it more lenient).

[sebilasse]

Citing the official documentation

Exception: The id member is not required when the resource object originates at the client and represents a new resource to be created on the server.

[ethanresnick]

@dgeb @tkellen @steveklabnik Do you guys have an opinion here on whether it's worth it to maintain multiple, stricter schemas or just go with one looser one? I was leaning toward the looser schema approach and started mocking it up, as you can see from the links. But, on reflection, ditching the id requirement for all resource objects seems like a big loss, so now I'm not sure.

[mvdstam]

If I may offer my 2 cents (as someone who has used JSON-API in a production environment and had the chance to look at it quite thoroughly). One of the most nice aspects about JSON-API is that once a request goes through a JSON-Schema, you can trust it's okay because it's so strict, and you know that certain data is at your disposal.
I'd go for multiple stricter schemas instead of going with 1 looser schema, because going down that road means potentially making the schema even more looser when more use-cases show up thus making the standard less, well, standard. The id field thing is a major dealbreaker IMHO and should be required for all requests aside from updating existing resources.

[sebilasse]

@ethanresnick : same like @mvdstam
I would also go for 2 schemas. Most people will use it as "Request Schema" with it's target "Response Schema": This is an official part of JSON schema ("hyperschema") - this article (how they do it at heroku) might be helpful: https://brandur.org/elegant-apis
and btw:
I already designed a typescript interface for those two - but than I realized that typson (which I wanted to use for JSON schema conversion as a starter) only supports features <TS 1.3.
I am starting to rewrite typson with the official TS compiler API which will always be up to date so that it can make oneOf or allOf for union or constraint types.
Afterwards I'll publish the resulting schemas here ...

[tkellen]

@ethanresnick I see no harm in maintaining multiple schemas. In fact, I think it's a pretty great idea (as long as their separate usages are clearly defined).

[eneuhauser]

Here is an updated schema to allow for creating new resources. I'd like to get some feedback before creating a pull request.

In this version, it allows for a new post type, which allows for only a "a single resource object as primary data". resource now extends a newResource definition to require the id. The one downside to this approach is that servers returning a single resource without an id could yield false positives in schema validation, but I feel that is a small compromise for a simpler implementation.

[ethanresnick]

Thanks @eneuhauser!

I may be misunderstanding something, but I think that schema will accept a single id-less resource in any case, right? That is, it won't yield a false positive only when the server returns a single resource without an id but also, say, if a client tries to PATCH a resource without providing the id?

If that's right, your version is still very interesting because it's stricter than the version I proposed, so maybe it's a good compromise. But, if we do decide that we want to make all the schemas as strict as possible, I don't think we can get around actually providing distinct files for the different cases.

[eneuhauser]

@ethanresnick, you are correct, a PATCH without an ID would also yield a false positive. As an aside, the spec specifically says this is invalid, but in my implementation it's moot since the URI has the ID. The request schema and response schema solution would still have this problem.

I'm using RAML to define my API and extend the JSON API schema with my own schema to explicitly enumerate the attributes. With my proposed change, you could reference the #/definitions/post with POST calls and #/definitions/success with PATCH calls just as easily as having two different schema files.

[ethanresnick]

The request schema and response schema solution would still have this problem.

Right. So I was imagining that one schema would be for the "create resource document" case and another would be for "all other request/response documents". Then, for each of these two cases, we'd need two files, one with with additionalProperties: true and one with it false, per #851. So we already have 4 schema files under the multiple files approach, actually. Then, if we want to subdivide the "all other request/response documents" case further—say, to separate out the response docs—we'd end up 2x as many schema files for each subsequent division.

That's why I was a bit hesitant about that approach. At the same time, the changes are small and pretty mechanical, and having these schemas helps implementors, so maybe it's the way to go. If @tkellen's still onboard given the above, then I am too.

With my proposed change, you could reference the #/definitions/post with POST calls and #/definitions/success with PATCH calls just as easily as having two different schema files.

Can you explain to me how this works? Is it something that a user can do only if they're using RAML, or does a generic JSON Schema parser allow the user to call out some definition in the schema and check just against that?