Cherry-pick JSON docs improvements from #6522

editions/tw5.com/tiddlers/concepts/DataTiddlers.tid

@@ -1,7 +1,8 @@
-created: 201308291647
+created: 20130829164700000
-modified: 201308291647
+modified: 20220427171321793
 tags: Concepts
 title: DataTiddlers
+type: text/vnd.tiddlywiki
 
 A data tiddler is a miniature database contained within a tiddler.
 
@@ -12,22 +13,4 @@ There are two standard formats:
 
 Other formats of tiddler can also be parsed to yield blocks of data that behave like data tiddlers.
 
-Use a TextReference to look up the value of a named property. For example, if a [[DictionaryTiddler|DictionaryTiddlers]] called `MonthDays` contains:
+See [[JSON in TiddlyWiki]] for an overview.
-
-```
-oct:31
-nov:30
-dec:31
-```
-
-... then `{{MonthDays##nov}}` will resolve to the value `30`.
-
-The same is true if `MonthDays` is a [[JSONTiddler|JSONTiddlers]] with the following content:
-
-```
-{"oct":31,"nov":30,"dec":31}
-```
-
-Note: //It is currently only possible to retrieve data from the immediate properties of the root object of a JSONTiddler.//
-
-The widgets ActionSetFieldWidget and ActionListopsWidget can manipulate named properties of data tiddlers by indicating the name of the property in the $index attribute. To create or modify a named property with ActionSetFieldWidget, provide a $value attribute. To delete a named property with ActionSetFieldWidget, omit the $value attribute. ActionListopsWidget assigns the named property the list constructed through its $filter and $subfilter attributes.

editions/tw5.com/tiddlers/concepts/DictionaryTiddlers.tid

@@ -1,9 +1,10 @@
 created: 20141228094500000
-modified: 20180305111822713
+modified: 20220427171020974
 tags: Concepts
 title: DictionaryTiddlers
+type: text/vnd.tiddlywiki
 
-A dictionary tiddler is a [[data tiddler|DataTiddlers]] containing a simple list of `name: value` pairs.
+A dictionary tiddler is a kind of [[data tiddler|DataTiddlers]] that contains a simple list of `name: value` pairs.
 
 Its [[ContentType]] is `application/x-tiddler-dictionary`.
 

editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid

@@ -1,10 +1,11 @@
 created: 20141228094500000
-modified: 20150221152956000
+modified: 20220427171219408
 tags: Concepts
 title: JSONTiddlers
+type: text/vnd.tiddlywiki
 
-A JSON tiddler is a [[data tiddler|DataTiddlers]] containing a [[JSON|JavaScript Object Notation]] structure in its `text` field.
+A JSON tiddler is a [[data tiddler|DataTiddlers]] containing a [[JSON|JavaScript Object Notation]] structure in its `text` field. See [[JSON in TiddlyWiki]] for an overview.
 
 Its [[ContentType]] is `application/json`.
 
-The [[history list|$:/HistoryList]] is a good example of a JSON tiddler.
+The [[history list|$:/HistoryList]] is an of a JSON tiddler.

editions/tw5.com/tiddlers/definitions/JavaScript Object Notation.tid

@@ -1,11 +1,7 @@
 created: 20150221152904000
-modified: 20150221181720000
+modified: 20220427170920772
 tags: Definitions
 title: JavaScript Object Notation
 type: text/vnd.tiddlywiki
 
-<<.dlink-ex JSON "https://en.wikipedia.org/wiki/JSON">> is a standard plain-text format used for modelling hierarchical structures of objects that contain named fields.
+<<.dlink-ex JSON "https://en.wikipedia.org/wiki/JSON">> is a standard plain-text format used for modelling hierarchical structures of objects that contain named fields. See [[JSON in TiddlyWiki]] for an overview.
-
-DataTiddlers can have JSON content.
-
-The <<.mlink jsontiddlers>> macro returns tiddler content in JSON format.

editions/tw5.com/tiddlers/features/JSON in TiddlyWiki.tid

@@ -0,0 +1,69 @@
+title: JSON in TiddlyWiki
+tags: Features
+type: text/vnd.tiddlywiki
+created: 20220427174702859
+modified: 20220427174702859
+
+!! Introduction
+
+JSON (~JavaScript Object Notation) is a standardised text representation for data structures that is widely used for the storage and transfer of data.
+
+JSON is used in several different contexts in TiddlyWiki. For example:
+
+* Tiddlers are represented as JSON data within TiddlyWiki HTML files
+* Groups of tiddlers can be [[exported|How to export tiddlers]] and [[imported|Importing Tiddlers]] as JSON files
+* Plugin tiddlers store their constituent shadow tiddlers as JSON data
+* The client-server configuration uses [[JSON messages|TiddlyWeb JSON tiddler format]] to communicate between the client and the server
+* Arbitrary JSON data within DataTiddlers can be processed and manipulated using a set of filter operators and action widgets
+
+!! About JSON
+
+The technical description of JSON at the official website https://json.org/ is terse. Here we summarise the main features.
+
+JSON supports two basic data structures:
+
+''Arrays'' are lists of items. The items are identified by their numeric index (starting at zero)
+
+An example of an array is:
+
+```json
+["one","two","three\"four"]
+```
+
+Note the following features of arrays:
+
+* The array is signified by square brackets surrounding the list of items
+* Each item is a string in double quotes. Double quotes can be included within the strings by preceding them with a backslash (`\`)
+* The items are separated by commas
+
+''Objects'' are collections of name/value pairs. Each item is a value that is identified by a unique name
+
+An example of an object is:
+
+```json
+{
+  "first": "This is the first value",
+  "second": "This is the second value",
+  "third": "This is the third value"
+}
+```
+
+Note the following features of objects:
+
+* The object is signified by curly braces surrounding the list of name/value pairs
+* Each name/value pair consists of the name in double quotes, a colon, and then the value
+* The name/value pairs are separated by commas
+
+The examples above all show string values. JSON actually supports several different types of value. Any of these types can be used as a value:
+
+* String values, as shown above
+* Numeric values, represented as signed decimals such as `1`, `3.14`. Exponential notation can also be used e.g. `-1E10`
+* Boolean values, represented by the keywords `true` and `false`
+* The special value `null`, which is often used to represent data that is missing or incomplete
+* Objects and arrays are also values, allowing complex nested structures to be represented
+
+!! Working with Data Tiddlers
+
+* [[Reading data from JSON tiddlers]]
+* [[Constructing JSON tiddlers]]
+* [[Modifying JSON tiddlers]]

editions/tw5.com/tiddlers/howtos/Constructing JSON tiddlers.tid

@@ -0,0 +1,16 @@
+title: Constructing JSON tiddlers
+tags: [[JSON in TiddlyWiki]] [[Learning]]
+created: 20220427174702859
+modified: 20220427174702859
+
+See [[JSON in TiddlyWiki]] for an overview of using JSON in TiddlyWiki.
+
+JSON data is just plain text, and so there are an wide variety of techniques to generate it in wikitext.
+
+At a high level, we have several ways to generate JSON data in TiddlyWiki's own tiddler format:
+
+* JSONTiddlerWidget
+* [[jsontiddler Macro]]
+* [[jsontiddlers Macro]]
+
+When constructing JSON data manually, the [[jsonstringify Operator]] is needed to ensure that any special characters are properly escaped.

editions/tw5.com/tiddlers/howtos/Modifying JSON tiddlers.tid

@@ -0,0 +1,18 @@
+created: 20220427174702859
+modified: 20220427171707459
+tags: [[JSON in TiddlyWiki]] Learning
+title: Modifying JSON tiddlers
+type: text/vnd.tiddlywiki
+
+See [[JSON in TiddlyWiki]] for an overview of using JSON in TiddlyWiki.
+
+Note that 
+
+!! Using ActionSetFieldWidget and ActionListopsWidget
+
+The widgets ActionSetFieldWidget and ActionListopsWidget can manipulate named properties of data tiddlers by indicating the name of the property in the $index attribute.
+
+* To create or modify a named property with ActionSetFieldWidget, provide a $value attribute
+* To delete a named property with ActionSetFieldWidget, omit the $value attribute.
+
+ActionListopsWidget assigns the named property the list constructed through its $filter and $subfilter attributes.

editions/tw5.com/tiddlers/howtos/Reading data from JSON tiddlers.tid

@@ -0,0 +1,25 @@
+created: 20220427174702859
+modified: 20220427171449102
+tags: [[JSON in TiddlyWiki]] Learning
+title: Reading data from JSON tiddlers
+type: text/vnd.tiddlywiki
+
+See [[JSON in TiddlyWiki]] for an overview of using JSON in TiddlyWiki.
+
+!! Text References for Accessing JSON Data
+
+[[Text references|TextReference]] are a simple shortcut syntax to look up the value of a named property. For example, if a [[DictionaryTiddler|DictionaryTiddlers]] called `MonthDays` contains:
+
+```
+oct:31
+nov:30
+dec:31
+```
+
+... then `{{MonthDays##nov}}` will resolve to the value `30`.
+
+The same is true if `MonthDays` is a [[JSONTiddler|JSONTiddlers]] with the following content:
+
+```
+{"oct":31,"nov":30,"dec":31}
+```

editions/tw5.com/tiddlers/macros/JsonTiddlersMacro.tid

@@ -1,11 +1,11 @@
+caption: jsontiddlers
 created: 20150221152226000
-modified: 20200204135513721
+modified: 20220427171155184
 tags: Macros [[Core Macros]]
 title: jsontiddlers Macro
 type: text/vnd.tiddlywiki
-caption: jsontiddlers
 
-The <<.def jsontiddlers>> [[macro|Macros]] returns the fields of a [[selection of tiddlers|Title Selection]] in [[JSON|JavaScript Object Notation]] form.
+The <<.def jsontiddlers>> [[macro|Macros]] returns the fields of a [[selection of tiddlers|Title Selection]] in [[JSON|JavaScript Object Notation]] form. See [[JSON in TiddlyWiki]] for an overview.
 
 An example can be seen in the [[template tiddler for JSON exports|$:/core/templates/exporters/JsonFile]].
 

editions/tw5.com/tiddlers/macros/jsontiddler Macro.tid

@@ -1,11 +1,11 @@
 caption: jsontiddler
 created: 20170317140130417
-modified: 20170317140226040
+modified: 20220427171228844
 tags: Macros [[Core Macros]]
 title: jsontiddler Macro
 type: text/vnd.tiddlywiki
 
-The <<.def jsontiddler>> [[macro|Macros]] returns the fields of a single tiddler in [[JSON|JavaScript Object Notation]] form.
+The <<.def jsontiddler>> [[macro|Macros]] returns the fields of a single tiddler in [[JSON|JavaScript Object Notation]] form. See [[JSON in TiddlyWiki]] for an overview.
 
 !! Parameters
 

editions/tw5.com/tiddlers/widgets/JSONTiddlerWidget.tid

@@ -1,14 +1,15 @@
-title: JSONTiddlerWidget
-created: 20210630100923398
-modified: 20210630100923398
-tags: Widgets
 caption: jsontiddler
+created: 20210630100923398
+modified: 20220427171128693
+tags: Widgets
+title: JSONTiddlerWidget
+type: text/vnd.tiddlywiki
 
 ! Introduction
 
 The jsontiddler widget renders the fields of a tiddler to display as a JSON object. The fields of the tiddler can be customised or excluded.
 
-The jsontiddler widget is used in system templates to generate JSON representations of tiddlers for saving.
+The jsontiddler widget is used in system templates to generate JSON representations of tiddlers for saving. See [[JSON in TiddlyWiki]] for an overview.
 
 ! Content and Attributes