There's this structured data format called XML, and typically you put a XML schema definition at the top (example: <xs:schema xmlns:xs="http://maven.apache.org/xsd/settings-1.0.0.xsd"> for a Maven config file). XML code editors then fetch the XML schema declaration, which contains information like what fields are expected, whether those fields are repeatable, whether they are required, and so on. Java library using XML as configuration will typically have published an XSD.
Fun fact: XML schema declarations are themselves XML documents, and there exists an XSD describing allowable XSDs. https://www.w3.org/2001/XMLSchema.xsd
It's a troll post, but the point stands: JSON is reinventing XML.
XML is ugly, but complicated JSON isn't much better IMO. It has an only slightly less human-unfriendly syntax: Why do I have to use double quotes on keys? Why are there no comments? Then come things like schemas, queries, and transformations: XSD, XPath, and XSLT are very powerful tools. Their implementation sucks, but it's arguably better than people coming up with their own half-documented solution whenever they need something XSD/XPath/XSLT provides.
XML protects JSON: people needing extra power choose the complexity in the XML ecosystem, keeping JSON simple.
The problem is usages that grow in their need for power over time, with high switching costs. Instead of choosing, they add pressure to XMLify the JSON ecosystem.
JSON's doom seems distant but inevitable, but it will instead be defeated by the rise of yet another format.
Is it even possible to make a 100% standards conforming parser that is not vulnerable to at least DoS attacks?
(Automatically fetching XSDs e.g. sounds nice in practice, until you realize that it means your server will make HTTP requests to user-supplied URLs, so most parsers come with an option to disable it, which may or may not break documents relying on it.)
> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.
I'd say "for reasons" not necessarily "good" ones. In particular, I think the jury is still out. The hacks that people have done to get comments into npm files are really quite illuminating.
It's funny. He says use a preprocessor to remove comments. Thus not using JSON. It's almost a joke. Except Microsoft does exactly that in their hip project.json format.
Double quotes everywhere are more annoying to read than end tags. If we're going to invent nonstandard formats, why not remove the redundant tag name in the XML end tag. Problem solved.
It allows optional quotes and comments, plus trailing "," and element type specifications. I think it's easier to read and hand-write, as well as write a parser/generator.
Looks like a good take. Your readme would benefit from an example of what luxem looks like, ideally the first thing I'd see, below a short tagline, rather than having to read a lot of text and try to picture what you're describing.
What good reason? Many programming languages have tools that parse comments for various things. With that 'good reason' we should remove comments from all programming languages.
Comments wouldn't be usefull (mostly) for data sent on the wire --and JSON is quite good for that-- but for configuration files, they're indispensable. INI (like git's) is way better of a configuration format than JSON. Easier both to read and to write.
For sending things over the wire, a few way more efficient formats exist. JSON's appeal was simplicity and human-readability. The first goal is achieved OK; the second, so-so.
Indeed, XML-RPC is surprisingly good protocol to this day. The only three
non-unimportant issues with it are (a) verbose XML (which was common back
then), (b) lack of null/none/nil tag, and (c) lack of named arguments (very
uncommon back then).
It seems that this format, while a clever idea, is going to have a lot of problems in describing more complex json documents, which may have optional arguments, arguments that are mutually-exclusive, etc etc.
For example, in the package.json example alone, there are several properties that can be either a string or an object, but it would be hard to expose that in this system.
But maybe this isn't supposed to be documentation, in which case I'm just confused about the purpose of this.
Edit: If more information about the available properties were available at each level (i.e. from the top-level, here are all the possible props; from the "contributors" prop, here are the different possibilities) and this could be used to document one's own project-specific JSON, this could be very cool. But the best would be if it had a way to integrate with a proper schema validator.
Yes, because it could be available while looking at your actual config file (JSON document), and showing you info specific to the element you're looking at, instead of on a separate page and requiring searching for a relevant element.
Why would this be any harder to describe complex JSON documents? Optional arguments don't need to be described if they're not in your specific file – not by something like this anyways. That's what the regular documentation is for, and this could easily link to it too.
Mutually exclusive arguments can easily be linked-to, or, rather, if your file contains one of those arguments then the contextual info can link to any other mutually exclusive arguments.
Why couldn't the context info state that valid values include either a string or an object (of some type and that type linked to in the context info)?
I'm confused about your confusion! It seems like this is a really handy way to show documentation specific to a selected portion of a JSON object for a given format.
OP described the tool as this: "It's an editor for those JSON file formats which shows contextual help as you edit the files."
Is that what it's supposed to be?
Because what I was saying was lacking was any contextual help that tells you what you could add, vs what's already there.
If I were shown http://package.json.is as "contextual help" to help me author my package.json file, I would have no idea that I could add "author" or "contributor" fields. This only gives documentation for the stuff that is already there.
You could add every property to the original document, but that fails if you have mutually-exclusive properties, because the original document would not be valid.
You could try to add every possible property to the top-level comment, but then the top-level comment needs to be practically as long as the original documentation.
Documentation that is incomplete, and doesn't seem to have a reasonable way to make it complete, doesn't seem useful to me -- and in many ways seems worse than not having it, because the incompletion means I would never even realize I was missing useful documentation. I'd have to have the real documentation open on another page anyway, to make sure I'm not missing stuff.
It's an editor for those JSON file formats which shows contextual help as you edit the files, similar to an IDE. It works by parsing the javascript and figuring out where your cursor is relative to the syntax of that particular format.
Likewise. The landing page gave me no clue. I just now went back and clicked on one of those documents, assuming that I'd get some kind of documentation about the format. Turns out it opened a live document editor. I certainly wouldn't have predicted that from the line "Open-source documentation for common JSON formats."
It's documenting the structure of json files used in large projects. On of the three, for example, is documenting the package.json file used by npm. It gives an inline editor to view what one looks like.
Nice, but too bad this is not in JSON Schema (it's a custom bunch of html strings in functions). I would love a more complete JSON Schema for package.json (with custom stuff like browserify or babel config) as VSCode is able to autocomplete JSON files from that.
Exactly - why invent some artisanal Turing-complete thing involving regular expressions and tied to a single proglang when you could achieve the same in a fully declarative, language-agnostic fashion by adding the "description" field into JSON Schemas for the same source documents?
I haven't used webpack enough to be certain but AFAIK, like grunt, the config part is basically just JSON. Sure you can build your object dynamically, but it isn't something like gulp where you use functions to configure your project. In the end you're just exporting one big JSON-serializable object.
It's used to build Eager Apps (and can be used by anything which needs to install a library in a non-technical-person friendly way): https://eager.io/developer/docs/install-json
The buttons aren't actually meant to be read. If you click them, you get to the actual code page which has a much better contrast ratio: http://install.json.is/
Fun fact: XML schema declarations are themselves XML documents, and there exists an XSD describing allowable XSDs. https://www.w3.org/2001/XMLSchema.xsd