Use JSON schema in definitions

[leplatrem]

After discussion with @AntoineCezar and debates in issue #9 it seems relevant to use JSON schema for model definitions, instead of our own formalism.

A basic investigation needs to address the following questions:

• Should it replace or supplement the current definition formalism ?
• Does it support current and planned field types ? #51 #33 #29
• Is it extensible and simple enough to add custom notions ? #11
• Could it address the need of defining and validating relationships between models ? #32
• Is it redundant with SPORE ?

More generally, should JSON schema validation come as a Cornice extension or as internal Daybed mechanics ?

[AntoineCezar]

Should it replace or supplement the current definition formalism ?

It could be plugable.

Does it support current and planned field types ? #51 #33 #29

http://json-schema.org/latest/json-schema-validation.html#anchor108 for #33 we'll define the schema https://github.com/fge/sample-json-schemas/tree/master/geojson

Is it extensible and simple enough to add custom notions ? #11 Could it address the need of defining and validating relationships between models ? #32

Play with this to get an idea: http://exavolt.github.io/onde/#?schema_url=schemas/jquery-package.json

[AntoineCezar]

Is it redundant with SPORE ?

SPORE Doesn't deal with schemas. Unless I'm missing something it's only about api discovery.

[almet]

Thanks for bringing this to the table.

Using Json Schema seems indeed something to consider, using our own format wouldn't bring any good. However, from what I see, JSONSchema still lacks some clear readability. By looking at the documentation, I wasn't able to tell simply if it's possible or not to use regular expressions or not.

About the concerns you have:

Should we replace or supersede what we have with JSONSchema?

I'm tempted to say we should use JSONSchema in parallel with the daybed formalism, but it means we need to write translation logic between the two, which I'm not sure would be reliable. If we validate JSONSchema as good enough to do what we are doing atm, maybe we should just switch there.

I've made a couple of queries to my search engine of choice and found that someone already did something related, so we may give it a go. (also, it means we lack the other direction, which is json schema to colander).

Does it handle what we have or plan?

I'm unsure about that, but it seems pretty complete. But JSon Schema doesn't seem to be very easy to extend:

Implementations MAY choose to define additional keywords to JSON Schema. Save for explicit agreement, schema authors SHALL NOT expect these additional keywords to be supported by peer implementations. Implementations SHOULD ignore keywords they do not support.

Also, the documentation say they support geo fields, but only lat/long from what I see, which might not be enough for us.

The specification document also states that it is about to expire "Expires: August 3, 2013", not sure what it means.

Redundancy with SPORE

It's not redundant with SPORE, and can be complimentary. The latter describes APIs in how we interact with them (HTTP Verbs, acceptable status code, resources URI), whereas JSON Schema does, well, schema validation.

I'm aware I'm not addressing all the questions you ask, but that's a start. I think we need to start playing with it to be sure of what we do. For now I'm not totally sold to the thing because I find it really complicated, or at least some beginner documentation is not made available.

Don't hesitate to share any good doc you found on it here.