Adding a detailed json-schema #440
Conversation
|
Thanks for this @eneuhauser! I'm going to hold off on merging until we have marked 1.0. |
|
With 1.0 released, will this be considered for merging? This would help when documenting APIs with RAML. |
|
Yes! Can you squash this to a single commit please? |
| "type": "string", | ||
| "format": "uri" | ||
| }, | ||
| "linkage": { |
|
I've been using this schema and updated my version of it now to pass with 1.0 (including your comments @ethanresnick). Since you did most of the work feel free to update this PR with my gist: https://gist.github.com/slaskis/f4f32beeea0080320e00 |
|
@tkellen I've updated the schema to match the new 1.0 format and squashed into a single commit. I validated the schema complies with the example on the homepage using JSON Schema Lint. @slaskis, thanks for your help. I used your changes to start out, but I did make some modifications based on the current format of the spec. Please let me know if you see any issues. |
|
@eneuhauser happy to help! I was a bit lazy with the descriptions but I see you took care of that 👍 |
| "$ref": "#/definitions/resource" | ||
| }, | ||
| "uniqueItems": true | ||
| } |
There was a problem hiding this comment.
Perhaps this could be moved into something like "#/definitions/collection"? Not that it's re-used right now but just for clarity. If that's even the correct term, but "an array of resource objects" doesn't really fit in a nice and tidy string.
There was a problem hiding this comment.
I don't know about this one. You wouldn't create a new object to represent an array of resources, so I don't think it needs its own definition.
There was a problem hiding this comment.
Very good points, ignore my ramblings please :)
| [http://jsonapi.org/schema](http://jsonapi.org/schema). Please note that this | ||
| schema is not a perfect document. Just because a JSON document may validate | ||
| against this schema, that does not necessarily mean it is a valid JSON API | ||
| document. The schema is provided for a base level sanity check. |
There was a problem hiding this comment.
Following this PR, and the preceding issue #271, I agree that a schema is helpful. If it doesn't validate all of the semantics of JSON API, then I would say it's like most schemas in that respect. It can yield some "false positives," where a given JSON input passes schema validation, but breaks some JSON API rules.
Still, I assume that whatever this schema does validate is in fact a requirement of the JSON API spec. So it should not yield any "false negatives." If a given input fails validation against this schema, then it's definitely not valid JSON API.
That's an important guarantee, and one worth stating in the FAQ, I think. Rather than saying it's "not a perfect document," say something like "Please note that this schema only enforces a subset of the JSON API specification."
There was a problem hiding this comment.
This wording was taken from the previous JSON Schema. The previous schema was a lot more simplistic, so your suggestions are more appropriate for this version of the schema.
I reused the wording because I didn't want to get into the politics of how it should read, but I can take a crack at updating the copy match what this schema does and doesn't do.
There was a problem hiding this comment.
Would you mind doing that @eneuhauser and pinging back when ready? I'd love to get this merged but it would be nice for it to be a bit more clear.
|
@tkellen, I've updated the FAQ with the spirit of the schema definition. I also cleaned up some whitespace issues with the schema if you notice differences there. Please review and let me know if it is sufficient. Thanks! |
|
thanks @eneuhauser! |
|
I haven't reviewed the schema definition in detail, but it looks like a great start. I suggest we merge and allow for refinement (if needed). Thanks so much for your work here @eneuhauser! |
|
Just want to confirm, unless I'm not seeing it, that this schema was manually generated and is not as authoritative as the |
Correct. The current schema is non-normative and has a few known issues (see #867) |
|
ref multiple schemas PR for discussion #1127 |
I saw that you just removed the json-schema, but I believe this schema is a good representation of JSON API and concisely explains the format.