JSON Structure

When to read this document

This document describes the structure of JSON responses returned by Squid. Use it as a reference when:

• Building integrations that consume Squid data
• Debugging unexpected response structures
• Understanding where to find specific data in the response

For information on making API calls, see API Call.
For information on renderTypes, see RenderTypes.

The returned JSON is structured into five main sections.

Response

{
  "metadata": {
    ...
  },
  "data": {
    ...
  },
  "tags": {                                                 <= optional, depending on query parameter 'showTags'
    ...
  },
  "relations": {
    ...
  },
  "referenced": {
    ...
  }
}

metadata

metadata contains information about build, license, and requested data.

The main intention is to provide information as to how Squid understood and executed the query it was given. This is of limited value for proven production queries, but has proven useful when building and testing queries.

metadata

{
  "metadata": {
    "powered_by": "arc46.io",
    "git": "squid-1.1.0.0+0-1f88b4a",
    "build": "2025-09-21T15:30:41.370Z",
    "license_max_entities": "Unlimited",
    "license_valid_till": "2050-12-31T23:59:59.000Z",
    "requested_by": "arc46_rest_demo",
    "request_received": "2025-10-02T09:23:35.877Z",
    "config": "cmdb_ci_server",
    "requested_relations": {
      "cmdb_ci_server": [
        "ci_to_asset"
      ]
    },
    "row_count": 1,
    "limit_request": 10,
    "sys_ids": [
      "5f9b83bfc0a8010e005a2b3212c9dc07"
    ],
    "updatedBefore": "2025-12-31T12:00:00Z",
    "updatedSince": "2020-12-31T12:00:00Z",
    "lastDiscoveredBefore": "2025-12-31T12:00:00Z",
    "lastDiscoveredSince": "2020-12-31T12:00:00Z",
    "provided_filter": "base_cpu_count>10",
    "combined_filter": "base_sys_idIN5f9b83bfc0a8010e005a2b3212c9dc07^base_sys_updated_on<2025-12-31 12:00:00^base_sys_updated_on>=2020-12-31 12:00:00^base_last_discovered<2025-12-31 12:00:00^base_last_discovered>=2020-12-31 12:00:00^base_cpu_count>10"
  },
  ...
}

Core Metadata Fields

These fields are always present in the response.

Field	Description
powered_by	Always arc46.io
git	Git commit of the Squid version processing the request
build	Build timestamp of the Squid version
license_max_entities	Your licensed entity limit. See Pricing
requested_by	The authenticated user calling Squid
request_received	Timestamp when Squid received the request
config	The configuration you requested
row_count	Number of entities returned by the base query

Optional Metadata Fields

These fields appear only when applicable to the request.

Field	Description	When Present
license_valid_till	License expiration date. See License	License is valid
license_error_msg	Error message	License is invalid or expired
requested_relations	Relations included in the request	Relations were requested
sys_ids	Requested sys_id values	sys_id parameter was provided
limit_request	Maximum entities to return	limit parameter was provided
updatedBefore	Parsed updatedBefore value	Filter was provided
updatedSince	Parsed updatedSince value	Filter was provided
lastDiscoveredBefore	Parsed lastDiscoveredBefore value	Filter was provided
lastDiscoveredSince	Parsed lastDiscoveredSince value	Filter was provided
provided_filter	The encodedQuery from your request	Filter was provided
view_filter	The encodedQuery defined in the configuration	Configuration has a filter
combined_filter	Combined encodedQuery applied by ServiceNow	Any filters are active

When in doubt: Check combined_filter

Squid applies various defined filters to the base query. combined_filter is retrieved after the query was executed and reflects what ServiceNow actually executed.

(Caveat: ServiceNow does not return correct values for JoinQueries. combined_filter will not reflect filterOnTags and filterOnTeams settings.)

Extended Metadata Fields

These fields appear only when the metaData query parameter is set.

Field	Description
config_queries	Number of SQL queries executed to retrieve configuration data
config_cache	Caching statistics (see below)
duration_parse_config	Time spent retrieving and parsing the configuration
base_data_query_start	Timestamp when the base query started
base_data_query_duration	Time spent executing the base query
base_data_query_returned	Timestamp when the base query completed
data_queries	Number of SQL queries executed to retrieve data

extended metadata

{
  "metadata": {
    ...
    "config_cache": {
      "view_metadata": {
        "hits": 12,
        "misses": 0
      },
      "references": {
        "hits": 10,
        "misses": 0
      }
    },
    "duration_parse_config": "123ms",
    "base_data_query_start": "2025-12-15T10:22:27.129Z",
    "base_data_query_duration": "2ms",
    "base_data_query_returned": "2025-12-15T10:22:27.131Z",
    "data_queries": 1,
    ...
  }
}

The config_cache object contains:

• view_metadata - Cache stats for view metadata (column types, internal datatypes, target tables for references)
• references - Cache stats for reference configurations

data

data contains the entities directly defined by the configuration.

The configuration defines:

• What is rendered: see Predefined Configurations for examples.
• How and where it is rendered: see renderTypes.

The example below displays some, but not all ways renderTypes for references.

data

{
  ...,
  "data": [
    {                                                       <= first entity,
      "asset_tag": "P1000173",                              <= simple entity property,
      "assigned_to": {                                      <= reference to another entity,
        "sys_id": "b9fe0810472a02103c1eb150706d431f",       <= sys_id is used to find resolved reference in 'referenced'
        "sys_class_name": "sys_user"
      },
      "classification": "Production",
      ...,
      "model_id": {                                         <= reference to another entity
        "display_name": "Hewlett-Packard ProLiant",         <= inlined entity
        "life_cycle_stage": "Operational",
        "life_cycle_stage_status": "In Use",
        "manufacturer": {                                   <= recursively inlined referenced entity
          "city": "Palo Alto",
          "name": "Hewlett-Packard",
          "sys_class_name": "core_company",
          "sys_id": "b7e7a507c0a8016900920ee7d71d6df9"
        }
      },
      ...,                                                  <= a lot more data, if configured
      "sys_class_name": "cmdb_ci_server",
      "sys_id": "106c5c13c61122750194a1e96cfde951",
      "sys_updated_on": "2025-10-10T08:12:18Z"
    },
    {                                                       <= second entity
      "asset_tag": "P1000114",
      "assigned_to": {
        "sys_id": "30ad318577ab2300454792718a10619e",       <= resolved in referenced
        "sys_class_name": "sys_user"
      },
      ...                                                   <= data left out for brevity
    },
    ...                                                     <= potentially hundreds of thousands of entities
  ],
  "relations": {},
  "referenced": {
    ...                                                     <= all referenced entities. See documentation below.
  }
}

tags

Public cloud provider have adopted tags as way of adding metadata to entities (AWS, Azure, GCP) making tags a common and established way of qualifying and accessing configuration items, especially in a dev-ops environment.

ServiceNow supports this concept by way of cmdb_key_value. This table is populated by Cloud Discovery, but may also be populated directly.

Tags are not Tags

ServiceNow uses the term tag for a slightly different concept. See Tags for details on the ServiceNow usage.

Squid users are mainly peripheral systems or devOps integrations. These users generally understand tag as described by the major public cloud providers. We try to make life easy for our users.

tags are only rendered if explicitly requested by setting the query parameter showTags.

See showTags for details on the different render forms.

tags with queryParameter showTags or showTags=object

{
  ...,
  "tags": {
    "995390bccd34f010f8778495fd9bf7f7": {                   <= sys_id of the entity
      // key : value
      "Owner": "SD DC Ops",
      "Location": "San Diego",
      "Environment": "Production"
    }
  },
  ...
}

tags with queryParameter showTags=array

{
  ...,
  "tags": {
    "995390bccd34f010f8778495fd9bf7f7": [                   <= sys_id of the entity
      {
        // key
        "name": "Owner",
        // value
        "value": "SD DC Ops"
      },
      {
        "name": "Location",
        "value": "San Diego"
      },
      {
        "name": "Environment",
        "value": "Production"
      }
    ]
  },
  ...
}

relations

Relations give entities context:

• What service is using a CI?
• Who is the CI assigned to?
• Where is the CI located?

Relations must be explicitly requested

As resolving relations comes with a cost, Squid does not render relations by default.

Squid will only resolve relations if explicitly requested by setting the query parameter relations.

Squid can resolve

• CMDB CI Relations (cmdb_rel_ci)
• 1-to-N Relations (e.g. parent references)
• M-to-N relations (Both sys_m2m or custom)

See Relations for further details.

The sys_id of the source entity is the key. Each relation is an array of target entities.

relations

{
  ...,
  "relations": {
    "5f9b83bfc0a8010e005a2b3212c9dc07": {                   <= sysId of the source entity
      "asset": [                                            <= relation name
        {                                                   <= the target of the relation, here rendered as renderType 'Relation Reference'
          "sys_id": "9bc1fa8837f3100044e0bfc8bcbe5d26",
          "sys_class_name": "alm_asset"
        }
      ]
    }
  },
  "referenced": {
    ...                                                     <= all referenced entities
  }
}

Squid has 10 different RenderTypes for Relations that define how and where a relation is rendered.

Quick Reference for Relations

Where does the relation appear?

RenderType prefix	Location	Best for
Relation*	relations section	Bulk exports
Inline*	Inlined with entity in data	Single-entity requests

What data is included?

RenderType	You see the relation as...	Full entity data is...
Relation Reference	sys_id + sys_class_name objects in relations	in referenced
Relation SysId	sys_id + sys_class_name objects in relations	n/a
Relation Literal	Plain string value in relations	n/a
Relation Display Value	Display text string in relations	n/a
Inline Content	Fully nested entity objects in data	inlined in data
Inline Reference	sys_id + sys_class_name objects inlined in data	in referenced
Inline SysId	sys_id + sys_class_name objects inlined in data	n/a
Inline Literal	Plain string value in data	n/a
Inline Display Value	Display text strings in data	n/a

For detailed information on RenderTypes for Relations, see RenderTypes for Relations.

referenced

All referenced entities are rendered in the referenced section.

This enables Squid to consolidate and minimize database queries. Instead of retrieving referenced entities one by one, Squid keeps track of all referenced entities and then retrieves them with a single query per target configuration.

referenced is a JSON object of all referenced entities. The sysId of the referenced entity is the key.

referenced

{
  ...,
  "referenced": {
    "30ad318577ab2300454792718a10619e": {                   <= sysId of an entity
      "active": true,                                       <= entity rendered according to the target configs
      "department": {
        "sys_id": "21d148bb475706103c1eb150706d430f",
        "sys_class_name": "cmn_department"
      },
      "first_name": "Nirali",
      "last_name": "Patel",
      "name": "Nirali Patel",
      "sys_class_name": "sys_user",
      "sys_id": "30ad318577ab2300454792718a10619e",
      "sys_mod_count": 6,
      "sys_updated_on": "2025-09-20T19:14:25Z",
      "user_name": "homepage.alp"
    },
    "86ddef6d47360a103c1eb150706d436a": {                   <= sysId of an entity,
      "country": "Germany",                                 <= entity rendered according to the target configs
      "customer": false,
      "manufacturer": false,
      "name": "Accord Investments",
      "sys_class_name": "core_company",
      "sys_id": "86ddef6d47360a103c1eb150706d436a",
      "sys_mod_count": 1,
      "sys_updated_on": "2024-06-15T06:53:58Z",
      "vendor": false
    }
  },
  ...
}

Squid allows for a wide variety of RenderTypes for references. Rendering references in referenced isn't your only option.

Quick Reference

RenderType	In data you see...	Full entity data is ...
Reference	sys_id + sys_class_name object	in referenced
Inline Content	Nested object with full entity	inlined in data
SysId	Just sys_id + sys_class_name, nothing in referenced	n/a
Literal	Plain string value	inlined in data
Display Value	Array with display text	inlined in data
Disable	n/a	n/a