
JSON Schema - based2
http://json-schema.org/
======
RobinL
I was unaware of the usefulness of JSON Schema until recently I was writing
some Vega Lite json specs in VS Code.

I don't have any relevant json extensions, but VS Code started auto-suggesting
values for options (e.g. a drop down for whether the chart type is a 'bar',
'line', etc.) and pointing our mistakes like 'the size should be an integer
not a percent'.

This was the lightbulb moment for me - as if by magic, my code editor was
double checking my json document was valid and helping me write it. Amazing,
and super useful.

It took me a while to work out how it was doing it, but all vega lite examples
start with the magic:

"$schema": "[https://vega.github.io/schema/vega-
lite/v2.json"](https://vega.github.io/schema/vega-lite/v2.json").

~~~
davidp
This light bulb is exactly why many people prefer statically-typed programming
languages, especially above a certain codebase size/complexity and team size.

Make my tools do the grunt-work for me, thanks, so I can focus on the actual
problem domain.

~~~
HumanDrivenDev
> This light bulb is exactly why many people prefer statically-typed
> programming languages, especially above a certain codebase size/complexity
> and team size.

I agree, with the caveat that _sometimes_ you need an escape valve.

Basically I want static typing 99% of the time and I don't want guff from the
compiler (or fanboys) in that 1%.

~~~
runeks
That’s what (unchecked) exceptions are for.

They’re supported by all general purpose programming languages because we — as
developers — are smarter than the compiler.

~~~
nardi
1\. GP is talking about type safety in general, not just exceptions.

2\. Not “all general purpose programming languages” support exceptions. To
name a few that don’t: C, Rust, Go.

~~~
bpp
Go has the empty interface, if you really need it.

~~~
majewsky
The empty interface is not an unchecked exception, but panic() is.
[https://golang.org/pkg/builtin/#panic](https://golang.org/pkg/builtin/#panic)

~~~
nardi
I don’t actually know Go, but can panic() be caught? If not, it’s not an
exception.

~~~
ovao
With recover(), yes.

------
niftich
For a long time, json-schema was stuck at draft-04, and it looks like in the
last few months under new authorship it's up to draft-07. The mapping of these
names to IETF RFC revisions is more complicated, and explained on the site
[1].

Json-schema is useful for describing JSON data structures in JSON, so you can
bring a codegen and generate corresponding structures in your language, or
perform some payload validation at an API gateway; and many higher-level API
specs -- like OpenAPI/Swagger -- make use of Json-schema underneath.

However, I'm not sure I fully understand why they branched out into also
becoming a hypermedia description language [2] when there's already half a
dozen others in this space [3], and reading some of the discussion about this
[4] makes my head hurt.

[1] [http://json-schema.org/specification.html](http://json-
schema.org/specification.html) [2] [http://json-schema.org/latest/json-schema-
hypermedia.html](http://json-schema.org/latest/json-schema-hypermedia.html)
[3] [https://sookocheff.com/post/api/on-choosing-a-hypermedia-
for...](https://sookocheff.com/post/api/on-choosing-a-hypermedia-format/) [4]
[https://github.com/json-schema-org/json-schema-
spec/issues/4...](https://github.com/json-schema-org/json-schema-
spec/issues/48)

------
peterkelly
Is there something wrong with just using TypeScript's type system for
expressing the required format of JSON data that would make me want to use the
significantly more verbose JSON schema format instead? I've written a couple
of code generators (e.g. [1]) in the past which use the former approach and
found it a very convenient way to express my models.

For example this:

    
    
        {
            "title": "Person",
            "type": "object",
            "properties": {
                "firstName": {
                    "type": "string"
                },
                "lastName": {
                    "type": "string"
                },
                "age": {
                    "description": "Age in years",
                    "type": "integer",
                    "minimum": 0
                }
            },
            "required": ["firstName", "lastName"]
        }
    

can be expressed like this:

    
    
        interface Person {
            firstName: string;
            lastName: string;
            age?: number; // Age in years
        }
    

I can see that there are additional constraints expressible, such as the fact
that age has to be an integer and has a minimum value. However those could all
conceivably comprise a superset of TypeScript's interface definitions. JSON
Schema just feels to me like XML Schema all over again.

[1]
[https://www.npmjs.com/package/jsonidator](https://www.npmjs.com/package/jsonidator)

~~~
zbentley
TypeScript provides, primarily, a type _verification_ system.

JSON-schema provides a type _assertion_ system.

Both serve as type documentation systems.

TS says "if you create objects in my world, I will use my type system to
verify that you're creating the right kind of objects, and you can look up
their definitions to see what's in them". JSON-schema says "if you give me
external, un-annotated objects, I can tell you whether they comply with a type
definition, and you can look at that definition to see what's in them".

TS has a limited assertion facility, but it's not nearly as capable as JSON-
schema. Projects like io-ts ([https://github.com/gcanti/io-
ts](https://github.com/gcanti/io-ts)) add more functionality to those
assertions, but they're still much less easy to use, in my opinion, than JSON-
schema for this purpose. If you're using TS types to assert, though, you can
definitely describe more complex constraints, so it may make sense as an
alternative to JSON-schema for some people.

As others have pointed out, JSON-schema is also much easier to use on non-
TypeScript platforms than TS assertions, which, even if you use an assertion
library like io-ts, will still be limited in use to JavaScript (and JS-
to-$other_language runtimes).

~~~
CMCDragonkai
A dependent type system can do both.

~~~
zbentley
...yes it can?

Would you expand on how dependent type systems are relevant to the differences
between TypeScript/JSON-Schema, or how the use of a DTS could help ameliorate
the issues people have in those areas?

~~~
CMCDragonkai
Not in an HN comment, but here's a paper called Power of Pi
[https://cs.ru.nl/~wouters/Publications/ThePowerOfPi.pdf](https://cs.ru.nl/~wouters/Publications/ThePowerOfPi.pdf)
that probably explains it the best. It shows the usage of it for deriving a
parser and generator from a single specification, and also crypto protocols
and database usage. It uses Agda for its examples, but it can be translated to
Idris as well.

------
nathan_f77
This is what I'm using for schema validation in FormAPI [1]. The best part
about using a standard is that there's a lot of open source libraries you can
use. It's really easy to validate a schema in Ruby [2]. I use json-schema-
faker [3] to fill out PDFs with test data. I also use AlpacaJS [4] to generate
HTML forms based on the JSON schema.

Anyway, I'm really glad I didn't try to roll my own thing for schema
validation. Alpaca is insanely powerful, and it would have taken me weeks or
months to build the online forms from scratch.

[1] [http://formapi.io](http://formapi.io)

[2] [https://github.com/ruby-json-schema/json-schema](https://github.com/ruby-
json-schema/json-schema)

[3] [https://github.com/json-schema-faker/json-schema-
faker](https://github.com/json-schema-faker/json-schema-faker)

[4] [http://www.alpacajs.org/](http://www.alpacajs.org/)

~~~
tappleby
We have a similar setup for extending our app with custom fields / forms using
ruby-json-schema and react-jsonschema-form [1].

ruby-json-schema has worked out quite well, we added a custom schema reader so
that we could generate enums dynamically based on records in the database via
custom refs eg. app://schemas/organizations?type_eq=education&tags=one, any of
these internal refs are inlined at the API layer.

One issue we did run into with ruby-json-schema, is the schema caching is not
thread safe. We opted to clear the cache after each validation, this ended up
causing race-condition issues. In the end we had to use a mutex on write and
cache the validation result (not ideal, but our app isn't that write heavy).

[1] [https://github.com/mozilla-services/react-jsonschema-
form](https://github.com/mozilla-services/react-jsonschema-form)

------
dvdsgl
Creating a JSON schema for your data and committing it is a great way to
codify assumptions about the data consumed or produced by your program. Once
you have a JSON schema for your data, you can generate models and serializers
in many languages with quicktype:
[https://app.quicktype.io#s=coordinate](https://app.quicktype.io#s=coordinate)

------
amthewiz
Reminds me of XSD - the XML schema definition language that itself is XML. Any
takeaways (good/bad/ugly) from that experience that are applicable here?

~~~
brightball
My first thought on seeing the headline was "continuing to reinvent the XML
ecosystem...in JSON"

~~~
HumanDrivenDev
Do you consider that a negative?

I personally think it's great. The faster the ecosystem is reinvented the
sooner we can stop wasting our lives reading it.

~~~
brightball
It just strikes me as a circular development pattern.

~~~
bonesss
XSD is only part of the value-offering... XSD + XSLT is the value provider for
format heavy, robust, declarative, document transformations.

JSON-schema solves many of the validation issues of JSON in the absence of an
XSD-for-JSON solution, to allow message processing and other validation
assertions. From that perspective it's 'duplicated effort', but only to the
extent that JSON messaging applications are maturing to the point they need
the kinds of guarantees that were so clear during the development of XML/SGML.
It's a whole different language supporting a range of JSON-powered clients
that don't necessarily require transformation support or other guarantees.

This is about JSONs ecosystem maturing to the baseline, not about reinventing
the wheel :)

------
redwood
This is what mongodb picked up for schema validation in its last release:
[https://docs.mongodb.com/manual/core/schema-
validation/](https://docs.mongodb.com/manual/core/schema-validation/)

------
ljm
This was incredibly handy when I was building a Slack bot that helped my
colleagues figure out what microservice did what, since they often had
puntastic names and there were enough that it was hard to keep track of
([https://github.com/leemachin/wtf-is](https://github.com/leemachin/wtf-is)).
It made it really easy to validate the structure of the metadata file and
return errors that made at least some sense to the person trying to integrate
it.

It's not particularly friendly to the maintainer compared to switching to a
statically typed language, but it would have taken a fair bit more effort to
wire that up without this.

------
relequestual
Hi all! I'm one of the new team that works on JSON Schema since draft-4.

I could spend time addressing each issue raised here, but that could take some
time...

@niftich We've (the new authorship) actually been working on JSON Schema since
late 2014!

If you're using JSON Schema, or are interetested in finding out more, we DO
now have a slack server; invite link at the bottom of json-schema.org. Come
talk with us.

We're looking for companies who are using it in production to weigh in on new
developments and releases. Our current release plan means we will have an RC
with time for feedback. We want to hear your issues, comments, and
suggestions!

One common problem at current is the level of support. Because draf-4 has been
around for a LONG time now, it became the defacto standard, and has the most
support. Developers come along and use an older library which only supports
draft-4, but want to use new functionaltiy found in draft-7. Many
implementations support draft-7, and some even implement new functionaltiy
before it's finalised. SO remember to check which version of JSON Schema the
library you're using supports.

HyperSchema already exsisted at that point, so we inheirted it. It focuses on
providing specification for correct HTTP usage and HATEOAS driven APIs, where
as other higher level API specification languages allow you to describe any
type of API.

It looks like a good number of you have good questions, ideas, or issues.
Thanks for all those replying supporting JSON Schema and those showing a
balanced viewpoint.

Come chat with us!

------
NelsonMinar
Does anyone actually use JSON Schema for real?

~~~
colept
Not since I discovered GraphQL. It's hard to imagine any other abstraction on
top of REST APIs that packs as much robust functionality in something so easy
to use.

~~~
avmich
I'm just curious - GraphQL is more of a query standard, while JSON Schema is
structure validation. How could one use GraphQL for, say, validating input?

------
dchuk
My startup built an extended version of JSON Schema that also supports
conditional logic and data references to power a customer-configurable
Workflow system. Basically a lightweight way to script a series of tasks with
more advanced validations and data pre-population. Works great, customers love
it.

~~~
chatmasta
I built this same thing in the past month for automated questionnaire
rendering in react, saving and merging the responses into word documents.

~~~
dchuk
whoa what's up man?! Wickedfire paths cross in the most random ways haha

~~~
chatmasta
Hah, seriously man! I’ve seen you here a couple times, would love to catch up.
Ping me? Email in my profile

------
lykr0n
This stuff is great. I used it to design an API in Python.

A request comes in and the wrapper checks for a schema. if it is not a GET
request and one does not exist it errors out even before the method is called.
If one exists, the schema is validated automatically. If the target method is
called, you can be safe assuming that the input is valid (in terms of type and
does it exist or not).

Same goes for output. Server will error out before it lets incorrect output be
returned to the user. Great way to present what the application accepts to a
developer. This is what it will accept and return, because this is what we use
to validate input and output!

------
HumanDrivenDev
Anybody using this in production?

We (reluctantly) went with XML for an external facing B2B API, because JSON
schema was stuck in draft and did not seem to be in widespread use. JSON
without schemas would have been a nightmare.

~~~
deathanatos
We "use" this in the form of Swagger, which is a web service that can download
a specification of how an HTTP API works and generate a minimal UI to use that
HTTP API from that specification. While the specification of the API is in
"Swagger", the actual documentation of types used by the API is JSON-Schema.

The UI is okay; however, we've had two big downsides:

* The UI needs to be able to fetch the JSON schema document from the API; that means that it needs to correctly respond with CORS headers if you host the web interface on a separate domain. (We do, s.t. each API service doesn't need to repeat the mundane task of hosting it and keeping it up to date.)

* The schema needs to be useful. Far too often, people will document an API endpoint as taking "JSON" and returning "JSON"; this is true and correct, but not _helpful_. What keys exist? What are the valid values for those keys? etc. The author of the schema needs to take the time and thoroughness to document the API, and all too often either they do not (the workmanship is sloppy) or they can not (management provided deadlines that were too tight to get the job done right).

Neither of those are really problems with JSON-schema per se. You also don't
_need_ JSON schema to document a JSON API: you can always do so with prose, by
using the type system of a language your devs are familiar with and providing
a set of rules to map those structures/types to JSON object, etc.

My biggest nit with JSON schema: it's painful for humans to interpret. (And we
actually do it in Swagger, which is in YAML, so it's slightly easier to parse
and we get comments. But it's considerably verbose compared to most type
systems; the upside is that it _can_ encode more information such as
descriptions, or valid ranges/values if the raw type like "number" or "string"
doesn't suffice.)

------
willtim
It's such a shame that many of these standards ignore or are ignorant of the
elementary and fundamental sum type. Instead I am left needing to employ some
ad-hoc encoding using string tags or similar.

~~~
dmcg
Does oneOf not cover it?

~~~
willtim
oneOf looks like it could be used to encode sum types together with a custom
string tag, but that's not the first class treatment that records get.

~~~
henryluo
Mark ([https://mark.js.org](https://mark.js.org)) is a new notation that
extends JSON with a type-name, which can be a more structured way to encode
type info, instead of using custom string tag.

------
dvdhnt
I'm just now becoming familiar with JSON Schema. It's very interesting.
However, before I or my team new it existed, we created this for filtering and
validation, which has its own sort of schema:
[https://spireteam.github.io/whitelister/](https://spireteam.github.io/whitelister/)

~~~
mplewis
Your site's CSS makes it unreadable on wide screens:
[https://imgur.com/a/WlYOA](https://imgur.com/a/WlYOA)

------
vram22
JSON Schema is useful. Here is a post with a Python example of using it to
validate some data:

Using JSON Schema with Python to validate JSON data:

[https://jugad2.blogspot.in/2015/12/using-json-schema-with-
py...](https://jugad2.blogspot.in/2015/12/using-json-schema-with-python-
to.html)

------
mattnewton
I can imagine uses, but I was looking for some kind of faq that answered what
problem this was solving. Aren’t there other serialization specification
formats that come with type validation built in (like protocol buffers and
thrift), that can be serialized to json as well? Maybe I am confused about
what this does.

------
avmich
These guys -
[https://cswr.github.io/JsonSchema/](https://cswr.github.io/JsonSchema/) \-
analyse JSON Schema and propose some mostly non-breaking adjustments.

------
jbverschoor
Techies are so f'ing useless. We keep reinventing every frikking wheel. I
should get out of tech, it's depressing

~~~
reificator
What, JSON shouldn't have schemas because they exist for other formats? Or
JSON shouldn't be used because XML is good enough?

While I agree that tech should reevaluate its sisyphean upgrade treadmill, I'm
not sure how that relates here.

~~~
eadmund
> Or JSON shouldn't be used because XML is good enough?

Mu. Neither JSON nor XML should be used, because S-expressions are good
enough, and more attractive to boot.

~~~
reificator
[https://eli.thegreenplace.net/2012/03/04/some-thoughts-on-
js...](https://eli.thegreenplace.net/2012/03/04/some-thoughts-on-json-vs-s-
expressions)

