Difference between revisions of "NetJSON"
From Guifi - Media-pool Common Repository
(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...") |
|||
| Line 1: | Line 1: | ||
= NetJSON: data interchange format for networks = | = NetJSON: data interchange format for networks = | ||
| − | + | [[image:netjson-logo.png]] | |
NetJSON is a data interchange format for encoding the basic building blocks of networking: | NetJSON is a data interchange format for encoding the basic building blocks of networking: | ||
| − | * | + | * [https://github.com/interop-dev/json-for-networks#network-device-configuration devices] |
| − | * | + | * [https://github.com/interop-dev/json-for-networks#device-monitoring-data monitoring data] |
| − | * | + | * [https://github.com/interop-dev/json-for-networks#network-routes routes] |
| − | * | + | * [https://github.com/interop-dev/json-for-networks#network-graph network topology] |
| − | + | [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] | |
| − | + | ||
| − | + | ||
== Goals == | == Goals == | ||
| Line 24: | Line 22: | ||
The resulting JSON structures should follow these general principles: | The resulting JSON structures should follow these general principles: | ||
| − | * | + | * [[wikipedia:KISS_principle|KISS]]: keep it simple, proceed one step at time |
| − | * | + | * [[wikipedia:Principle_of_least_astonishment|Principle of least astonishment]]: use accepted terminology |
* '''Explicit names''': prefer verbose explicit names, eg: "operating_system" is better than "os" | * '''Explicit names''': prefer verbose explicit names, eg: "operating_system" is better than "os" | ||
| Line 35: | Line 33: | ||
* Node databases | * Node databases | ||
* Monitoring tools | * Monitoring tools | ||
| − | |||
| − | |||
== Motivations == | == Motivations == | ||
| Line 50: | Line 46: | ||
Instead of creating an ecosystem, we have been creating silos that hardly talk to each other. | 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 | + | 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. | 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. | 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 == | == Definitions == | ||
| − | * JavaScript Object Notation (JSON), and the terms object, name, value, array, and number, are defined in | + | * 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 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in | + | * 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 [http://www.ietf.org/rfc/rfc2119.txt IETF RFC 2119]. |
| − | + | ||
| − | + | ||
= Network Device Configuration = | = Network Device Configuration = | ||
| Line 69: | Line 61: | ||
'''Definition''': configuration and properties of a network device. | '''Definition''': configuration and properties of a network device. | ||
| − | '''Example''': | + | '''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>. | 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. | Software consuming this JSON format must ignore unrecognized attributes. | ||
| − | |||
| − | |||
= Device Monitoring Data = | = Device Monitoring Data = | ||
| Line 101: | Line 91: | ||
'''Definition''': information that indicates the behaviour of a device that changes over time. | '''Definition''': information that indicates the behaviour of a device that changes over time. | ||
| − | '''Example''': | + | '''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>. | 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'''. | '''Each object will be described more in detail in the future iterations of this project'''. | ||
| − | |||
| − | |||
= Network Routes = | = 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. | '''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''': | + | '''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>. | 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). | A <code>route</code> object may also define a <code>source</code> member indicating the source (necessary for source-specific routing). | ||
| − | |||
| − | |||
= Network Graph = | = Network Graph = | ||
| Line 153: | Line 139: | ||
'''Definition''': a list of nodes and links that represent the topology of a network. | '''Definition''': a list of nodes and links that represent the topology of a network. | ||
| − | '''Example''': | + | '''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>. | 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. | Each <code>link</code> object may also define a <code>properties</code> object to store additional / custom metadata. | ||
| − | |||
| − | |||
= FAQs = | = FAQs = | ||
Revision as of 05:42, 12 May 2015
Contents
NetJSON: data interchange format for networks
NetJSON is a data interchange format for encoding the basic building blocks of networking:
Reach us on the Mailing List - Consult the ML Archives
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:
- KISS: keep it simple, proceed one step at time
- Principle of least astonishment: 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
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 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 IETF RTC 4627.
- 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 IETF RFC 2119.
Network Device Configuration
Definition: configuration and properties of a network device.
Example: device-configuration.json
A Network Device Configuration object must have a member with the name type and value DeviceConfiguration.
The object should be composed of the following members:
-
general -
hardware -
operating_system -
resources -
interfaces -
physical_devices -
routing -
dns_servers -
dns_search
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 Monitoring Data
Definition: information that indicates the behaviour of a device that changes over time.
Example: monitoring-data.json
A Device Monitoring object must have a member with the name type and value DeviceMonitoring.
The object should be composed of the following members:
-
general -
interfaces -
resources
Each object will be described more in detail in the future iterations of this project.
Network Routes
Definition: a list of routes of a dynamic routing protocol or statically configured on the device. May be contained in a DeviceConfiguration object.
Example: network-routes.json
A Network Routes object must have a member with the name type and value NetworkRoutes.
It must define the following members:
-
protocol: the name of the routing protocol, can bestaticwhen representing static routes -
version: the version of the routing protocol, can benullwhen representing static routes -
metric: a string which indicates the name of main routing metric used by the routing protocol to determine the best routes when sending packets, can benullwhen representing static routes
It may also define the following optional members:
-
revision: the revision from which the routing protocol binary was built (eg: git hash, svn revision) -
router_id: ID of the router on which the protocol is running
When contained in a DeviceConfiguration, a Network Routes object indicates either that a routing protocol is running on the device or that static routes have been set; in this case the member routes is required only for static routes.
When self contained, a NetworkRoutes object represents a routing table and must define a routes member, which contains a list of route objects.
Each route object must define the following members:
-
destination: a string indicating the ip address, prefix or mac address that will be matched to the destination of the traffic -
next: a string indicating the ip address, prefix or mac address of the next hop -
device: a string indicating the interface the traffic will be going to, it can be omitted when representing static routes -
cost: the numeric value of the routing metric; lower cost is better, it can be omitted when representing static routes
A route object may also define a source member indicating the source (necessary for source-specific routing).
Network Graph
Definition: a list of nodes and links that represent the topology of a network.
Example: network-graph.json
A Network Graph object must have a member with the name type and value NetworkGraph.
It must define the following members:
-
protocol: the name of the routing protocol, can bestaticwhen representing static routes -
version: the version of the routing protocol, can benullwhen representing static routes -
metric: a string which indicates the name of main routing metric used by the routing protocol to determine the best routes when sending packets, can benullwhen representing static routes -
nodes: a list of nodes -
links: a list of links
It may also define the following optional members:
-
revision: the revision from which the routing protocol binary was built (eg: git hash, svn revision) -
router_id: ID of the router on which the protocol is running
Each node object must define an id member and may define the following optional members:
-
label: a label for the node -
properties: an object to store additional / custom metadata
Each link object must define the following members:
-
source: id of thetargetnode -
target: id of thesourcenode -
weight: metric value for the link
Each link object may also define a properties object to store additional / custom metadata.
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.
