Typed JSON

Plain vs Typed JSON

The Plain JSON result format does not provide information about the type of a returned value. For example, the two following requests result in the exact same response, even if in the first case the return value is a Cypher STRING, while in the second case it is a ZONED DATETIME.

{
  "statement": "RETURN '2024-01-01T21:40:32-01:00'"
}

{
  "statement": "RETURN datetime('2024-01-01T21:40:32-01:00')"
}

If you care about what type each returned value is, you can use Neo4j’s extended JSON format with type information.

Enable Typed JSON

To receive the result in Typed JSON format, set Accept: application/vnd.neo4j.query.v1.1 in the request headers.

In this format, each return value is an object where the type and value information are stored as separate keys:

An OffsetDateTime value with the JSON with type information

{
  "$type":"OffsetDateTime",
  "_value":"2024-01-01T21:40:32-01:00"
}

If you wish to also submit parameters with this format, set Content-Type: application/vnd.neo4j.query.v1.1 in the request headers.

Examples

Example 1. Both parameters and result data in extended JSON format

Example request

POST http://localhost:7474/db/neo4j/query/v2
Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==
Accept: application/vnd.neo4j.query.v1.1
Content-Type: application/vnd.neo4j.query.v1.1

{
  "statement": "MERGE (p:Person {name: $name}) RETURN p AS person, p.name AS name",
  "parameters": {
    "name": {
      "$type": "String",
      "_value": "Phil"
    }
  }
}

Example response

202: Accepted
Content-Type: application/vnd.neo4j.query.v1.1

{
  "data": {
    "fields": [
      "person",
      "name"
    ],
    "values": [
      [
        {
          "$type": "Node",
          "_value": {
            "_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
            "_labels": [
              "Person"
            ],
            "_properties": {
              "name": {
                "$type": "String",
                "_value": "Phil"
              }
            }
          }
        },
        {
          "$type": "String",
          "_value": "Phil"
        }
      ]
    ]
  },
  "bookmarks": [
    "FB:kcwQ/wTfJf8rS1WY+GiIKXsCXg6Q"
  ]
}

Type mapping

This section details how Cypher types are labeled in the Query API.

Cypher type Query API type Example

NULL

null

{
  "$type": "Null",
  "_value": null
}

BOOLEAN

Boolean

{
  "$type": "Boolean",
  "_value": true
}

INTEGER

Integer

{
  "$type": "Integer",
  "_value": "123"
}

FLOAT

Float

{
  "$type": "Float",
  "_value": "4.56"
}

{
  "$type": "Float",
  "_value": "3.2E9"
}

Float values can be represented in decimal (ex. 0.2) or scientific notation (ex. 2.0E-7, 3.2E9). Out of range values are represented as Nan, Infinity, and -Infinity. -NaN is handled as NaN when used as parameter, but this value is never emitted as output.

When returning values, values with magnitude between 10⁻³ (inclusive) and 10⁷ (exclusive) are represented in decimal notation, whereas other values are represented in scientific notation.

STRING

String

{
  "$type": "String",
  "_value": "Hello World"
}

BYTE ARRAY

Base64

{
  "$type": "Base64",
  "_value": "A2+/"
}

LIST

List

{
  "$type": "List",
  "_value": [
    {
      "$type": "String",
      "_value": "A"
    },
    {
      "$type": "String",
      "_value": "B"
    }
  ]
}

MAP

Map

{
  "$type": "Map",
  "_value": {
    "fieldA": {
      "$type": "String",
      "_value": "A"
    },
    "fieldB": {
      "$type": "String",
      "_value": "B"
    }
  }
}

DATE

Date

{
  "$type": "Date",
  "_value": "2015-03-26"
}

ZONED TIME

Time

{
  "$type": "Time",
  "_value": "12:50:35.556+01:00"
}

LOCAL TIME

LocalTime

{
  "$type": "LocalTime",
  "_value": "12:50:35.556"
}

ZONED DATETIME

OffsetDateTime

{
  "$type": "OffsetDateTime",
  "_value": "2015-11-21T21:40:32.142Z[Antarctica/Troll]"
}

LOCAL DATETIME

LocalDateTime

{
  "$type": "LocalDateTime",
  "_value": "2015-07-04T19:32:24"
}

DURATION

Duration

{
  "$type": "Duration",
  "_value": "P14DT16H12M"
}

POINT

Point

{
  "$type": "Point",
  "_value": "SRID=7203;POINT (1.2 3.4)"
}

NODE

Node

{
  "$type": "Node",
  "_value": {
    "_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
    "_labels": [
      "Person"
    ],
    "_properties": {
      "name": {
        "$type": "String",
        "_value": "Phil"
      }
    }
  }
}

RELATIONSHIP

Relationship

{
  "$type": "Relationship",
  "_value": {
    "_element_id": "5:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
    "_start_node_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
    "_end_node_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
    "_type": "LIKES",
    "_properties": {
      "since": {
        "$type": "String",
        "_value": "forever!"
      }
    }
  }
}

PATH

Path

{
  "$type": "Path",
  "_value": [
    {
      "$type": "Node",
      "_value": {
        "_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
        "_labels": [
          "Person"
        ],
        "_properties": {
          "name": {
            "$type": "String",
            "_value": "Alice"
          },
          "age": {
            "$type": "Integer",
            "_value": "42"
          }
        }
      }
    },
    {
      "$type": "Relationship",
      "_value": {
        "_element_id": "5:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
        "_start_node_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:0",
        "_end_node_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
        "_type": "LIKES",
        "_properties": {
          "since": {
            "$type": "String",
            "_value": "forever!"
          }
        }
      }
    },
    {
      "$type": "Node",
      "_value": {
        "_element_id": "4:ff04df25-ff2b-4b55-98f8-6888297b025e:2",
        "_labels": [
          "Person"
        ],
        "_properties": {
          "name": {
            "$type": "String",
            "_value": "Phil"
          }
        }
      }
    }
  ]
}

The direction of the relationship in a path is only encoded in the start and end node element IDs. The order of returned nodes and relationships is not representative of the direction of relationships.

VECTOR

Vector

{
  "$type": "Vector",
  "_value": {
    "coordinatesType": "INT8",
    "coordinates": ["1", "-5", "10"]
  }
}

Enterprise Edition Introduced in 2025.11

Supported values for coordinatesType are: FLOAT64, FLOAT32, INT64, INT32, INT16 and INT8. The coordinates field is an array containing the string representation of the coordinate values. The dimension of the vector is implicitly defined by the length of the coordinates array.

UNSUPPORTED

Unsupported

{
  "$type": "Unsupported",
  "_value": "Type TheUnsupportedType is not supported."
}

Introduced in 2025.11