神刀安全网

Specifying JSON

I find my­self tasked with pol­ish­ing and pub­lish­ing a lit­tle cus­tom JSON-encoded lan­guage. It’s hard­er than it ought to be.

This didn’t start with the lan­guage, it start­ed with pro­to­type soft­ware this guy wrote, that did some­thing old and fa­mil­iar in a new and dra­mat­i­cal­ly bet­ter way. He re­placed a bunch of gnarly old code with a few JSON tem­plates to save time. Now, in the rearview, the JSON looks like an im­por­tant part of an im­por­tant pro­duc­t.

And there’s a les­son in that: All the good markup vo­cab­u­lar­ies are dis­cov­ered by coders try­ing to get shit done, not cooked up in com­mit­tee rooms in ad­vance of soft­ware. For ex­am­ple, TimBL just need­ed to tag his hy­per­texts. Not that this is that big.

Q: Why JSON? · If it looks like a doc­u­men­t, use XML. If it looks like an ob­jec­t, use JSON. It’s that sim­ple. The es­sen­tial dif­fer­ence isn’t sim­plic­i­ty/­com­plex­i­ty or com­pact/ver­bose or type­d/­tex­t, it’s ordered-by-default or not.

This par­tic­u­lar thing I’m work­ing on is a lot like ob­jects and not at all like doc­u­ments. Case closed.

By the way, it’s amus­ing that this cen­tu­ry hasn’t yet of­fered a plau­si­ble new markup al­ter­na­tive to the last one’s mouldy left­over­s. Al­so pleas­ing to one who has left fin­ger­prints on both left­over­s.

Q: How to au­thor? · With pain. By de­fault, I write things in Emac­s, which un­ac­count­ably doesn’t have a JSON mode that knows where to put the fuck­ing com­mas .

I’ve al­so tried edit­ing JSON in In­tel­liJ and it’s not ter­ri­ble but not re­mote­ly good enough. I’m writ­ing what you’re now read­ing in XML in an Emacs mode that’s a fantastically-productive finely-tuned ma­chine, so the thing should be pos­si­ble.

There’s an­oth­er so­lu­tion: make JSON eas­ier. Hj­son (“the Hu­man JSON”) ad­dress­es this prob­lem and looks quite clean­ly thought out. There’s al­so JSON5 (“JSON for the ES5 era”), but I stopped read­ing at “Unicode char­ac­ters and es­cape se­quences aren’t yet supported”.

Me­h. Few­er markup lan­guages are bet­ter; fix the ed­i­tors, I say. Maybe Ama­zon would be OK with me drop­ping all this cloud stuff and work­ing on JSON au­thor­ing tools for a few month­s? Not hold­ing my breath.

Q: How to spec­i­fy? · If you want to ship your own lan­guage, you need to spec­i­fy it. The most im­por­tant part of any lan­guage spec is the human-readable prose that de­scribes the con­struct­s, says what they mean, and of­fers ad­vice on how to use them.

Next most im­por­tant is ex­am­ples; lots of ’em, well-chosen, and down­load­able from some­where.

(Ac­tu­al­ly, if you ev­er find your­self tasked with spec­i­fy­ing some­thing, go read Mark Pilgrim’s Why specs mat­ter , which clar­i­fies your task: Turn­ing mo­rons in­to ex­pert­s.)

Next most im­por­tan­t, an open-source val­ida­tor, so peo­ple can check their ef­fort­s; it should have help­ful er­ror mes­sages which in­clude line and col­umn num­ber­s.

Now, to write the val­ida­tor, a schema will help, and you should write one any­how; if you’re like most peo­ple, writ­ing down the for­malisms will prob­a­bly shake out some bugs and slop­py think­ing in your men­tal mod­el of your lan­guage.

Hav­ing a schema is a lousy way to ex­plain a lan­guage, and it on­ly solves part of the val­i­da­tion prob­lem, be­cause any non­triv­ial lan­guage will have se­man­tic con­straints that you can’t cap­ture declar­a­tive­ly.

But like I said, you should write one any­how. Which means that if your lan­guage is JSON-based, it sucks to be you, be­cause JSON Schema is a big fat pool of pain.

JSON Schema, sigh · If you find your­self need­ing to use it, run don’t walk over to Un­der­stand­ing JSON Schema , which has lots of ex­am­ples and rea­son­ably human-readable nar­ra­tive; a nice piece of work.

In its first para­graph, it says “learning to use [JSON Schema] by read­ing its spec­i­fi­ca­tion is like learn­ing to drive a car by look­ing at its blueprints.” They’re be­ing tact­ful; the JSON Schema spec is re­al­ly not very good at al­l. I don’t think this is a con­tro­ver­sial thing to say, but let me of­fer some ev­i­dence any­how.

Most ob­vi­ous: There are mul­ti­ple pieces of soft­ware out there that claim to im­ple­ment JSON Schema, and their be­hav­ior is re­al­ly in­con­sis­ten­t, in my ex­pe­ri­ence.

One area where I ob­serve in­con­sis­ten­cies is in the han­dling of the “$ref” con­struc­t. Ir­ri­tat­ed, I de­cid­ed to go check the of­fi­cial spec. “$ref” is not de­fined (but is used) in JSON Schema Core . Same for JSSON Schema Val­i­da­tion . Same for JSON Hyper-Schema . Same for the Core/Val­i­da­tion Meta-Schema and the Hyper Meta-Schema

Ac­tu­al­ly, I could be wrong; the spec is re­al­ly hard to read; and I say that as one with much more ex­pe­ri­ence in spec-reading and schemas than most.

When I’m defin­ing a lan­guage, I need to work on the schema and the val­ida­tor and the ex­am­ples all to­geth­er, it­er­a­tive­ly, val­i­dat­ing things mul­ti­ple times per min­ute, so I need a tool that I can run from the com­mand line that is:

  1. Fast,

  2. con­sis­ten­t,

  3. com­plete, and

  4. re­ports er­rors with line and col­umn num­ber­s.

So far, I haven’t found one. JSONLint (npm) isn’t up to date with the lat­est schema spec draft. json-schema and json_schema (ruby; see, hy­phen vs un­der­score, isn’t that quain­t?) are in­con­sis­ten­t, par­tic­u­lar­ly in their han­dling of “$ref”, and nei­ther of them re­ports line/­colum­n, and nei­ther of them re­spond sane­ly to JSON-level rather than schema-level er­rors.

Then there’s json-schema-validator , but that’s in Java, which means it’s prob­a­bly too slow for command-line use, and al­so I’m not smart enough to run Ja­va from the com­mand line with­out hand-holding from an IDE or a re­al­ly good build sys­tem that knows de­pen­den­cies.

Feaugh.

What I’m ac­tu­al­ly do­ing · First, I’m keep­ing my schema in one great big file; cross-file “$ref” han­dling is ir­re­me­di­a­bly bro­ken, near as I can tel­l.

Se­cond, I’m us­ing “json-schema” (hy­phen not un­der­bar) in a lit­tle ru­by scrip­t, which first of all runs “jsonlint” to check for ba­sic JSON san­i­ty. “jsonlint” at least does line num­ber­s, yay. ♫ Ru­by and Node, sittin’ in a tree…

Be­cause I dis­trust the tools I’m build­ing a Ja­va testbed in In­tel­liJ that will let me double-check with “json-schema-validator” from time to time.

JSON spec­i­fi­ca­tion fu­ture? · I no­tice that the most re­cent JSON-Schema IETF draft ex­pired in 2013, and that a cou­ple of the tools have “looking for maintainer” signs post­ed on them.

Now that I’ve most­ly fig­ured out JSON Schema, I nei­ther love it nor hate it. So far, I’ve been able to make it do what I want­ed. But it sure feels lame com­pared to RELAX NG , in terms of pol­ish, doc­u­men­ta­tion, and tool­ing.

This is a space that could use some work.

转载本站任何文章请注明:转载至神刀安全网,谢谢神刀安全网 » Specifying JSON

分享到:更多 ()

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址