JSON Schema bundling formalised

Glad you asked! ;)

https://donhopkins.medium.com/the-x-windows-disaster-128d398...

[...] X-Windows is the Iran-Contra of graphical user interfaces: a tragedy of political compromises, entangled alliances, marketing hype, and just plain greed. X-Windows is to memory as Ronald Reagan was to money. Years of “Voodoo Ergonomics” have resulted in an unprecedented memory deficit of gargantuan proportions. Divisive dependencies, distributed deadlocks, and partisan protocols have tightened gridlocks, aggravated race conditions, and promulgated double standards. [...]

X: The First Fully Modular Software Disaster

>X-Windows started out as one man’s project in an office on the fifth floor of MIT’s Laboratory for Computer Science. A wizardly hacker, who was familiar with W, a window system written at Stanford University as part of the V project, decided to write a distributed graphical display server. The idea was to allow a program, called a client, to run on one computer and allow it to display on another computer that was running a special program called a window server. The two computers might be VAXes or Suns, or one of each, as long as the computers were networked together and each implemented the X protocol.

[...]

X-Windows: …A mistake carried out to perfection. X-Windows: …Dissatisfaction guaranteed. X-Windows: …Don’t get frustrated without it. X-Windows: …Even your dog won’t like it. X-Windows: …Flaky and built to stay that way. X-Windows: …Complex non-solutions to simple non-problems. X-Windows: …Flawed beyond belief. X-Windows: …Form follows malfunction. X-Windows: …Garbage at your fingertips. X-Windows: …Ignorance is our most important resource. X-Windows: …It could be worse, but it’ll take time. X-Windows: …It could happen to you. X-Windows: …Japan’s secret weapon. X-Windows: …Let it get in your way. X-Windows: …Live the nightmare. X-Windows: …More than enough rope. X-Windows: …Never had it, never will. X-Windows: …No hardware is safe. X-Windows: …Power tools for power fools. X-Windows: …Putting new limits on productivity. X-Windows: …Simplicity made complex. X-Windows: …The cutting edge of obsolescence. X-Windows: …The art of incompetence. X-Windows: …The defacto substandard. X-Windows: …The first fully modular software disaster. X-Windows: …The joke that kills. X-Windows: …The problem for your problem. X-Windows: …There’s got to be a better way. X-Windows: …Warn your friends about it. X-Windows: …You’d better sit down. X-Windows: …You’ll envy the dead.

When using tooling that accepts YAML (or JSON) configuration, I always want something to say "this is what you can write that will have an effect".

As a specific example, when I'm writing a snapcraft.yaml, I want to be able to view a schema to see what all I can put in there. What's important is that the schema is actually used by snapcraft itself for validation, otherwise it's no better than the rest of the snapcraft documentation, which is pretty meh. Schemas are also easy to digest for other tooling, so e.g. my editor can automatically highlight when I make a mistake, without having to specifically write a plugin for each tool that accepts JSON/YAML

To be clear, I don’t have a lot of experience with JSON schema, but recently I found myself needing to validate Azure ARM templates using json schema, and my god is the Microsoft provided schema insane. Go look for yourself: https://schema.management.azure.com/schemas/2019-04-01/deplo...

That’s the root schema definition, but there are many, many references within, and they go deep. I tried using the bundling tool mentioned in the article to bundle all the references schemas and it came out to 25MB, minified. But if you don’t bundle, then you are right, your tool has to crawl the document and make many more http calls to deref everything. It’s so frustrating to work with.

Over the past year I’ve built an ESB for a client’s deployment of a brand spanking new distribution management system … which you could integrate with only and solely using SOAP. The tooling in Java makes it bearable, but I am still shocked that this system deployed in 2021 has this.

What is hard to read and difficult to understand about this:

    schemaValidate(input, { 
        "required": ["price"]
        "properties": { 
            "price": {
                "type": "number",
                "minimum": 0,
                "maximum": 1000
            }
        }})

vs

    if (input.hasOwnProperty("price"))
        throw Error("Missing price property")
    let price = parseInt(data["price"], 10)
    if (isNaN(price))
        throw Error("Property 'price' is not a number")
    if (price  1000)
        throw Error("Property 'price' is too high")

Not claiming the later is particularly difficult, in fact it's very easy to understand, but it is sligthly more verbose and tedious, for bigger validations it can become even worse. Here the schema turns every 2-3 lines of custom validation code into 1, provides automatic and better error messages of the error cause and acts as a contract which consumers of the api can read or even use to auto generate code, GUI, autocompletion. For the later use cases you would of course put the schema in a separate public file. For more complex validation you can of course add them after calling schemaValidate.