NetJSON - Revision history

Al at 23:55, 1 September 2015

2015-09-01T23:55:49Z

Al at 23:34, 1 September 2015

2015-09-01T23:34:30Z

Al at 15:33, 26 August 2015

2015-08-26T15:33:44Z

Al: /* Is this some kind of new [wikipedia:SNMP|SNMP]? */

2015-05-12T05:14:37Z

‎Is this some kind of new [wikipedia:SNMP|SNMP]?

Al at 04:57, 12 May 2015

2015-05-12T04:57:42Z

Al at 04:42, 12 May 2015

2015-05-12T04:42:20Z

Al: Created page with "= NetJSON: data interchange format for networks = .. image:: https://raw.githubusercontent.com/interop-dev/json-for-networks/master/static/netjson-logo.png NetJSON is a data..."

2015-05-11T18:57:13Z

Created page with "= NetJSON: data interchange format for networks = .. image:: https://raw.githubusercontent.com/interop-dev/json-for-networks/master/static/netjson-logo.png NetJSON is a data..."

New page

= NetJSON: data interchange format for networks =

.. image:: https://raw.githubusercontent.com/interop-dev/json-for-networks/master/static/netjson-logo.png

NetJSON is a data interchange format for encoding the basic building blocks of networking:

* <code>devices <https://github.com/interop-dev/json-for-networks#network-device-configuration></code>__
* <code>monitoring data <https://github.com/interop-dev/json-for-networks#device-monitoring-data></code>__
* <code>routes <https://github.com/interop-dev/json-for-networks#network-routes></code>__
* <code>network topology <https://github.com/interop-dev/json-for-networks#network-graph></code>__

<code>Reach us on the Mailing List</code>_ - <code>Consult the ML Archives</code>_

.. ''Reach us on the Mailing List: https://lists.funkfeuer.at/mailman/listinfo/interop-dev .. ''Consult the ML Archives: https://lists.funkfeuer.at/pipermail/interop-dev/

== Goals ==

Define simple JSON data structures that contain the lowest common denominator of:

* network device configurations
* monitoring data extracted from devices
* routes of a routing protocol

The resulting JSON structures should follow these general principles:

* <code>KISS</code>_: keep it simple, proceed one step at time
* <code>Principle of least astonishment</code>_: use accepted terminology
* '''Explicit names''': prefer verbose explicit names, eg: "operating_system" is better than "os"

Once we get to a first version, we should implement these formats in software like:

* Firwmares and linux modules
* Routing protocols
* Monitoring agents
* Node databases
* Monitoring tools

.. ''KISS: http://en.wikipedia.org/wiki/KISS''principle .. ''Principle of least astonishment: http://en.wikipedia.org/wiki/Principle''of_least_astonishment

== Motivations ==

Developing software that deals with networks is harder than it should.

Developers have to take into account all the differences between vendors, operating systems, routing protocols, hardware and (when working with community networks) with the different approaches of each community.

Very often, each vendor develops an entire stack that works exclusively with its own hardware and software.

There exist many libraries and web apps for networking, but it is very hard to make them interoperable, that is, making them talk and understand one another with minimum effort.

Instead of creating an ecosystem, we have been creating silos that hardly talk to each other.

This is an attempt to invert this trend, following the successful example of the <code>GeoJSON</code>_ open standard.

By defining common data structures we can allow developers to focus on their goals instead of having to struggle with the differences of each vendor, firmware, routing protocol or community.

Moreover, we will lay the groundwork for an '''ecosystem''' to grow organically: once the standard JSON structures are defined and adopted it will be easier to write systems that work together, instead of creating silos.

.. _GeoJSON: http://en.wikipedia.org/wiki/GeoJSON

== Definitions ==

* JavaScript Object Notation (JSON), and the terms object, name, value, array, and number, are defined in <code>IETF RTC 4627</code>_.
* The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <code>IETF RFC 2119</code>_.

.. ''IETF RTC 4627: http://www.ietf.org/rfc/rfc4627.txt .. ''IETF RFC 2119: http://www.ietf.org/rfc/rfc2119.txt

= Network Device Configuration =

'''Definition''': configuration and properties of a network device.

'''Example''': <code>device-configuration.json</code>_

A <code>Network Device Configuration</code> object must have a member with the name <code>type</code> and value <code>DeviceConfiguration</code>.

The object should be composed of the following members:

* <code>general</code>
* <code>hardware</code>
* <code>operating_system</code>
* <code>resources</code>
* <code>interfaces</code>
* <code>physical_devices</code>
* <code>routing</code>
* <code>dns_servers</code>
* <code>dns_search</code>

All the values of each member must be objects which further describe each component of a network device.

'''Each object will be described more in detail in the future iterations of this project'''.

Software providing this JSON format to should return all the information it is able to access from the system, according to security and privacy rules defined by the device owner or network administrator.

Software consuming this JSON format must be able to handle missing attributes.

Software consuming this JSON format must ignore unrecognized attributes.

.. _device-configuration.json: https://github.com/interop-dev/network-device-schema/blob/master/examples/device-configuration.json

= Device Monitoring Data =

'''Definition''': information that indicates the behaviour of a device that changes over time.

'''Example''': <code>monitoring-data.json</code>_

A <code>Device Monitoring</code> object must have a member with the name <code>type</code> and value <code>DeviceMonitoring</code>.

The object should be composed of the following members:

* <code>general</code>
* <code>interfaces</code>
* <code>resources</code>

'''Each object will be described more in detail in the future iterations of this project'''.

.. _monitoring-data.json: https://github.com/interop-dev/network-device-schema/blob/master/examples/monitoring-data.json

= Network Routes =

'''Definition''': a list of routes of a dynamic routing protocol or statically configured on the device. May be contained in a <code>DeviceConfiguration</code> object.

'''Example''': <code>network-routes.json</code>_

A <code>Network Routes</code> object must have a member with the name <code>type</code> and value <code>NetworkRoutes</code>.

It must define the following members:

* <code>protocol</code>: the name of the routing protocol, can be <code>static</code> when representing static routes
* <code>version</code>: the version of the routing protocol, can be <code>null</code> when representing static routes
* <code>metric</code>: a string which indicates the name of main routing metric used by the routing protocol to determine the best routes when sending packets, can be <code>null</code> when representing static routes

It may also define the following optional members:

* <code>revision</code>: the revision from which the routing protocol binary was built (eg: git hash, svn revision)
* <code>router_id</code>: ID of the router on which the protocol is running

When contained in a <code>DeviceConfiguration</code>, a <code>Network Routes</code> object indicates either that a routing protocol is running on the device or that static routes have been set; in this case the member <code>routes</code> is required only for static routes.

When self contained, a <code>NetworkRoutes</code> object represents a routing table and must define a <code>routes</code> member, which contains a list of route objects.

Each <code>route</code> object must define the following members:

* <code>destination</code>: a string indicating the ip address, prefix or mac address that will be matched to the destination of the traffic
* <code>next</code>: a string indicating the ip address, prefix or mac address of the next hop
* <code>device</code>: a string indicating the interface the traffic will be going to, '''it can be omitted when representing static routes'''
* <code>cost</code>: the numeric value of the routing metric; lower cost is better, '''it can be omitted when representing static routes'''

A <code>route</code> object may also define a <code>source</code> member indicating the source (necessary for source-specific routing).

.. _network-routes.json: https://github.com/interop-dev/network-device-schema/blob/master/examples/network-routes.json

= Network Graph =

'''Definition''': a list of nodes and links that represent the topology of a network.

'''Example''': <code>network-graph.json</code>_

A <code>Network Graph</code> object must have a member with the name <code>type</code> and value <code>NetworkGraph</code>.

It must define the following members:

* <code>protocol</code>: the name of the routing protocol, can be <code>static</code> when representing static routes
* <code>version</code>: the version of the routing protocol, can be <code>null</code> when representing static routes
* <code>metric</code>: a string which indicates the name of main routing metric used by the routing protocol to determine the best routes when sending packets, can be <code>null</code> when representing static routes
* <code>nodes</code>: a list of nodes
* <code>links</code>: a list of links

It may also define the following optional members:

* <code>revision</code>: the revision from which the routing protocol binary was built (eg: git hash, svn revision)
* <code>router_id</code>: ID of the router on which the protocol is running

Each <code>node</code> object must define an <code>id</code> member and may define the following optional members:

* <code>label</code>: a label for the node
* <code>properties</code>: an object to store additional / custom metadata

Each <code>link</code> object must define the following members:

* <code>source</code>: id of the <code>target</code> node
* <code>target</code>: id of the <code>source</code> node
* <code>weight</code>: metric value for the link

Each <code>link</code> object may also define a <code>properties</code> object to store additional / custom metadata.

.. _network-graph.json: https://github.com/interop-dev/network-device-schema/blob/master/examples/network-graph.json

= FAQs =

Frequentedly Asked Questions.

== Is this some kind of new SNMP? ==

Not exactly. Think about NetJSON as a possible common language that libraries and applications can adopt in order to interoperate on different levels.

NetJSON does not aim to define how the data is exchanged, it could be exposed via an HTTP API, it could be sent through UDP packets, it could be copied from application A and pasted into application B.

← Older revision		Revision as of 23:55, 1 September 2015
Line 1:		Line 1:
	= NetJSON: data interchange format for networks =		= NetJSON: data interchange format for networks =
−
	[[image:netjson-logo.png]]		[[image:netjson-logo.png]]

@@ Line 181: / Line 181: @@
 = See also =
 * [[:en:CNML]]
 [[Category:Standards]]

@@ Line 173: / Line 173: @@
 Frequentedly Asked Questions.
-== Is this some kind of new [wikipedia:SNMP|SNMP]? ==
+== Is this some kind of new [[wikipedia:SNMP|SNMP]]? ==
 Not exactly. Think about NetJSON as a possible common language that libraries and applications can adopt in order to interoperate on different levels.

@@ Line 1: / Line 1: @@
 = NetJSON: data interchange format for networks =
-.. image:: https://raw.githubusercontent.com/interop-dev/json-for-networks/master/static/netjson-logo.png
+[[image:netjson-logo.png]]
 NetJSON is a data interchange format for encoding the basic building blocks of networking:
-* <code>devices &lt;https://github.com/interop-dev/json-for-networks#network-device-configuration&gt;</code>__
+* [https://github.com/interop-dev/json-for-networks#network-device-configuration devices]
-* <code>monitoring data &lt;https://github.com/interop-dev/json-for-networks#device-monitoring-data&gt;</code>__
+* [https://github.com/interop-dev/json-for-networks#device-monitoring-data monitoring data]
-* <code>routes &lt;https://github.com/interop-dev/json-for-networks#network-routes&gt;</code>__
+* [https://github.com/interop-dev/json-for-networks#network-routes routes]
-* <code>network topology &lt;https://github.com/interop-dev/json-for-networks#network-graph&gt;</code>__
+* [https://github.com/interop-dev/json-for-networks#network-graph network topology]
-<code>Reach us on the Mailing List</code>_ - <code>Consult the ML Archives</code>_
+[https://lists.funkfeuer.at/mailman/listinfo/interop-dev Reach us on the Mailing List] - [https://lists.funkfeuer.at/pipermail/interop-dev/ Consult the ML Archives]
-−
-.. ''Reach us on the Mailing List: https://lists.funkfeuer.at/mailman/listinfo/interop-dev .. ''Consult the ML Archives: https://lists.funkfeuer.at/pipermail/interop-dev/
 == Goals ==
@@ Line 24: / Line 22: @@
 The resulting JSON structures should follow these general principles:
-* <code>KISS</code>_: keep it simple, proceed one step at time
+* [[wikipedia:KISS_principle|KISS]]: keep it simple, proceed one step at time
-* <code>Principle of least astonishment</code>_: use accepted terminology
+* [[wikipedia:Principle_of_least_astonishment|Principle of least astonishment]]: use accepted terminology
 * '''Explicit names''': prefer verbose explicit names, eg: &quot;operating_system&quot; is better than &quot;os&quot;
@@ Line 35: / Line 33: @@
 * Node databases
 * Monitoring tools
 == Motivations ==
@@ Line 50: / Line 46: @@
 Instead of creating an ecosystem, we have been creating silos that hardly talk to each other.
-This is an attempt to invert this trend, following the successful example of the <code>GeoJSON</code>_ open standard.
+This is an attempt to invert this trend, following the successful example of the [[wikipedia:GeoJSON|GeoJSON]] open standard.
 By defining common data structures we can allow developers to focus on their goals instead of having to struggle with the differences of each vendor, firmware, routing protocol or community.
 Moreover, we will lay the groundwork for an '''ecosystem''' to grow organically: once the standard JSON structures are defined and adopted it will be easier to write systems that work together, instead of creating silos.
 == Definitions ==
-* JavaScript Object Notation (JSON), and the terms object, name, value, array, and number, are defined in <code>IETF RTC 4627</code>_.
+* JavaScript Object Notation (JSON), and the terms object, name, value, array, and number, are defined in [http://www.ietf.org/rfc/rfc4627.txt IETF RTC 4627].
-* The key words &quot;MUST&quot;, &quot;MUST NOT&quot;, &quot;REQUIRED&quot;, &quot;SHALL&quot;, &quot;SHALL NOT&quot;, &quot;SHOULD&quot;, &quot;SHOULD NOT&quot;, &quot;RECOMMENDED&quot;, &quot;MAY&quot;, and &quot;OPTIONAL&quot; in this document are to be interpreted as described in <code>IETF RFC 2119</code>_.
+* The key words &quot;MUST&quot;, &quot;MUST NOT&quot;, &quot;REQUIRED&quot;, &quot;SHALL&quot;, &quot;SHALL NOT&quot;, &quot;SHOULD&quot;, &quot;SHOULD NOT&quot;, &quot;RECOMMENDED&quot;, &quot;MAY&quot;, and &quot;OPTIONAL&quot; in this document are to be interpreted as described in [http://www.ietf.org/rfc/rfc2119.txt IETF RFC 2119].
-−
-.. ''IETF RTC 4627: http://www.ietf.org/rfc/rfc4627.txt .. ''IETF RFC 2119: http://www.ietf.org/rfc/rfc2119.txt
 = Network Device Configuration =
@@ Line 69: / Line 61: @@
 '''Definition''': configuration and properties of a network device.
-'''Example''': <code>device-configuration.json</code>_
+'''Example''': [https://github.com/interop-dev/json-for-networks/blob/master/examples/device-configuration.json device-configuration.json]
 A <code>Network Device Configuration</code> object must have a member with the name <code>type</code> and value <code>DeviceConfiguration</code>.
@@ Line 94: / Line 86: @@
 Software consuming this JSON format must ignore unrecognized attributes.
 = Device Monitoring Data =
@@ Line 101: / Line 91: @@
 '''Definition''': information that indicates the behaviour of a device that changes over time.
-'''Example''': <code>monitoring-data.json</code>_
+'''Example''': [https://github.com/interop-dev/network-device-schema/blob/master/examples/monitoring-data.json monitoring-data.json]
 A <code>Device Monitoring</code> object must have a member with the name <code>type</code> and value <code>DeviceMonitoring</code>.
@@ Line 112: / Line 102: @@
 '''Each object will be described more in detail in the future iterations of this project'''.
 = Network Routes =
@@ Line 119: / Line 107: @@
 '''Definition''': a list of routes of a dynamic routing protocol or statically configured on the device. May be contained in a <code>DeviceConfiguration</code> object.
-'''Example''': <code>network-routes.json</code>_
+'''Example''': [https://github.com/interop-dev/network-device-schema/blob/master/examples/network-routes.json network-routes.json]
 A <code>Network Routes</code> object must have a member with the name <code>type</code> and value <code>NetworkRoutes</code>.
@@ Line 146: / Line 134: @@
 A <code>route</code> object may also define a <code>source</code> member indicating the source (necessary for source-specific routing).
 = Network Graph =
@@ Line 153: / Line 139: @@
 '''Definition''': a list of nodes and links that represent the topology of a network.
-'''Example''': <code>network-graph.json</code>_
+'''Example''': [https://github.com/interop-dev/network-device-schema/blob/master/examples/network-graph.json network-graph.json]
 A <code>Network Graph</code> object must have a member with the name <code>type</code> and value <code>NetworkGraph</code>.
@@ Line 182: / Line 168: @@
 Each <code>link</code> object may also define a <code>properties</code> object to store additional / custom metadata.
 = FAQs =