JSON has three major problems: it does not allow comments, it is hard to read, and it is very strict with things like trailing commas and quotes, making it much harder to write by humans. Since JSON is almost a perfect subset of YAML, I would like to propose that we start using YAML for things like template parameter documentation, graphs, on-wiki configuration. and other "JSON as wiki markup" places. See more examples below.
Note that internally we may still process all the data as JSON, e.g. if it needs to be available to JavaScript clients, or stored in the page properties.
== `<graph>` Vega JS "JSON programming language"
[[ https://en.wikipedia.org/wiki/Template:Graph:Street_map_with_marks | example1 ]] or [[ https://en.wikipedia.org/wiki/Template:Graph:Most_Expensive_Cars | example2 ]] (scroll down to the <graph> section) - we already use the HHVM's non-standard JSON parsing for comments, lenient trailing commas, and multiline strings autoconversion to `\n`.
```lang=json, counterexample, name=JSON
{
// Create a dataset that indicates which cars are visible and should drive the domain of the scales.
"name": "visible-cars",
"source": "cars",
"transform": [
{
"type": "filter",
"test": "datum['Adjusted price'] >= selectedPrice"
},
{
"type": "filter",
"test": "if(selectedPriceType == 'greater', true, if (selectedPrice == 0, if(datum.bin_start==0 & datum['Adjusted price'] < 5000000, true, false), if (selectedPrice == 5000000, if(datum.bin_start==0 & datum['Adjusted price'] >= 5000000, true, false), if(selectedPrice == datum.bin_start, true, false))))"
}
]
},
```
```lang=yaml, name=YAML
# Create a dataset that indicates which cars are visible and should drive the domain of the scales.
- name: visible-cars
source: cars
transform:
- type: filter
test: datum['Adjusted price'] >= selectedPrice
- type: filter
test: >
if (selectedPriceType == 'greater', true,
if (selectedPrice == 0,
if (datum.bin_start == 0 & datum['Adjusted price'] < 5000000, true, false),
if (selectedPrice == 5000000,
if (datum.bin_start == 0 & datum['Adjusted price'] >= 5000000, true, false),
if (selectedPrice == datum.bin_start, true, false)
)))
```
== JSON as a template parameter
JSON is sometimes useful as a parameter for a template that contains a graph, e.g. [[ https://en.wikipedia.org/wiki/Template:Graph:Street_map_with_marks | this template ]]:
```lang=json, counterexample, name=JSON
{{ Graph:Street map with marks | lat=37.8 | lon=-122.4 | zoom=9 |
{"lat":37.8, "lon":-122.4, "img":"wikirawupload:{{filepath:Volcano red 32x32.svg|32}}", "width":25, "height": 25, "offsetY":-10, "text": "Volcano", "textFontWeight": "bold", "textFontSize": 20, "textColor": "#00f"}
}}
```
```lang=yaml, name=YAML
{{ Graph:Street map with marks | lat=37.8 | lon=-122.4 | zoom=9 |
lat: 37.8
lon: -122.4
img: wikirawupload:{{filepath:Volcano red 32x32.svg|32}}
width: 25
height: 25
offsetY: -10
text: Volcano
textFontWeight: bold
textFontSize: 20
textColor: "#00f"
}}
```
== SPARQL query as a single string for Kartographer
[[ https://en.wikipedia.beta.wmflabs.org/wiki/Maplink | Map example ]], while much better than the original URL encoded [[ https://en.wikipedia.org/wiki/User:Yurik/maplink | example ]], is still a major pain to write because one has to be very careful of quote escaping. Also requires non-standard (multi-line) JSON parsing.
```lang=json, counterexample, name=JSON
<maplink latitude="52.16" longitude="-112.15" zoom="3" width="800" height="500" text="Governors of US states with their party affiliation">
{
"type":"ExternalData",
"service": "geoshape",
"query": "SELECT ?id ?head
(SAMPLE(?img) as ?img)
(SAMPLE(?fill) as ?fill)
(concat('[[', substr(str(?link),31,100), ' | ', ?headLabel, ']]') as ?title)
...
```
```lang=yaml, name=YAML
<maplink latitude="52.16" longitude="-112.15" zoom="3" width="800" height="500" text="Governors of US states with their party affiliation">
type: ExternalData
service: geoshape
query: >
SELECT ?id ?head
(SAMPLE(?img) as ?img)
(SAMPLE(?fill) as ?fill)
(concat('[[', substr(str(?link),31,100), ' | ', ?headLabel, ']]') as ?title)
```
== Zero configuration
Zero team had tons of issues with configuring Zero with keeping the trailing commas and lack of comments at first, but with the non-standard JSON it has gotten better. YAML-style would help, but building a full-blown interface might have been considerably more effort
== Event logging schema
[[ https://meta.wikimedia.org/wiki/Schema:Kartographer | our event schema ]] - the "action" field (enum) is horribly documented because there is a disjoint between the enum values and their description, and it doesn't allow even JSON comments (event schema reformats json on save). Editing that doc is also painful because the `\n` are not that readable.