JSON Convert — turn arbitrary JSON into tiddlers, with reusable profiles and a staging step
I’ve been working on a plugin for the case where the core JSON importer falls short: source JSON whose shape doesn’t already match TiddlyWiki’s tiddler shape, or fields that aren’t strings. Inspired directly by this thread — the Moodle imports pain points there were the motivating example.
Demo wiki: https://crosseye.github.io/TW5-JSON_Convert/
Source: https://github.com/crosseye/TW5-JSON_Convert
What it does
You write a small JSON document — a profile — that describes how each record in your source JSON maps onto a tiddler. You can do this manually or with the tool supplied. Paste the source into the Console, pick a profile, hit ‘‘Convert’’. The results land in a preview area where you can resolve title collisions (skip / overwrite / rename) before committing.
A profile looks like this:
{
"records": "{{books[*]}}",
"tw-fields": {
"title": "{{author}}: {{title}}",
"tags": "Book {{genre|split-commas}}"
},
"custom-fields": {
"year": "{{year}}",
"categoory": "{{group|to-title-case}}"
}
}
recordsis a path to the array you want to iterate — one tiddler per element. It supports nested iteration like{{groups[*].subgroups[*].items[*]}}, and bindings can use../to reach an enclosing scope.tw-fieldsandcustom-fieldsare bindings — template strings with{{path}}tokens that resolve against the current record. Numbers, booleans, and nested objects are coerced rather than dropped.- Tokens can pipe through transforms:
{{title|to-lower-case|slugify}}. The plugin ships a handful (html-to-wikitext,split-commas,split-to-titles,timestamp-to-date,to-upper-case,to-lower-case,to-title-case,slugify) and you can drop in your own as tiddlers tagged$:/tags/json-convert/transform— JavaScript bodies for arbitrary logic, or wikitext bodies for filter-operator chains.
There’s a form-based editor for profiles with a Browse modal that walks the parsed JSON’s shape and inserts paths on click, and the parser tolerates BOMs and stray non-JSON wrapping (the noisy Moodle exports from the inspiration thread parse cleanly with a recoverable warning).
Try it
The demo wiki ships six sample profiles with matching data tiddlers (Moodle quiz, Moodle forum, music library two ways, reading list, trip itinerary). Click the {} icon in the page-controls toolbar to open the Console.
To install in your own wiki, drag $:/plugins/crosseye/json-convert from the demo wiki onto yours and save.
Documentation
An end-to-end walkthrough, the profile schema, path expressions, transforms, recipes, and reference all live in a single tiddler in the plugin: Usage guide.
JSON Mangler Contrast
Joshua Fontany’s JSON Mangler and JSON Convert work on opposite ends of the JSON-meets-TiddlyWiki problem and complement rather than compete. JSON Mangler extends what you can do with JSON that already lives in your wiki as a JSON-typed data tiddler — text references reach into nested values, new filter operators (indexes[] , hasindex[] , encodeindex[] , comparefield[] , etc.) walk and sort nested structures, a $jsonmangler widget edits JSON tiddlers in place, and there’s even CSV support and a Plugin Management UI in the Control Panel.
JSON Convert, by contrast, doesn’t touch the JSON-tiddler shape at all: it’s an importer that takes arbitrary external JSON (an LMS export, an API response, a config dump) and writes ordinary tiddlers based on a reusable mapping profile, with a staging step to preview and resolve collisions before committing.
So if you have a JSON-shaped knowledge base inside TiddlyWiki and want better tools to query and edit it, reach for JSON Mangler; if you have a chunk of foreign JSON and want each record to become its own first-class tiddler with the field names you choose, reach for JSON Convert.
Feedback
This was a little itch I had to scratch, not a big idea; it’s simply a grown-up version of what I did a year ago. It’s also something I don’t expect to use a lot myself, as I have other regular workflows that I use to convert JSON before importing. But I do expect to update and maintain this, so long as doing so doesn’t become too burdensome.
Bug reports, feature requests, design objections, “have you considered X?” — all welcome, here or on the issue tracker. This is at 0.9.2 and the API is approaching stability but not frozen.
