Standardized JSON data set for service graph connectors

  • Release version: Australia
  • Updated March 12, 2026
  • 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 Data Set for Service Graph Connectors

    This guide explains how to implement a standardized JSON schema and architecture for Service Graph Connectors within ServiceNow, based on the TSOM architecture. The goal is to unify data formats and ETL processes to accelerate onboarding of new connectors, ensure consistent CMDB integration, and support complex device modeling. This standardization is essential for ServiceNow customers who want streamlined, scalable, and accurate discovery and configuration management of network and telecommunications assets.

    Show full answer Show less

    Key Features

    • Common JSON Schema: All service graph connectors must output data following a unified JSON schema conforming to the Telco Network Inventory (TNI) standards. This schema excludes slot-on-slot hierarchies, clearly marks logical interfaces as virtual, and aligns equipment types to model-class mappings. The schema is designed for runtime adaptability to TNI changes.
    • Decoupled Connectivity and ETL: Device connectivity and data collection logic are separated from ETL transformation processes. Collectors focus on connectivity and data conversion to the standard schema, allowing reuse of EMS/NMS adaptors and pushing data into ServiceNow import sets independently of ETL.
    • Generic ETL for CMDB Updates: A reusable ETL process ingests all standardized import sets to detect entity types and map them accurately into the CMDB. This includes mapping logical interfaces, logical connections, PDU cards, and equipment to correct CI classes with appropriate inventory categories.
    • Support for Multi-Chassis and Composite Devices: The standardized schema supports modeling complex devices such as multi-chassis routers by using logical composites to represent grouped entities (e.g., router plus PDU), with hierarchical components like fans, slots, and cards properly defined and mapped.
    • TNI Entity Creation Based on Installation: When TNI is installed, the system automatically creates corresponding TNI entities for discovered CIs with the right inventory categories. If TNI is not installed, entity creation is skipped to prevent invalid or orphaned records.

    What Customers Can Expect

    • Faster and more consistent onboarding of new service graph connectors due to a unified data standard and reusable logic.
    • Improved integration and data quality within the CMDB through standardized data ingestion and mapping.
    • Greater flexibility by allowing customers or partners to develop or reuse collectors independently from ETL processes.
    • Accurate modeling of complex network equipment and logical connections, supporting detailed asset and relationship management.
    • Alignment with TNI standards that enhance inventory categorization and entity management when TNI is deployed.

    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.