From 49e0f1dc6e52e791f5e0ba21097aea17d5950d38 Mon Sep 17 00:00:00 2001
From: Phil Sutter <phil@nwl.cc>
Date: Wed, 29 Aug 2018 16:23:28 +0200
Subject: JSON: Add metainfo object to all output

Right now this object merely contains the nftables version and release
name as well as a JSON schema version, but it could be extended
arbitrarily. In the future, this will also allow for non-compatible
schema changes should the need for this arise.

Adjust the parser to accept metainfo objects and make it verify
json_schema_version to be less than or equal to the one hard-coded in
the library.

Signed-off-by: Phil Sutter <phil@nwl.cc>
Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
---
 doc/libnftables-json.adoc | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

(limited to 'doc/libnftables-json.adoc')

diff --git a/doc/libnftables-json.adoc b/doc/libnftables-json.adoc
index c174a354..59bac17f 100644
--- a/doc/libnftables-json.adoc
+++ b/doc/libnftables-json.adoc
@@ -16,13 +16,14 @@ libnftables-json - Supported JSON schema by libnftables
 
 'CMD_OBJECTS' := 'CMD_OBJECT' [ *,* 'CMD_OBJECTS' ]
 
-'CMD_OBJECT' := *{* 'CMD'*:* 'LIST_OBJECT' *}*
+'CMD_OBJECT' := *{* 'CMD'*:* 'LIST_OBJECT' *}* | 'METAINFO_OBJECT'
 
 'CMD' := *"add"* | *"replace"* | *"create"* | *"insert"* | *"delete"* |
          *"list"* | *"reset"* | *"flush"* | *"rename"*
 
 'LIST_OBJECT' := 'TABLE' | 'CHAIN' | 'RULE' | 'SET' | 'MAP' | 'ELEMENT' |
-		 'FLOWTABLE' | 'COUNTER' | 'QUOTA' | 'CT_HELPER' | 'LIMIT'
+		 'FLOWTABLE' | 'COUNTER' | 'QUOTA' | 'CT_HELPER' | 'LIMIT' |
+		 'METAINFO_OBJECT'
 
 == DESCRIPTION
 libnftables supports JSON formatted input and output. This is implemented as an
@@ -47,6 +48,26 @@ It's value is a ruleset element - basically identical to output elements apart
 from certain properties which may be interpreted differently or are required
 when output generally omits them.
 
+== METAINFO OBJECT
+In output, the first object in *nftables* array is a special one containing
+library information. Its content is as follows:
+
+[verse]
+*{ "metainfo": {
+	"version":* 'STRING'*,
+	"release_name":* 'STRING'*,
+	"json_schema_version":* 'NUMBER'
+*}}*
+
+The values of *version* and *release_name* properties are equal to the package
+version and release name as printed by *nft -v*. The value of
+*json_schema_version* property is an integer indicating the schema version.
+
+If supplied in library input, the parser will verify *json_schema_version* value
+to not exceed the internally hardcoded one (to make sure the given schema is
+fully understood). In future, a lower number than the internal one may activate
+compatibility mode to parse outdated and incompatible JSON input.
+
 == COMMAND OBJECTS
 The structure accepts an arbitrary amount of commands which are interpreted in
 order of appearance. For instance, the following standard syntax input:
-- 
cgit v1.2.3

