json schema to "human readable" layout

[Andrei Neculau]

I got a "complaint" today that if you want to get an overview of a JSON schema definition, it's ~7 (out of 10) on the annoyance scale to do that by looking at a pure JSON schema file.

Has anyone spent any time on thinking of or implementing some sort of parser into some HTML table-like easy-to-the-eye layout ?

[Json Schema]

The only tool I know of is not directly intended for that purpose, but does have the following features that may help you:

1. JSON schema objects can be collapsed

2. JSON schema object highlighting

3. Large chunks of the schema can be deleted to make clear only the schema objects you're interested in

Find it here: http://www.jsonschema.net

I'm hardly impartial on this, but I do think it makes schemas readable and also you can play around with hiding the parts you don't wish to read.

Kind regards,

Jack 

On 5 October 2012 16:40, Andrei Neculau <andrei....@gmail.com> wrote:

I got a "complaint" today that if you want to get an overview of a JSON schema definition, it's ~7 (out of 10) on the annoyance scale to do that by looking at a pure JSON schema file.

Has anyone spent any time on thinking of or implementing some sort of parser into some HTML table-like easy-to-the-eye layout ?

--
 
 

[Andrei Neculau]

Thanks

For now, since I see the readability part so "subjective", or at least in need of attention from a designer,

I will go with converting a JSON schema to Orderly on-the-fly for these readability purposes

[Luis Montes]

ctrl+shift+J in chrome, console.log() a shema object to inspect the hierarchy and get highlighting :)

--
 
 

[Matthew O'Donoghue]

Shameless plug but would Matic not help here?

--
 
 

[Andrei Neculau]

thanks, not convinced though

PS: having an dummy example site would be nice

[Matthew O'Donoghue]

Oh sorry I have two:

https://github.com/mattyod/matic-very-simple-example

https://github.com/mattyod/matic-simple-example

Aiming to put up a more complex one soon.

--
 
 

[Andrei Neculau]

I meant "built-example" by example site, so that one doesn't need to download matic, one of the example repos, only to see what the output is like.

[Geraint (David)]

Don't know if it's helpful, but I knocked this together: http://geraintluff.github.com/jsonary/demos/view-schema.html

Some aspects of schemas are not currently displayed (like "format", for instance), but it might still be useful.

Also, the library is uses is currently not tested on all browsers, and requires a shim to to work on IE (for things like JSON parse/stringify), although that's on my to-do list. :)

[Geraint (David)]

It's probably also worth mentioning that it's focused on the current v4 proposals, so it might not recognise some v3-style stuff.  If it's useful, I can put that stuff in.

[Andrei Neculau]

Interesting work

Thanks

[Andrei Neculau]

David,

is it possible to extract this functionality as a module out of jsonary? It's a nice standalone piece of software imho.

[Geraint (David)]

You mean creating a version that doesn't require Jsonary in order to work?

I guess it's possible, if you only wanted the read-only view.  The actual renderer itself is a bit of a mess (sorry!), but one could trawl through it and replace Jsonary with direct recursion.  I must confess I'm not very personally motivated to do that, but you're welcome to go for it.

I am going to carry on developing that schema renderer, though, because I'm using it to display (and in fact edit) bits of my API documentation (the function arguments/results are specified as JSON Schemas).

That's probably not quite what you wanted, though - sorry.

[Andrei Neculau]

No need for "sorry".

I must confess that _I_ wasn't up for this, and I was trying to... delegate =)

Really - great work. If I ever start a "renderer", I think your UX is adequate.

[Ganesh and Sashi Prasad]

Readability is a real human concern, but rather than make drastic changes or require tools to visually collapse a document, I suggest that the standard be modified slightly so that all schema "keywords" are prefixed with underscores. I've found that this simple trick immediately distinguishes data from metadata and makes a schema document more comprehensible.

Example modified from the one on the Orderly site:

{
  "_type": "object",
  "_properties": {
    "name": {
      "_type": "string"
    },
    "description": {
      "_type": "string",
      "_optional": true
    },
    "homepage": {
      "_type": "string",
      "_pattern": "^http:"
    },
    "invented": {
      "_type": "integer",
      "_minimum": 1500,
      "_maximum": 3000
    }
  },
  "_additionalProperties": true
}

Just visually parse this schema looking for strings without an underscore and you'll see what the core document is supposed to look like. It's just four elements ("name", "description", "homepage" and "invented") and they leap out at you.

What do you think?

Regards,

Ganesh

> --
>  
>  

[Ganesh and Sashi Prasad]

A convention of using underscores will also at one stroke end the confusion over the attribute "name", which is one of the most maddening aspects of a schema. Are we referring to an attribute (of a business document) called "name", or a metadata element that refers to the name of an attribute? The latter now becomes "_name" and there is no more confusion.

Regards,

Ganesh

[penduin]

I see the appeal of underscores, and I may come around on it, but there's something I think is worth mentioning, and it applies to this and a number of other proposals...

All changes to the spec that are something other than a superset of what it is now, have the potential of fracturing the available tools.  I personally will most likely update WJElement to validate according to post-v3 drafts, but that would be a hard sell if it would affect customer data or integrations, for example.  Some current tools will have a supported base going forward that for one reason or another will make major spec revisions very problematic to implement.

Now, maybe that's not a problem worth worrying about.  I was a pretty early adopter of JSON Schema, and this stuff comes with the territory for early implementations.  And even if there were tons of widely-used tools out there already for v3 of the spec, just look at Python.  Old and new versions can coexist if need be.

"Perfect" shouldn't be the enemy of "good enough".  The v3 spec was good enough for a decent collection of useful code to have grown up around it.  It's quirky, but it helps us get the job done.  Like the x86 architecture, or Bash, or JavaScript itself.  Growing slowly and organically, even if it's uglier, has its advantages.  Those things are not elegant, but they're everywhere.  Food for thought.  :^)

[Andrei Neculau]

sorry. you didn't convince me with the underscores

[Geraint (David)]

Me neither.

The schema format as it exists at the moment is syntactically unambiguous.  So the underscores are there simply as clarification for the human reader.

It sounds like what you *really* want is a syntax highlighter for JSON Schema.  Something that highlights keywords in blue, and other keys in green italics or something.  Trying to approximate that effect by changing the keywords themselves is a really bad idea.  We're already dealing with JSON!  We are flooded with { and } and ".  I don't think that adding _s to the mix will help.

You also simply add more confusion when describing any JSON format which has underscores itself, such as HAL.

[Geraint (David)]

@penduin:

Thanks for raising this point.

There are some places where the v4 draft changes the behaviour of keywords, or keywords have been removed.  For instance, "extends" has (essentially) been renamed to "allOf", partly because of the intense confusion surrounding the concept of extending schemas.  The "types" keyword can no longer contain schemas - the new "anyOf" and "oneOf" keywords are there for that.

However it should still be possible to create a validator that can use v3 or v4 interchangeably, simply by inspecting the schema data itself.  So updating tools to also support v4 does not have to affect v3 functionality at all.  If you can think of a situation where that is not true, then please shout loudly about it either here or on GitHub.

[Ganesh and Sashi Prasad]

We don't have to fracture available tools. Just add the variants with underscores to the spec with the recommendation that this is the preferred format, and deprecate the non-underscore equivalents over time.

Regards,

Ganesh

--
 
 

[Geraint (David)]

Basically, you're proposing we change every single keyword, which is a huge change to the spec.

It would add a lot of boilerplate code to any tool that deals with JSON Schema, and I don't think it's worth it for a subjective readability improvement (that ends up more confusing if we are describing a JSON format with underscores in).

If you want that kind of readability, I reckon you could create a syntax highlighter in less than 100 lines of JavaScript.

[Geraint (David)]

In fact: https://gist.github.com/3945460

That's just a hacked-together quick solution, but it highlights schema properties in green, except for the sub-properties of "properties" (which it highlights blue), and the values of "default" and "enum" which are all plain black.

I think that if you have problems with readability, some tactical highlighting like that is probably a better solution than large-scale changes to the standard.

[xmlbuddy]

Hi group,

I'm currently developing a tool that will be able to do JSON schema specific syntax-coloring. I'm sure this will increase the readability of any JSON schema a lot. At the moment JSON syntax-coloring and auto-completion is available. However, the tool is a standalone Windows desktop editor.

A long term goal is to provide a graphical JSON schema editor but this still needs to be designed and evaluated...

Kind regards

Clemens

[Andrei Neculau]

Good luck, Clemens!

My own experience - colouring is fine, but it will still not be enough.

Geraint's tool is at the top on my list http://geraintluff.github.com/jsonary/demos/view-schema.html , and the ones that complained to me agreed that this is very close to what is needed.

When I have/make time, I will take that piece of code out of jsonary and make it standalone. Or if someone has the time now.. =)

[xmlbuddy]

Just the syntax-coloring is surely not enough. But together with validation it is a first step for the editor to support the creation of JSON schemas.