devblog

doc/devblog/day_410__better_JSON_for_metadata.mdwn

@@ -0,0 +1,33 @@
+I've had to change the output of `git annex metadata --json`.
+The old output looked like this:
+
+	{"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true}
+
+That was not good, because it didn't separate the metadata fields
+from the rest of the JSON object. What if a metadata field is named
+"note" or "success"? It would collide with the other "note" and "success"
+in the JSON.
+
+So, changed this to a new format, which moves the metadata fields into
+a "fields" object:
+
+	{"command":"metadata","file":"foo","key":"...","fields":{"author":["bar"],...},"note":"...","success":true}
+
+I don't like breaking backwards compatability of JSON output, but in this
+case I could see no real alternative. I don't know if anyone
+is using `metadata --batch` anyway. If you are and this will cause a
+problem, get in touch.
+
+----
+
+While making that change, I also improved the JSON outputlayer, so it can
+use Aeson. I didn't switch exclusively to using Aeson, because git-annex
+commands with JSON output often output it incrementally as they go (which
+Aeson can't really do), and are anyway not often doing the kind of
+serialization of data type that Aeson excells at.
+
+This let me use Aeson to generate the "fields" object for `metadata
+--json`. And it was also easy enough to use Aeson to parse the output of
+that command (and some simplified forms of it).
+
+So, I've laid the groundwork for `git annex metadata --batch` today.