Judge my JSON documentation
-
I'm working on a set of projects that use JSON-format files as the data-storage mechanism (because it's easy to parse and tolerable to write by hand as needed). I'm currently engaged in documenting the format/requirements of these files. I'd like some feedback on my style.
Example:File: dungeon_data.json Description: This contains the types of adventure locations and their information. Format: [ { "Name": string //the type of location. Used as a unique key. "Scale": string //this indicates the overall size of the adventure location-- //"large" sites have areas scaled in tens of miles //"medium" sites have areas scaled in miles or thousands of feet //"small" sites have room-size areas (tens or hundreds of feet) "Sizes": [int] //this indicates how many discrete areas are present. //I'd recommend not going above about 5 (a 5-room dungeon) //bigger ones should have multiple locations. "Subtypes": [string] //a list of subtypes that share a common location theme //(wilderness has forests and mountains, for example) "Ages": [string] //how old the adventure location (or the interesting parts anyway) //can be. I recommend using "ancient", "old", and "recent" "HasBoss": float //the decimal percent chance that there's a "boss" monster present (0 < x < 1) "LairChance": {string : float} // keys are the tier of adventure (I use half-integers to represent marginal cases) // values are the decimal percent chance that the entrance to a lair is present. "HasSublocations": bool // can this site have smaller sites embedded in it (usually for large-scale sites) } ]for this file (fragment):
[ { "Name": "wilderness", "Scale": "large", "Sizes": [3,4,5], "Subtypes": [ "hostile", "enchanted", "fey", "barren", "mountains", "planar", "corrupted", "arctic", "forest", "water" ], "Ages": ["old", "recent"], "HasBoss": 0.0, "LairChance": { "1": 0.1, "2": 0.5, "3": 0.6 }, "HasSublocations": true },...Is this sufficient? Is there a better style? Am I stupid and ugly?
-
-
@masonwheeler said in Judge my JSON documentation:
@benjamin-hall said
Judge my JSON documentation
Guilty!
Of being documentation? or of being bad? or of...
Or are we playing Red Queen again?
-
@benjamin-hall I know sockbot uses an extended form of json for configuration which allows replacing certain json syntax elements with whitespace for easier hand-editing, but I don't recall the proper name, the library, or whether it's available for any platform other than node. @sockdevs may be able to help.
-
You cannot use comments in JSON. Not like that, anyway.
I realize that's just documentation, but putting comments in suggests that you can do so, and someone's liable to try.
-
You must not be a real programmer since you're writing documentation
-
@benjamin-hall Having [type] denote an array of types might be easy to miss and confuse with just the type, especially if you have, say, a JSON spec that consists of all arrays for their properties. The only reason I knew what it meant was because there were other properties in that format which lacked the square brackets. Perhaps use something like Array<string> or something a little more explicit?
-
@benjamin-hall said in Judge my JSON documentation:
Or are we playing Red Queen again?
OFF WITH HIS HEADER!
-
It makes sense to me.
However, as @The_Quiet_One says, the array notation might be better like
int[](at least if you're familiar with C-like language declarations) or[int,...](the list nature of the array is fairly explicit here) to make it clearer.
-
I think I'd just align the comments and use a
|to separate code from comments, like this:File: dungeon_data.json Description: This contains the types of adventure locations and their information. JSON: | Description: ------------------------------------------+--------------------------------------------------------------------------------- [ | { | "Name": string, | the type of location. Used as a unique key. | "Scale": string, | this indicates the overall size of the adventure location-- | "large" sites have areas scaled in tens of miles | "medium" sites have areas scaled in miles or thousands of feet | "small" sites have room-size areas (tens or hundreds of feet) | "Sizes": [int], | this indicates how many discrete areas are present. | I'd recommend not going above about 5 (a 5-room dungeon) | bigger ones should have multiple locations. | "Subtypes": [string], | a list of subtypes that share a common location theme | (wilderness has forests and mountains, for example) | "Ages": [string], | how old the adventure location (or the interesting parts anyway) | can be. I recommend using "ancient", "old", and "recent" | "HasBoss": float, | the decimal percent chance that there's a "boss" monster present (0 < x < 1) | "LairChance": {string : float}, | keys are the tier of adventure (I use half-integers to represent marginal cases) | values are the decimal percent chance that the entrance to a lair is present. | "HasSublocations": bool | can this site have smaller sites embedded in it (usually for large-scale sites) } | ] |
-
suggestion: use this
-
@anotherusername said in Judge my JSON documentation:
You cannot use comments in JSON. Not like that, anyway.
I realize that's just documentation, but putting comments in suggests that you can do so, and someone's liable to try.
Here's my unedited
df-ai.jsonthat I'm using right now:{ // true or false: should the AI automatically follow dwarves it thinks are interesting? "camera" : true, // how many job cancellation notices to show. 0: none, 1: some, 2: most, 3: all "cancel_announce" : 1, // site finder options. -1 is "N/A", 0 is the first option, 1 is the second, and so on. "embark_options" : { "Aquifer" : 0, "BottomlessPit" : -1, "Chasm" : -1, "Clay" : -1, "DeepMetal" : 2, "DimensionX" : 8, "DimensionY" : 6, "Drainage" : -1, "Elevation" : -1, "Evil" : -1, "FluxStone" : 1, "MagmaPipe" : -1, "MagmaPool" : -1, "OtherFeatures" : -1, "Rain" : -1, "River" : 1, "Savagery" : -1, "ShallowMetal" : 2, "Soil" : -1, "Temperature" : -1, "UndergroundPool" : -1, "UndergroundRiver" : -1 }, // true or false: should the AI hide the FPS meter when in a menu? (the FPS meter is always hidden in lockstep mode) "fps_meter" : true, // true or false: should the AI make Dwarf Fortress think it's running at 100 simulation ticks, 50 graphical frames per second? this option is most useful when recording as lag will not affect animation speeds in the CMV files. the game will not accept input if this is set to true. does not work in TEXT mode. "lockstep" : true, // the name of a DFHack plugin that manages labors, in quotes, or "" for no automated labor management. "autolabor" and "labormanger" are specifically supported. "manage_labors" : "labormanager", // true or false: should the AI assign administrators in the fortress? "manage_nobles" : true, // true or false: should the AI keep the game running after it loses? "no_quit" : true, // true or false: should the AI use the legacy floor plan generator if it fails to generate a floor plan using blueprints? "plan_allow_legacy" : false, // number from -1 to 3: how much information about the blueprint should the AI write to the log? -1: none, 0: summary, 1: room placement summary, 2: placements that succeeded, 3: placements that failed "plan_verbosity" : 1, // true or false: should the AI automatically pick an embark location? "random_embark" : true, // the name of the region to embark on, between quotes, or "" to generate a new world. "random_embark_world" : "region1", // true or false: should the AI automatically record CMV files while it plays? "record_movie" : false, // 0: pocket, 1: smaller, 2: small, 3: medium, 4: large "world_size" : 2, // true or false: should the AI say what it's thinking in the DFHack console? "write_console" : true, // true or false: should the AI say what it's thinking in df-ai.log? "write_log" : true }
-
@ben_lubar Some parsing libraries fail on comments. Others don't. Formally, they're not allowed.
-
@benjamin-hall said in Judge my JSON documentation:
Formally, they're not allowed.
This. If your parser doesn't barf on comments, it's not following the JSON spec, and you should probably be worried about other stuff -- such as, say, how it would parse
alert("XSS!").And even if it doesn't contain gaping security holes, it's still a really bad habit...
The Inner JSON Effect
Jake eagerly stepped into his new job, grateful for more experience and new challenges, craving to learn new software stacks and see what his new company had to teach him about the world of software. They told him he’d be working on some websites, dealing with JavaScript, Node.js, JSON, and the...
-
@anotherusername That's only if it doesn't barf on comments because it execs it.
If it doesn't barf on comments because it specifically handles them as an extension to the json spec, then it's just doing the world a favor.
-
That looks fiddly to align and maintain. I'd go with the more standard docs above the items.
Also, instead of inventing yet another JSON-with-comments format, why not use yaml? I've been using it for my projects and it's been great. You can go as JSON-like or as python-like as you feel comfortable.
-
@createdtodislikethis said in Judge my JSON documentation:
If it doesn't barf on comments because it specifically handles them as an extension to the json spec, then it's just doing the world a favor.
Yes... teaching programmers bad habits that could bite them later. A "favor".
-
@cartman82 said in Judge my JSON documentation:
That looks fiddly to align and maintain. I'd go with the more standard docs above the items.
Also, instead of inventing yet another JSON-with-comments format, why not use yaml? I've been using it for my projects and it's been great. You can go as JSON-like or as python-like as you feel comfortable.
I'll probably move the comments above the items. I'm not sure why I didn't think of that to begin with...
I'm not too worried about this being valid JSON as it stands, since my target audience will be modifying the files that I provide (without the comments) by hand.
And as for not using YAML:
- I don't know it at all, I know JSON pretty well.
- I'm not familiar with the parsing libraries for JS or C#.
- From what I've seen, it's fiddly with spacing. That annoys me.
-
@anotherusername said in Judge my JSON documentation:
Yes... teaching programmers bad habits that could bite them later. A "favor".
The bad habit of using comments?
The bad habit of disrespecting formats by daring to extend them?
-
Have you given any thought to JSON5? Then you can have trailing commas, comments, and all that lovely goodness.
... and it still looks like JSON.
I have a love-hate relationship with YAML.
-
@julianlam I'm using it in a C# project, does Newtonsoft's parser handle it?
-
-
@julianlam That's C++.
-
@anotherusername said in Judge my JSON documentation:
You cannot use comments in JSON. Not like that, anyway.
I realize that's just documentation, but putting comments in suggests that you can do so, and someone's liable to try.
I don't follow your remark. The file in question is just documentation for the JSON file, it's not JSON itself. If you remove all the comments it still won't be valid JSON.
I thought the comments pretty clear, by the way.
-
@cartman82 YAML is god-awful, and throws up terrible error messages. Plus it's not hip enough - the cool kids now use HOCON
XML or nothing.
-
@coldandtired said in Judge my JSON documentation:
@cartman82 YAML is god-awful, and throws up terrible error messages.
A file format can't produce error messages, terrible or otherwise. Perhaps you're thinking of a specific YAML library?
-
@createdtodislikethis said in Judge my JSON documentation:
The bad habit of disrespecting formats by daring to extend them?
That. Specifically, "extending" them by writing a non-standard version that's incompatible with the standard version, instead of actually extending them by... changing the standard.
If the JSON standard is modified to allow comments, then and only then should you go ahead and use them.
-
@createdtodislikethis said in Judge my JSON documentation:
@anotherusername said in Judge my JSON documentation:
Yes... teaching programmers bad habits that could bite them later. A "favor".
The bad habit of disrespecting formats by daring to extend them?
JSON is designed to be a versatile format that can be used in a myriad of consumers ranging from browsers to servers. If you are encouraging developers to defy a spec, it is bound to cause problems if and when a new consumer is introduced to your software that can't handle it. Data format specs are just something you don't ignore.
-
@coldandtired said in Judge my JSON documentation:
@cartman82 YAML is god-awful, and throws up terrible error messages. Plus it's not hip enough - the cool kids now use HOCON
XML or nothing.
HOCON is good when it's a machine writing it and a human potentially reading it. When it's a human writing it, then the best format is probably TOML. And if both humans and machines are writing it, then you're doing your files wrong.
-
@coldandtired said in Judge my JSON documentation:
@cartman82 YAML is god-awful, and throws up terrible error messages.
No repro in my experience.
I can imagine whitespace aligning can be a bother if you indent too far out. It just hasn't been an issue for me thus far.
-
@pie_flavor said in Judge my JSON documentation:
HOCON is good when it's a machine writing it and a human potentially reading it. When it's a human writing it, then the best format is probably TOML. And if both humans and machines are writing it, then you're doing your files wrong.
Looks like .ini with arrays. Nested objects will be annoying to maintain.
Looks better than ini or env or pure JSON, but not as fancy as yaml.
-
@cartman82 said in Judge my JSON documentation:
@pie_flavor said in Judge my JSON documentation:
HOCON is good when it's a machine writing it and a human potentially reading it. When it's a human writing it, then the best format is probably TOML. And if both humans and machines are writing it, then you're doing your files wrong.
Looks like .ini with arrays. Nested objects will be annoying to maintain.
They're simple enough - just use dots in your sections. If you've designed your config graph such that it's tedious to put it in TOML, then you've probably designed your config graph badly to begin with and should remember that it's a human editing the thing.
Looks better than ini or env or pure JSON, but not as fancy as yaml.
YAML's all right, but there's way too many features and it's far too easy to write or autogenerate something completely incomprehensible to anyone who hasn't read over the spec in-depth. Not to mention the spaces vs tabs nonsense. Bukkit used YAML for data storage, config, and manifests, and if I never have to use it ever again it'll be too soon.
-
@pie_flavor said in Judge my JSON documentation:
HOCON is good when it's a machine writing it and a human potentially reading it. When it's a human writing it, then the best format is probably TOML. And if both humans and machines are writing it, then you're doing your files wrong.
If we're doing semi-obscure formats, I'd like to say I like where RON is going.
On topic:
-
Sizes: it not clear to me whether "I'd recommend not going above about 5" refers to the size of an area or the count of areas. If the former, what would you recommend for the latter, and if the latter what would you recommend for the former? -
HasBoss: should say(0 <= x <= 1)to appease pedants if 0.0 and 1.0 are possible values. -
LairChance: don't use the word "percent" if it's a decimal value like inHasBoss. "Decimal percent" felt ambiguous or even contradictory to me. Better to use(0 <= x <= 1)or(0.0 <= x <= 1.0)like above.
Looking at the example helped a lot.
-
-
@cartman82 said in Judge my JSON documentation:
not as fancy as yaml
You say that as if being fancy is something good.
-
@zecc said in Judge my JSON documentation:
On topic:
-
Sizes: it not clear to me whether "I'd recommend not going above about 5" refers to the size of an area or the count of areas. If the former, what would you recommend for the latter, and if the latter what would you recommend for the former? -
HasBoss: should say(0 <= x <= 1)to appease pedants if 0.0 and 1.0 are possible values. -
LairChance: don't use the word "percent" if it's a decimal value like inHasBoss. "Decimal percent" felt ambiguous or even contradictory to me. Better to use(0 <= x <= 1)or(0.0 <= x <= 1.0)like above.
Looking at the example helped a lot.
Thanks.
Size: well, it doesn't really matter. Truth is, all the values are arbitrary--the code just chooses between them randomly and sticks them in a template. This code builds adventure location seeds--not locations, just gives a randomized choice of conditions. I mean "rooms/discrete areas" by that value; 5 is a good cap because otherwise the areas should probably be split into two locations. The size of an area is given by theScaleparameter--those are descriptive (small, medium, large).I'll change those other ones to be more clear.
-
JSON - Wikipedia
