From b44b66c7bf050d80069ae0a5dc61e088a897cab9 Mon Sep 17 00:00:00 2001 From: Christian Hopps Date: Tue, 3 Jan 2023 07:22:28 -0500 Subject: [PATCH] doc: add guidance for CLI cmds that output JSON Signed-off-by: Christian Hopps --- doc/developer/cli.rst | 5 +++++ doc/developer/workflow.rst | 18 +++++++++++++++++- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/doc/developer/cli.rst b/doc/developer/cli.rst index d51f06d118..5d1dda06df 100644 --- 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 b0d320b5ea..06a2ccbc0a 100644 --- 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 ^^^^^^^^^^^^ -- 2.39.5