search

gossi / docspec

A specification for code documenting tools
5 stars 0 forks source link

Discussion: JSON vs. XML #6

Open mvriel opened 12 years ago

mvriel commented 12 years ago

I understand the negative bias that XML has in many cases due to verbosity but I need to ask what arguments were used to consider JSON.

AFAIK are there no cross-language libraries that allow easy transformation from JSON data to another format; whereas in XML you can use XPath to get pieces of what you want or use XSL to convert an entire document (or parts of it) to another format such as HTML.

Since the structure files can become rather large it would sound inconvenient to load the JSON into a hashmap and then process it.

gossi commented 12 years ago

Hi Mike,

As a disclaimer in front: I used XSLT to generate some docs back in the day, from xml into simple html and as a front end developer I like the ease of JSON.

I think output generators may use one or the other format, so I think later converters from one to the other format will be there anyway. You end up with either a XSLT to transform XML into the format you want or a coffeescript that runs on node to transform JSON into the format you want. At the end it will be a question of taste I guess.

But I still don't know yet. I think you know those structures better due to your docblox usage here. What do you think?

rafalwrzeszcz commented 12 years ago

I think we shouldn't force any format. DocSpec can be completly abstract and format-agnostic. We can provide JSON-Schema for JSON, XML Schema/DTD/whatever for XML etc, but there can be cases where XML can be more usefull and natural. DocSpec can describe just a data structure, without forcing any formats.

gossi commented 12 years ago

I had exactly the same thoughts but later turned out not to be ideal:

  1. What if we had multiple formats, through multiple schema validators. Doctools may generate the one, thats the easiest for their programming language they are using. One Doctool may output XML, the other JSON, another YAML and what else. So, from the perspective of and output generator developer (like me), I may use JSON for my tool, so I need a converter from an 'unknown' format to JSON. Another may use XML as their input so he needs another converter from 'unknown' to XML and it ends up with writing a lots of converters.
  2. So limiting to 2 output formats, JSON and/or XML? Again as output generator developer I still would constrain my input to one format. If a DocTool provides the other one, I still need a converter. There will be less converters but still enough in different languages, if I want to convert from JSON to XML, vice versa is easier through a XSL transformation. What if DocTools provide both formats? well that doesn't make sense to me.
  3. Having one format. We only need converters from one to another format and that's one, that can be bundled with a output generator. This step may also be handled by a build tool.

Would love to hear some feedback on this one :)