doc: add guidance for CLI cmds that output JSON

Signed-off-by: Christian Hopps <chopps@labn.net>

diff --git a/doc/developer/cli.rst b/doc/developer/cli.rst
index d51f06d118f8debf14ecd974d747190232da8ba4..5d1dda06dfcea1a9f5546910991ee250d884ba58 100644 (file)
--- a/doc/developer/cli.rst
+++ b/doc/developer/cli.rst
@@ -106,6 +106,11 @@ convention. Please do not scatter individual CLI commands in the middle of
 source files; instead expose the necessary functions in a header and place the
 command definition in a ``*_vty.[ch]`` file.
 
+.. note::
+
+   Please see :ref:`cli-workflow` for requirements when creating CLI commands
+   (e.g., JSON structure and formatting).
+
 Definition Grammar
 ^^^^^^^^^^^^^^^^^^
 FRR uses its own grammar for defining CLI commands. The grammar draws from

diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst
index b0d320b5eaf4c045b718621cbdae40a08a3a4510..06a2ccbc0aae9a7df69372d92f5267bfad8ad06d 100644 (file)
--- a/doc/developer/workflow.rst
+++ b/doc/developer/workflow.rst
@@ -1308,6 +1308,8 @@ is to correctly set up `LD_LIBRARY_PATH` so that libraries from the build tree
 are used.  (On some systems, `libtool` is also available from PATH, but this is
 not always the case.)
 
+.. _cli-workflow:
+
 CLI changes
 -----------
 
@@ -1374,9 +1376,23 @@ the development mailing list / public Slack instance.
 JSON Output
 ^^^^^^^^^^^
 
-* All JSON keys are to be camelCased, with no spaces
+New JSON output in FRR needs to be backed by schema, in particular a YANG model.
+When adding new JSON, first search for an existing YANG model, either in FRR or
+a standard model (e.g., IETF) and use that model as the basis for any JSON
+structure and *especially* for key names and canonical values formats.
+
+If no YANG model exists to support the JSON then an FRR YANG model needs to be
+added to or created to support the JSON format.
+
+* All JSON keys are to be ``camelCased``, with no spaces. YANG modules almost
+  always use ``kebab-case`` (i.e., all lower case with hyphens to separate
+  words), so these identifiers need to be mapped to ``camelCase`` by removing
+  the hyphen (or symbol) and capitalizing the following letter, for
+  example "router-id" becomes "routerId"
 * Commands which output JSON should produce ``{}`` if they have nothing to
   display
+* In general JSON commands include a ``json`` keyword typically at the end of
+  the CLI command (e.g., ``show ip ospf json``)
 
 Use of const
 ^^^^^^^^^^^^