I'll be one of the few positive voices here, I guess.<p>JSON Schema is pretty good. It's a relatively simple, extensible, pragmatic specification that supports validating the kinds of data that JSON can express.<p>XML was killed by complexity, same as lots of technologies that preceded it, such as CORBA and SOAP. Developers don't like complexity. W3C tried to build an enormously complicated ecosystem of tools on top of XML. The specifications for XML Schema, WSDL, XSLT, etc. were gigantic. XML Schema and WSDL are both so big they are split into multiple parts. XSLT 3.0 is maybe 500 pages when printed. Many of these originated in the wrong sort of place, designed by committee and from inside big enterprises like IBM, rather than being adopted from evolving practices.<p>With XML out of the way, we still need a way to represent structured data, and it turns out JSON is pretty good for that. JSON has problems, but its simplicity is what lead to it becoming so prevalent in the first place. Now, we <i>also</i> need a way to define the structure and format of that data, and JSON Schema is pretty good for that. I think JSON Schema could have been a bit simpler, but it's still nowhere near to making the same mistakes as XML Schema.
We've come full circle back to XML SOAP.<p>We should consider restricting the registration of .org domains to actual non-profit organizations, and restricting the use of words like "schema" and "standard" to things that have been fully certified as such by internationally accredited engineering bodies.<p>This doesn't add anything on-top of the tools we've had 40 years ago. We're stuck with this everywhere now, all thanks to pure marketing.
I generally prefer using JSON in my interactions, where possible.<p>That's because it is lightweight, and 99.9% of the data I'm transferring is scalar. JSON is basically "implied" for scalar types.<p>The good thing (if you want to call it "good") about XML, is Schema.<p>Schema is a "rock hard" contract. It is definite, empirical, unambiguous. When I am looking at an API, and it has a Schema, then I know that I can figure out exactly what shape the data will take/emit.<p>If possible, I still use JSON for the exchange. I just use the XML to figure out the specifics in the exchange.<p>I've been working in XML forever, it seems. I've done ONVIF stuff, which is SOAP/WSDL-based, and even XSLT.<p>I still like JSON.<p>Mostly because I don't have to deal with Schema.<p>Over the years, I've gotten fairly good at developing XML Schemas, but I have never gotten "used" to it, and still have to look everything up.<p>If I develop APIs, I will often do an XML variant, alongside the JSON, because that forces me to write a Schema. Doing this, helps me to "code review" my schema, and also gives me a very convenient automated test hook.<p>But, boy, I still <i>hate</i> XML Schema...
I'd like to offer a contrasting opinion to all of the other currently negative comments: I've used JSON schema in the past to validate outside input and it was a pleasant and straightforward experience.<p>There are unfortunately no standard type declarations that I'm aware of, which is a pain, but tools exist to translate schema.org schemas[1] (I have not used this myself).<p>[1]: <a href="https://github.com/charlestati/schema-org-json-schemas" rel="nofollow">https://github.com/charlestati/schema-org-json-schemas</a>
I use jsonschema to validate my projects' output, and also generate the documentation from it. The python jsonschema support makes this possible: our testsuite is in Python already.<p>But it's an awkward fit, and I despair of having anyone else in my team write schemas: the default of allowing additional unspecified fields must be continually overridden, otherwise your schema has no teeth, and things like "if this field is this value, these additional fields exist" must then always have an "else" indicating that no additional fields exist.<p>In summary, it's better than nothing, but it's not easy. I'm not sure that JSON is a great language to specify schemas in, sorry.
I haven't stumbled upon a better schema for JSON than the Typescript definition files. If only I could use them in non Typescript contexts.<p><a href="https://www.typescriptlang.org/docs/handbook/declaration-files/deep-dive.html" rel="nofollow">https://www.typescriptlang.org/docs/handbook/declaration-fil...</a>
I started using jsonschema at work and can't go back. We have an extremely large configuration file to configure our system and there are lots of 'optional' blocks that can be configured. Jsonschema really cleanly allows you to express that logic without having to write a line of code. It's been great.<p>Protip: if you are using jsonschema in python, it takes in a dict() not a file, so you can use yaml (or something else) as your configuration file and still validate it with jsonschema.
I might be exceptionally dense, but it's hard for me to see practical applications for something like this. In the end, if you implement this in your application, you will have a mechanism to say "this input document is invalid". AND THEN WHAT? Your only option is to discard it.<p>I'd rather live by the old maxim "be liberal in what you accept, and strict in what you produce". But perhaps I'm overlooking an important use case here, in which I'd happily stand corrected.
Never had to learn the intimidating XML stack in depth but it seems clear that the (superficially definetely more digestible) JSON way of notating data must slowly and painfully reinvent the wheel. Reaching the same level of logical complexity (if it solves the same set of problems) seems unavoidable, no?<p>So if the main advantage of JSON is human readability (not a machine oriented attribute btw :-) might be possible to JSON-ify the XML stack, essentially focusing on appearances and preserving the substance (a bit like the JSON-LD approach)<p>In the end of the day these are frameworks for public data / metadata exchange and removing these frictions would be enormously beneficial to everybody...
For those looking to sanitize input from Typescript, I highly recommend the runtypes library: <a href="https://github.com/pelotom/runtypes" rel="nofollow">https://github.com/pelotom/runtypes</a><p>It let's you specify type definitions a DSL in Typescript using syntax very similar to Typescript's type definitions. Once you define your types in the DSL, you get Typescript types and parsing / verification for free. Not as general purpose as JSON Schema, but 1000x cleaner and easier to use.
Not at all to be critical of JSON schema, but my experience has been that for most use cases it is an overkill. As simple as it may be, it still is relatively complex. As someone mentioned in a prior post, if the validation fails then what? Even though the JSON schema document is human readable, just by looking at the JSON schema document, its not intuitive to visualize where the particular path resides in the actual document. And one would need tools written on top of JSON schema to be able to do operations like merge one JSON document into another while validating at the same time. To make things simple, I had created JDocs. What this allows is to write the JSON schema in exactly the same structure as the JSON data document, just that the value field contains the validation specifications. Of course it does not have all the advanced features of JSON Schema (like some properties and cross referencing abilities), but then as I said, it
meets our requirements in a real straightforward and simple way and opens up multiple possibilities in manipulating JSON data. You can read about it here. I would welcome feedback and apologies if you feel it is off track. Thanks.<p><a href="https://github.com/americanexpress/unify-jdocs" rel="nofollow">https://github.com/americanexpress/unify-jdocs</a>
The way $ref resolution works is hideously complicated, to the point where many JSON Schema implementations just don't even bother supporting external $refs. It really should be a totally separate concern from validation, especially since how you store and compose schemas may end up being specific to a given use case.
A possibly silly question about JSON Schema:<p>What’s with the emphasis on full URLs to describe where to find related schema? Are developers really assembling a bunch of related schema over the Internet instead of just coalescing them in one place for local use?<p>Maybe I just don’t understand the use case. Why would I ever want to make a client do a bunch of calls to URLs I don’t own rather than serving them up reliably and consistently at one time?<p>It feels to me like the idea is some utopia where independent resources everywhere provide schemas and you can start stitching them together. But it just feels… unrealistic and not what I’d actually want.<p>Is this actively realized today? Or does everyone just reference local schemas by relative file path like I do?
Great, now we can finally add the next step in "The Ascent of Ward".<p>EDIT (for the lucky 10.000 of today): <a href="http://harmful.cat-v.org/software/xml/" rel="nofollow">http://harmful.cat-v.org/software/xml/</a>
Bundling for OpenAPI specification has long been a need for authors to allow to reduce duplication, and to allow to split a big specification in multiples files, but publish a single one.<p>A few years ago I've written a tool to fit that niche: <a href="https://github.com/dolmen-go/openapi-preprocessor" rel="nofollow">https://github.com/dolmen-go/openapi-preprocessor</a><p><a href="https://github.com/dolmen-go/openapi-preprocessor" rel="nofollow">https://github.com/dolmen-go/openapi-preprocessor</a><p>I have now to tweak it (well, it will be a major rewrite) to handle $ref relative to $id instead of the file location.
JSON format is simple and easily readable. It’s now so common and probably one of most used language on earth. That’s great! Now, anyone can create a decent API with basic programming tool available. And everyone will be able to use it.<p>Why does some people want to over-engineer it?<p>> { "$id": "<a href="http://…" rel="nofollow">http://xn--rvg</a>" }<p>Oh no. Please don’t do that.
Article:<p>> "Developers of platforms and libraries that use OpenAPI haven't had such a shake up before, and my feeling is it may take more than a few releases to correctly implement all the new shiny features full JSON Schema has to offer."<p>Dear OpenAPI, please avoid the shiny features.
> "There are several libraries which offer bundling solutions, however they all have caveats, and I haven't seen any to date which are fully JSON Schema aware."<p>But what's wrong with just stuffing the schemas in a flat array or object exactly?
A slightly different approach: <a href="https://bitfieldconsulting.com/golang/cuelang-exciting" rel="nofollow">https://bitfieldconsulting.com/golang/cuelang-exciting</a>
A yes. Because things like "integer" totally need to be abstracted away into another schema. Couldn't have given this DSL built-ins for the things that are... you know... built into JSON already.<p>Also bonus points for the apparent lack of shorthands, turning this language into a verbose word salad. I hope there's at least a line of reasoning that explains why some keys are prefixed with '$' and others aren't.<p>Great way to turn something as beautifully simple as JSON into something abhorrent.<p>Hey. You know what is better than JSON at being XML? XML.