RejectedSoftware Forums

On Sat, 09 Mar 2013 12:11:09 GMT, Sönke Ludwig wrote:

There has been some discussion about using a different format than JSON for the package description files. While this topic is techinically not particularily pressing, it would be good to know where to go with this early. The two candidates so far are YAML and SDL. JSON will still be supported for backwards compatibility and as the default format that is transferred over the network (package registry). The following sections list the pros/cons of each format and an example of how it could look like. My favorite so far is SDL, which was originally proposed by Nick Sabalausky, who also made a D implementation. So now I think it would be good to get some more input to get a collective opinion on this before implementing anything.

JSON

While I think the current JSON based format for the package description is OK, it does have a few drawbacks:

• No support for comments
• Key names must be quoted, although they are just plain identifiers
• Commas between individual fields -> danger of syntax errors for the last field
• The very generic structure makes it easy to learn, but sometimes a bit verbose
• Relatively deep nesting

Example:

{
	"name": "my-package",
	"description": "A package for demonstration purposes",
	"dependencies": {
		"vibe-d": ">=0.7.13",
		"sub-package": {"version": "~master", "path": "./sub-package"}
	},
	"configurations": [
		{
			"name": "console",
			"targetType": "executable",
			"versions": ["ConsoleApp"]
		},
		{
			"name": "gui",
			"targetType": "executable",
			"versions": ["ConsoleApp"],
			"libs-windows": ["gdi32", "user32"]
		}
	]
}

YAML

YAML basically has the same structure as JSON, but allows an alternative syntax using indentation instead of clamps to group items together. It also removes the quotes around strings. Furthermore, tt allows a multitude of ways to format the file (including JSON, which is a subset of YAML), which can be handy, but can also make it harder to learn or read, depending on how it is actually written. It follows the same structure as JSON, but supports comments.

Example:

---
name: my-package
description: A package for demonstration purposes
dependencies:
	vibe-d: ">=0.7.13"
	sub-package:
		version: ~master
		path: ./sub-package

configurations:
	# command line version
	- name: console
	  targetType: executable
	  versions:
	    - ConsoleApp

	# Win32 based GUI version
	- name: gui
	  targetType: executable
	  versions:
	    - UseWinMain
	  libs-windows:
	    - gdi32
	    - user32		

SDL

Finally, SDL has a tag+attribute based structure that differs from the other two and allows to vary how certain data fields are specified. It uses curly braces as the means to create a tag hierarchy and otherwise goes without punctuation (except for quotation marks) and thus results in clean files. Syntax-wise it comes closest to D when comparing the three contenders. Finally, the tag based nature facilitates a design with less nesting and less syntactic ambiguity (e.g. fields that may only occur once can be attributes).

Example:

name "my-package"
description "A package for demonstration purposes"

dependency "vibe-d" version=">=0.7.13"
dependency "sub-package" version="~master" path="./sub-package"

# command line version
configuration "console" {
	targetType "executable"
	versions "ConsoleApp"
	libs-windows "gdi32" "user32"
}

# Win32 based GUI version
configuration "gui" {
	targetType "executable"
	versions "UseWinMain"
	libs-windows "gdi32" "user32"
}

As much as I dislike XML, I think it is not a good idea to ignore it. XML should definitely be among the supported formats. Also, it would be nice to have a converter between them in the case package owners decide to switch to an alternative.

On Tue, 03 Dec 2013 11:44:43 +0100, Sönke Ludwig wrote:

Am 03.12.2013 10:43, schrieb Dejan Lekic:

As much as I dislike XML, I think it is not a good idea to ignore it. XML should definitely be among the supported formats. Also, it would be nice to have a converter between them in the case package owners decide to switch to an alternative.

I don't know, the purpose of the alternative format discussed here is
supposed to improve human readability (which XML surely doesn't offer).
But on top of that I really think it would be a bad idea to complicate
the system with more formats without a very good reason. JSON should be
universal enough as the standard format for machine data exchange. What
would XML really offer additionally in practice?

Having said that, SDL is structurally more or less the same as XML, so a
generic XML<->SDL converter could be used for this.

I would agree with to a certain degree. But the moment your project becomes complicated, no format will make it readable. You will struggle with any format, especially when you autogenerate (and that is going to happen) DUB JSON. And the more it is close to be machine readable than human readable the higher is the need of a tool that can aid person in altering something. There are thousands of XML tools out there, as you already know. Plus, it is a standard exchange format in many environments. I've seen literally unreadable JSON in many places, and I am 100% sure you have seen it too. DUB JSON files will probably continue being human readable because humands made them, and edit them. :)

On 03/12/2013 11:10, Dejan Lekic wrote:

On Tue, 03 Dec 2013 11:44:43 +0100, Sönke Ludwig wrote:

Am 03.12.2013 10:43, schrieb Dejan Lekic:

As much as I dislike XML, I think it is not a good idea to ignore it. XML should definitely be among the supported formats. Also, it would be nice to have a converter between them in the case package owners decide to switch to an alternative.

I don't know, the purpose of the alternative format discussed here is
supposed to improve human readability (which XML surely doesn't offer).
But on top of that I really think it would be a bad idea to complicate
the system with more formats without a very good reason. JSON should be
universal enough as the standard format for machine data exchange. What
would XML really offer additionally in practice?

Having said that, SDL is structurally more or less the same as XML, so a
generic XML<->SDL converter could be used for this.

I would agree with to a certain degree. But the moment your project becomes complicated, no format will make it readable. You will struggle with any format, especially when you autogenerate (and that is going to happen) DUB JSON. And the more it is close to be machine readable than human readable the higher is the need of a tool that can aid person in altering something. There are thousands of XML tools out there, as you already know. Plus, it is a standard exchange format in many environments. I've seen literally unreadable JSON in many places, and I am 100% sure you have seen it too. DUB JSON files will probably continue being human readable because humands made them, and edit them. :)

I agree with Sonke here, supporting XML would just be an unnecessary
distraction.
No data format is truly unreadable, unless it just used for
machine-to-machine/program-to-program interaction. And even so, there
might be times a human might have to look at it (say, debugging the
communication for example).
Rather, the question is not if it's readable or not, but how readable it
is, how simple and succint the data language is. And it is of value to
have a succint data description language for DUB, since a lot of the
times it will be read and edited by humans.

Plus, JSON is well supported accross a variety of languages:
www.json.org (scroll bellow) , so it's not too far from XML.

On 03/09/2013 01:11 PM, Sönke Ludwig wrote:

JSON

While I think the current JSON based format for the package description is OK, it does have a few drawbacks:

• No support for comments
• Key names must be quoted, although they are just plain identifiers
• Commas between individual fields -> danger of syntax errors for the last field
• The very generic structure makes it easy to learn, but sometimes a bit verbose
• Relatively deep nesting

Looks like CSON (Coffeescript JSON) does address all of the above points.
https://github.com/bevry/cson