Skip to main content

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.

FieldDescription
powered_byAlways arc46.io
gitGit commit of the Squid version processing the request
buildBuild timestamp of the Squid version
license_max_entitiesYour licensed entity limit. See Pricing
requested_byThe authenticated user calling Squid
request_receivedTimestamp when Squid received the request
configThe configuration you requested
row_countNumber of entities returned by the base query

Optional Metadata Fields​

These fields appear only when applicable to the request.

FieldDescriptionWhen Present
license_valid_tillLicense expiration date. See LicenseLicense is valid
license_error_msgError messageLicense is invalid or expired
requested_relationsRelations included in the requestRelations were requested
sys_idsRequested sys_id valuessys_id parameter was provided
limit_requestMaximum entities to returnlimit parameter was provided
updatedBeforeParsed updatedBefore valueFilter was provided
updatedSinceParsed updatedSince valueFilter was provided
lastDiscoveredBeforeParsed lastDiscoveredBefore valueFilter was provided
lastDiscoveredSinceParsed lastDiscoveredSince valueFilter was provided
provided_filterThe encodedQuery from your requestFilter was provided
view_filterThe encodedQuery defined in the configurationConfiguration has a filter
combined_filterCombined encodedQuery applied by ServiceNowAny filters are active
When in doubt: Check combined_filter

combined_filter shows the final encodedQuery that ServiceNow executed, combining all your filter parameters. Useful for verifying that your query was interpreted as intended.

(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.

FieldDescription
config_queriesNumber of queries to load the configuration
config_cacheConfiguration cache performance (see below)
duration_parse_configTime to prepare the configuration
base_data_query_startTimestamp when the data query started
base_data_query_durationDuration of the data query
base_data_query_returnedTimestamp when the data query completed
data_queriesTotal number of queries to retrieve entity 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:

data​

data contains the entities directly defined by the configuration.

The configuration defines:

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.

See RenderTypes for Relations for how to control where related data appears (relations section vs inlined in data) and what data is included.

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 that control how references appear — from sys_id pointers resolved in referenced, to fully inlined entity objects, to plain string values.

Last updated on
We track. Ok?