4 ms·

OpenAPI and JSON Schema Divergence: Part 1

28 points by icc97 8y ago

benatkin 8y ago
It's certainly possible to talk about API specifications without mentioning either of those.
- deleted 8y ago
  [deleted]
segphault 8y ago
I really like the idea of declarative and machine-readable validation and API descriptions, but JSON schema is often pretty frustrating to work with in practice. Building a compliant implementation is quite difficult. The $ref resolution, as defined in the spec, is hideously complicated, to the point where many implementations just don't even bother supporting external $refs. It feels like it really should be a totally separate concern from validation, especially since how you store and compose schemas may end up being somewhat specific to a given use case.
- dfee 8y ago
  I compose my json-schemas in yaml, and therefore use yaml-anchors to stitch together repetitive code. The errors I've run into are more alongside implementation details like: `number` being interpreted as a float (not a decimal) which makes it's related property `multipleOf` erroneous.
kizer 8y ago
I have an idea. Why don't we give up on a strictly declarative format/solution? What if, associated with each possible API call, was a pseudocode or generalcode representation of the code executed to validate the request? Is reading code snippets that difficult? For a short validation program, a machine could certainly infer if a type would be accepted (just run the validation). I know that a declarative format seems like the right choice, given validation in mainstream programming languages is expressed declaratively via the type system, but these standards, to me, often seem to only translate awkwardly an implicit validation program into a very verbose declaration.
- Boulth 8y ago
  That's a really interesting idea! The language for API validation could be a total programming language [0], something similar to Dhall [1] for configuration. [0]: https://en.m.wikipedia.org/wiki/Total_functional_programming https://en.m.wikipedia.org/wiki/Total_functional_programming [1]: https://github.com/dhall-lang/dhall-lang https://github.com/dhall-lang/dhall-lang
  - kizer 8y ago
    Reading up on those now. Thanks for the feedback!

28 points by icc97 8y ago

benatkin 8y ago

It's certainly possible to talk about API specifications without mentioning either of those.

deleted 8y ago
[deleted]

segphault 8y ago

I really like the idea of declarative and machine-readable validation and API descriptions, but JSON schema is often pretty frustrating to work with in practice. Building a compliant implementation is quite difficult. The $ref resolution, as defined in the spec, is hideously complicated, to the point where many implementations just don't even bother supporting external $refs. It feels like it really should be a totally separate concern from validation, especially since how you store and compose schemas may end up being somewhat specific to a given use case.

dfee 8y ago
I compose my json-schemas in yaml, and therefore use yaml-anchors to stitch together repetitive code. The errors I've run into are more alongside implementation details like: `number` being interpreted as a float (not a decimal) which makes it's related property `multipleOf` erroneous.

kizer 8y ago

I have an idea. Why don't we give up on a strictly declarative format/solution? What if, associated with each possible API call, was a pseudocode or generalcode representation of the code executed to validate the request? Is reading code snippets that difficult? For a short validation program, a machine could certainly infer if a type would be accepted (just run the validation). I know that a declarative format seems like the right choice, given validation in mainstream programming languages is expressed declaratively via the type system, but these standards, to me, often seem to only translate awkwardly an implicit validation program into a very verbose declaration.

Boulth 8y ago
That's a really interesting idea! The language for API validation could be a total programming language [0], something similar to Dhall [1] for configuration. [0]: https://en.m.wikipedia.org/wiki/Total_functional_programming https://en.m.wikipedia.org/wiki/Total_functional_programming [1]: https://github.com/dhall-lang/dhall-lang https://github.com/dhall-lang/dhall-lang
- kizer 8y ago
  Reading up on those now. Thanks for the feedback!