Standardized JSON common data set to support all service graph connectors

  • Release version: Zurich
  • Updated July 31, 2025
  • 8 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Standardized JSON Common Data Set to Support All Service Graph Connectors

    This standardized JSON schema and architectural approach enable ServiceNow customers to streamline the integration of multiple service graph connectors into the CMDB by using a unified data format and reusable ETL logic. By adopting this common schema, customers can reduce onboarding time for new connectors, simplify data transformation, and maintain consistent, accurate CMDB updates across complex network environments.

    Show full answer Show less

    Key Features

    • Common JSON Schema: A unified JSON schema aligned with the TNI standard that all service graph connectors must output. This schema supports various entity types such as devices, logical composites, logical connections, ports, and network topologies, ensuring data consistency and runtime adaptability to TNI changes.
    • Decoupled Connectivity and ETL: Collector or adaptor logic focuses solely on device connectivity and converting raw data into the standardized JSON format. ETL ingestion is handled separately by a generic, reusable ETL process, allowing independent development and reuse of collectors and adaptors, including third-party ones.
    • Generic ETL for CMDB Updates: A single reusable ETL process validates and processes all standardized import sets to accurately update the CMDB. It uses model mapping logic to assign the correct CI classes and populate fields such as Inventory Category. Special handling includes mapping logical interfaces to the port table, logical connections to their table, and PDU cards to the PDU table.
    • Support for Complex Devices: Logical Composite constructs model multi-chassis and composite devices accurately within the CMDB, preserving hierarchical relationships among components like routers, PDUs, slots, and cards. This is essential for representing devices such as multi-chassis routers consistently.
    • TNI Entity Creation Based on Installation: When the TNI plugin is installed, the system automatically creates TNI entities for discovered CIs with appropriate inventory categories, ensuring compliance with TNI standards. If TNI is not installed, entity creation is skipped to avoid invalid records.

    Key Outcomes

    • Accelerated Connector Onboarding: Standardizing output data formats and reusing ETL logic reduces the time and effort needed to integrate new service graph connectors.
    • Improved Data Consistency and Quality: Using a unified schema aligned with TNI standards ensures consistent representation of network entities and relationships within the CMDB.
    • Flexible Integration Architecture: Separating data collection from transformation allows customers to leverage various data sources and adaptors without reworking ETL processes.
    • Accurate Modeling of Complex Network Topologies: Support for logical composites and hierarchical device components enables precise representation of multi-chassis and composite devices in the CMDB.
    • Compliance with ServiceNow TNI Standards: Automatic TNI entity creation when enabled maintains alignment with ServiceNow’s Telecom Network Infrastructure model, improving data usability and integration.

    Use the TSOM architecture to support standardized Service Graph Connectors using a unified schema and reusable ETL logic. This reduces onboarding time for new connectors and simplifies integration with CMDB.

    1. Define the common JSON Schema

    Standardize the output of all service graph connectors to align with a single JSON format that conforms to the TNI schema.

    Ensure the following points:
    1. Implement conversion logic in the collector or adaptor to output data in the common schema.
    2. Ensure:
      • Slot-on-slot or card-on-card hierarchies are excluded.
      • Logical interfaces are clearly marked with virtual=true.
      • Equipment types align to model-class mappings.
    Note:
    The schema should support runtime adaptability to TNI changes if available.

    The following is the JSON schema common data set that supports all TSOM service graph connectors:

    {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Telco Generic Schema",
  "version": "2.0.1",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "logical_composites": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/logical_composite"
          }
        }
      },
      "required": [
        "logical_composites"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "devices": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/device"
          }
        }
      },
      "required": [
        "devices"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "logical_connections": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/logical_connection"
          }
        }
      },
      "required": [
        "logical_connections"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "port_relations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/port_relation"
          }
        }
      },
      "required": [
        "port_relations"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "logical_connection_relations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/logical_connection_relation"
          }
        }
      },
      "required": [
        "logical_connection_relations"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "numbers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/number"
          }
        }
      },
      "required": [
        "numbers"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "topologies": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/network_topology"
          }
        }
      },
      "required": [
        "topologies"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "topology_relations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/network_topology_relation"
          }
        }
      },
      "required": [
        "topology_relations"
      ],
      "additionalProperties": false
    }
  ],
  "$defs": {
    "keyRef": {
      "type": "object",
      "properties": { "key": { "type": "string" }
      },
      "required": [ "key" ],
      "additionalProperties": false
    },
    "optionalKeyRef": { "type": [ "object", "null" ],
      "properties": {
        "key": { "type": "string" }
      },
      "additionalProperties": false
    },
    "value": {
      "type": "object",
      "properties": {
        "from": { "type": [ "integer" ], "default": 0, "minimum": 0 },
        "to": { "type": [ "integer" ], "default": 0, "minimum": 0 }
      },
      "required": [ "from", "to" ],
      "additionalProperties": false
    },
    "logical_composite": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "logical_composite" ] },
        "key": { "type": "string" },
        "name": { "type": [ "string", "null" ] },
        "description": { "type": [ "string", "null" ] },
        "devices": { "type": "array", "items": { "$ref": "#/$defs/keyRef" } },
        "power_units": { "type": "array", "items": { "$ref": "#/$defs/pdu" } },
        "fan_shelves": { "type": "array", "items": { "$ref": "#/$defs/fan_shelf" } } },
      "required": [ "key", "name" ]
    },
    "pdu": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "pdu" ] },
        "key": { "type": "string" },
        "name": { "type": [ "string", "null" ] },
        "description": { "type": [ "string", "null" ] },
        "model_name": { "type": [ "string", "null" ] },
        "model_number": { "type": [ "string", "null" ] },
        "unit_position": { "type": [ "integer", "null" ], "minimum": 1 },
        "slots": { "type": "array", "items": { "$ref": "#/$defs/slot" } }
      },
      "required": [ "key", "name" ]
    },
    "fan_shelf": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "fan_shelf" ] },
        "key": { "type": "string" },
        "name": { "type": [ "string", "null" ] },
        "description": { "type": [ "string", "null" ] },
        "slots": { "type": "array", "items": { "$ref": "#/$defs/slot" } }
      },
      "required": [ "key", "name" ]
    },
    "device": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "device" ] },
        "key": { "type": "string" },
        "name": { "type": [ "string", "null" ] },
        "description": { "type": [ "string", "null" ] },
        "ip_address": { "type": [ "string", "null" ] },
        "mac_address": { "type": [ "string", "null" ] },
        "serial_number": { "type": [ "string", "null" ] },
        "model_name": { "type": [ "string", "null" ] },
        "model_number": { "type": [ "string", "null" ] },
        "manufacturer": { "type": [ "string", "null" ] },
        "firmware_version": { "type": [ "string", "null" ] },
        "slots": { "type": "array", "items": { "$ref": "#/$defs/slot" } },
        "ports": { "type": "array", "items": { "$ref": "#/$defs/port" } } },
      "required": [ "key", "name", "serial_number" ]
    },
    "slot": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "slot" ] },
        "key": { "type": "string" },
        "name": { "type": [ "string", "null" ] },
        "description": { "type": [ "string", "null" ] },
        "model_name": { "type": [ "string", "null" ] },
        "model_number": { "type": [ "string", "null" ] },
        "manufacturer": { "type": [ "string", "null" ] },
        "unit_position": { "type": [ "integer", "null" ], "minimum": 1 },
        "cards": { "type": "array", "items": { "$ref": "#/$defs/card" } }
      },
      "required": [ "key", "name" ]
    },
    "card": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "card" ] },
        "key": { "type": "string" },
        "name": { "type": [ "string", "null" ] },
        "description": { "type": [ "string", "null" ] },
        "mac_address": { "type": [ "string", "null" ] },
        "serial_number": { "type": [ "string", "null" ] },
        "firmware_version": { "type": [ "string", "null" ] },
        "model_name": { "type": [ "string", "null" ] },
        "model_number": { "type": [ "string", "null" ] },
        "manufacturer": { "type": [ "string", "null" ] },
        "unit_position": { "type": [ "integer", "null" ], "minimum": 1 },
        "slots": { "type": "array", "items": { "$ref": "#/$defs/slot" } },
        "ports": { "type": "array", "items": { "$ref": "#/$defs/port" } }
      },
      "required": [ "key", "name" ]
    },
    "port": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "port" ] },
        "key": { "type": "string" },
        "name": { "type": [ "string", "null" ] },
        "description": { "type": [ "string", "null" ] },
        "model_name": { "type": [ "string", "null" ] },
        "ip_address": { "type": [ "string", "null" ] },
        "virtual": { "type": "boolean", "default": false },
        "unit_position": { "type": [ "integer", "null" ], "minimum": 1 },
        "bandwidth_name": { "type": [ "string", "null" ] },
        "bandwidth_group": { "type": [ "string", "null" ] },
        "bandwidth": { "type": [ "integer", "null" ], "minimum": 0 },
        "mtu_size": { "type": [ "integer", "null" ], "minimum": 0 }
      },
      "required": [ "key", "name" ]
    },
    "number": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "number" ] },
        "key": { "type": "string" },
        "name": { "type": [ "string", "null" ] },
        "related_ci_type": { "type": "string", "enum": [ "Network Interface", "Physical Connection", "Logical Connection", "Equipment", "Topology" ] },
        "related_ci": { "$ref": "#/$defs/keyRef" },
        "type": { "type": "string", "enum": [ "vlan_range", "vlan_subrange", "vlan", "lag_range", "lag" ] },
        "vlan_type": { "type": "string", "enum": [ "inner", "outer" ] },
        "value": { "$ref": "#/$defs/value" }
      },
      "required": [ "key", "name", "type", "related_ci_type", "related_ci", "value" ] },
    "logical_connection": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "logical_connection" ] },
        "key": { "type": "string" },
        "name": { "type": [ "string", "null" ] },
        "description": { "type": [ "string", "null" ] },
        "model_name": { "type": [ "string", "null" ] },
        "bandwidth_group": { "type": [ "string", "null" ] },
        "bandwidth_name_a_to_z": { "type": [ "string", "null" ] },
        "bandwidth_name_z_to_a": { "type": [ "string", "null" ] },
        "bandwidth_a_to_z": { "type": [ "integer", "null" ], "minimum": 0 },
        "bandwidth_z_to_a": { "type": [ "integer", "null" ], "minimum": 0 },
        "equipment_a": { "$ref": "#/$defs/optionalKeyRef" },
        "equipment_z": { "$ref": "#/$defs/optionalKeyRef" },
        "port_a": { "$ref": "#/$defs/keyRef" },
        "port_z": { "$ref": "#/$defs/keyRef" }
      },
      "required": [ "key", "name", "equipment_a", "equipment_z", "port_a", "port_z" ]
    },
    "port_relation": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "port_relation" ] },
        "parent": { "$ref": "#/$defs/keyRef" },
        "child": { "$ref": "#/$defs/keyRef" }
      },
      "required": [ "parent", "child" ]
    },
    "logical_connection_relation": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "logical_connection_relation" ] },
        "sequence": { "type": [ "integer", "null" ], "minimum": 1 },
        "route": { "type": [ "integer", "null" ], "minimum": 1 },
        "parent": { "$ref": "#/$defs/keyRef" },
        "child": { "$ref": "#/$defs/keyRef" }
      },
      "required": [ "parent", "child" ]
    },
    "network_topology": {
      "type": "object",
      "properties": {
        "class": { "type": "string", "enum": [ "network_topology" ] },
        "key": { "type": "string" },
        "name": { "type": "string" },
        "model_name": { "type": [ "string", "null" ] },
        "devices": { "type": "array", "items": { "key": "#/$defs/optionalKeyRef" } },
        "logical_connections": { "type": "array", "items": { "key": "#/$defs/optionalKeyRef" } }
      },
      "required": [ "key", "name", "devices", "logical_connections" ]
    }
  }
}

    2. Decouple Connectivity from ETL

    Ensure flexibility by separating device interaction logic from transformation logic (ETL ingestion). Users can develop their own collectors independently of the ETL logic.

    Ensure the following points:
    1. Design collectors to focus only on connectivity and data conversion to the unified schema.
    2. Use or reuse any EMS/NMS adaptor (including third-party adaptors like Atrinet).
    3. Push the standardized data into ServiceNow import sets.

    3. Configure Generic ETL for CMDB Updates

    Use a single reusable ETL to process all standardized import sets and update the CMDB accurately.

    Ensure the following points:

    1. Validate the import set contains data in the standardized JSON format.
    2. Use the TSOM Generic ETL to:
      • Detect the entity type (e.g., Slot, Card, Logical Interface).
      • Map each entity to the correct CI class based on model mapping logic.
      • Populate fields including Inventory Category where applicable.

    Special Handling:

    • Logical Interfaces → Port table (virtual=true)
    • Logical Connections → Logical Connection table
    • PDU Cards → PDU table
    • Equipment → Model-based CI class (most recent mapping if multiple exist)

    4. Configure support for Multi-Chassis and Composite Devices

    Model complex devices such as multi-chassis routers with correct CMDB relationships.

    Ensure the following points:
    1. Use the Logical Composite construct to represent grouped entities like Router + PDU.
    2. Define individual components (Fan, Management, Slot) under their respective hierarchy.
    3. Map each entity as per the TNI modeling guidance.
    Example: For a 7750-2s multi-chassis device:
    • Logical Composite → contains Router and PDU
    • PDU → contains Slots → Cards → Sub-slots

    5. Enable TNI Entity Creation Based on Installation

    Ensure consistency with TNI standards without unnecessary record creation.

    Ensure the following points:
    • If TNI is installed:
      • Automatically create a TNI Entity for each discovered CI.
      • Set Inventory Category appropriately (e.g., "Logical Connection", "Interface").
    • If TNI is not installed: Skip TNI entity creation to avoid orphaned or invalid records.