Update raddb/mods-available/json

diff --git a/raddb/mods-available/json b/raddb/mods-available/json
index cfe71c0f6ba8d44405e8fc420e7b74420420fd86..434fdba4feebc0b07f7119b2af59d58ca412da2b 100644 (file)
--- a/raddb/mods-available/json
+++ b/raddb/mods-available/json
@@ -1,51 +1,84 @@
 # -*- text -*-
 #
+#  :toc:
+#
 #  $Id$
 #
-# JSON module registers a map function to allow mapping fields from JSON
-# structures to attributes.
+
+#######################################################################
 #
-# The path through the JSON document's tree is specified with FR jpath,
-# which is the FreeRADIUS implementation of the jpath grammar described here:
+#  = JSON Module
 #
-#        http://goessner.net/articles/JsonPath/
+# The `json` module registers a `map` function to allow mapping fields
+# from JSON structures to attributes.
+#
+# The path through the JSON document's tree is specified with FR jpath,
+# which is the FreeRADIUS implementation of the jpath grammar described
+# at http://goessner.net/articles/JsonPath/
 #
 # Selectors currently implemented are:
-#   - $                         Root node (only valid at the start of the path).
-#   - @                         Current node (only valid at the start of the path).
-#   - .<name>                   A field within an object.
-#   - [<idx>]                   Index within an array.
-#   - [<start>:<end>[:<step>]]  A slice within an array (identical to the Python syntax).
-#   - [<idx>,<start>:<end>]     Multiple indexes/slices within an array.
-#   - .*                        All the children of the current node.
-#   - ..                        Recursive descent.
-#
-# Automatic casting will occur between JSON and attribute types where possible.
-#
-# Assignment of JSON objects/arrays to strings is supported, in which case the
-# JSON serialized form of the object/array is used.
-#
-# If a jpath matches multiple nodes, unless the map includes the += operator
-# only the first node's value will be used.
-# If the map uses += then multiple instances of the attribute will be created,
-# each holding a different node value.
-#
-# Simple example:
-# {
-#      "user": "bob",
-#      "account number": 7124503,
-#      "groups": {
-#              "admin",
-#              "networks",
-#              "bob"
-#      }
 #
+# [options="header,autowidth"]
+# |===
+# | Selector                 | Description
+# | $                        | Root node (only valid at the start of the path).
+# | @                        | Current node (only valid at the start of the path).
+# | .<name>                  | A field within an object.
+# | [<idx>]                  | Index within an array.
+# | [<start>:<end>[:<step>]] | A slice within an array (identical to the Python syntax).
+# | [<idx>,<start>:<end>]    | Multiple indexes/slices within an array.
+# | .*                       | All the children of the current node.
+# | ..                       | Recursive descent.
+# |===
+#
+# [NOTE]
+# ====
+# * Automatic casting will occur between JSON and attribute types where possible.
+# * Assignment of JSON objects/arrays to strings is supported, in which case the
+#   JSON serialized form of the object/array is used.
+# * If a jpath matches multiple nodes, unless the map includes the `+=` operator
+# * only the first node's value will be used.
+# * If the map uses `+=` then multiple instances of the attribute will be created,
+#   each holding a different node value.
+# ====
+#
+
+#
+# ## Sample
+#
+# Assuming that you have the url http://example.org/api/user/$username
+# service replying some JSON content as below.
+#
+# [source, json]
+# ----
+# {
+#   "user": "bob",
+#   "account number": 7124503,
+#     "groups": {
+#       "admin",
+#       "networks",
+#       "bob"
+#     }
+#   }
 # }
+# ----
 #
+# Then, you can call using the module `rest` and access the JSON fields as below example.
+#
+# [source, unlang]
+# ----
 # map json "%{rest:GET http://example.org/api/user/%{User-Name}" {
-#      &Tmp-Integer-0  := '$.account number'
-#      &Group          += '$.groups.*"
+#   &Tmp-Integer-0  := '$.account number'
+#   &Group          += '$.groups.*'
 # }
+# ----
+#
+
+#
+# ## Default instance
+#
+# This module takes no configuration.
+#
 json {
 
 }