From 995130a60e0a125d4eeaf35faf19bf493d7d12cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20Barc=C3=A9los?= Date: Wed, 10 Jun 2026 12:11:32 +0200 Subject: [PATCH 1/4] Introduce `application/vnd.neo4j.query.v1.2` and UUID The UUID support is expected to be introduced in 2026.07 in plain json and the new media type `application/vnd.neo4j.query.v1.2`. --- modules/ROOT/pages/changelog.adoc | 6 ++++++ modules/ROOT/pages/headers.adoc | 6 +++--- modules/ROOT/pages/plain-json.adoc | 14 ++++++++++++++ modules/ROOT/pages/streaming.adoc | 2 +- modules/ROOT/pages/typed-json.adoc | 28 +++++++++++++++++++++++----- 5 files changed, 47 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/changelog.adoc b/modules/ROOT/pages/changelog.adoc index 0b16651..c5d9f78 100644 --- a/modules/ROOT/pages/changelog.adoc +++ b/modules/ROOT/pages/changelog.adoc @@ -2,6 +2,12 @@ = Changelog +[#typed-json-version-1-2] +[role=label--new-2026.07] +== application/vnd.neo4j.query.v1.2 + +- Introduce `UUID` type. + [#typed-json-version-1-1] [role=label--new-2025.11] == application/vnd.neo4j.query.v1.1 diff --git a/modules/ROOT/pages/headers.adoc b/modules/ROOT/pages/headers.adoc index 23c61df..6c8902a 100644 --- a/modules/ROOT/pages/headers.adoc +++ b/modules/ROOT/pages/headers.adoc @@ -10,7 +10,7 @@ This page contains a full list of headers you may use to tweak the API behavior, |Accept |Desired format of the response body. + -Possible values are `application/json`, `application/vnd.neo4j.query.v1.1`, and `application/vnd.neo4j.query.v1.0`. + +Possible values are `application/json`, `application/vnd.neo4j.query.v1.2`, `application/vnd.neo4j.query.v1.1`, and `application/vnd.neo4j.query.v1.0`. + For more information, see xref:plain-json.adoc[] and xref:typed-json.adoc[]. |Authorization @@ -19,7 +19,7 @@ For more information, see xref:authentication-authorization.adoc[]. |Content-Type |The format of the request body. + -Possible values are `application/json`, `application/vnd.neo4j.query.v1.1`, and `application/vnd.neo4j.query.v1.0`. + +Possible values are `application/json`, `application/vnd.neo4j.query.v1.2`, `application/vnd.neo4j.query.v1.1`, and `application/vnd.neo4j.query.v1.0`. + For more information, see xref:plain-json.adoc[] and xref:typed-json.adoc[]. |neo4j-cluster-affinity @@ -38,7 +38,7 @@ For more information, see xref:transactions.adoc[]. |Content-Type |The format of the response body (matches the `Accept` request header). + -Possible values are `application/json`, `application/vnd.neo4j.query.v1.1`, and `application/vnd.neo4j.query.v1.0`. + +Possible values are `application/json`, `application/vnd.neo4j.query.v1.2`, `application/vnd.neo4j.query.v1.1`, and `application/vnd.neo4j.query.v1.0`. + For more information, see xref:plain-json.adoc[] and xref:typed-json.adoc[]. |neo4j-cluster-affinity diff --git a/modules/ROOT/pages/plain-json.adoc b/modules/ROOT/pages/plain-json.adoc index 5d1f489..7aa6f0e 100644 --- a/modules/ROOT/pages/plain-json.adoc +++ b/modules/ROOT/pages/plain-json.adoc @@ -269,4 +269,18 @@ label:enterprise-edition[] label:new[Introduced in 2025.10] [NOTE] link:https://neo4j.com/docs/cypher-manual/current/values-and-types/vector/[`VECTOR`] values can only be retrieved from the database, but cannot be passed as parameters in Plain JSON. To create vectors, use the link:https://neo4j.com/docs/cypher-manual/current/values-and-types/vector/#construct-vector-values[Cypher `vector` constructor], or use the xref:typed-json.adoc[Typed JSON result format]. + +| UUID +| string (ISO-9834) +| [source, JSON] +---- +"550e8400-e29b-41d4-a716-446655440000" +"00000000-0000-0000-0000-000000000000" +---- + +label:new[Introduced in 2026.07] + +[NOTE] +UUID values can only be retrieved from the database, but cannot be passed as parameters in Plain JSON. + |=== diff --git a/modules/ROOT/pages/streaming.adoc b/modules/ROOT/pages/streaming.adoc index 6058f01..ff683b2 100644 --- a/modules/ROOT/pages/streaming.adoc +++ b/modules/ROOT/pages/streaming.adoc @@ -8,7 +8,7 @@ This allows clients to process data incrementally as it arrives, improving memor You enable streaming by tweaking the `Accept` header: * For xref:plain-json.adoc[Plain JSON], `application/jsonl`. -* For xref:typed-json.adoc[Typed JSON], add the suffix `+jsonl`. For example, `application/vnd.neo4j.query.v1.1+jsonl`. +* For xref:typed-json.adoc[Typed JSON], add the suffix `+jsonl`. For example, `application/vnd.neo4j.query.v1.2+jsonl`. [NOTE] For clarity, JSON objects in this page are formatted with line breaks. diff --git a/modules/ROOT/pages/typed-json.adoc b/modules/ROOT/pages/typed-json.adoc index 11342bd..2a243ce 100644 --- a/modules/ROOT/pages/typed-json.adoc +++ b/modules/ROOT/pages/typed-json.adoc @@ -32,7 +32,7 @@ If you care about what type each returned value is, you can use Neo4j's extended [[enable]] == Enable Typed JSON -To receive the result in Typed JSON format, set `Accept: application/vnd.neo4j.query.v1.1` in the request headers. +To receive the result in Typed JSON format, set `Accept: application/vnd.neo4j.query.v1.2` in the request headers. In this format, each return value is an object where the type and value information are stored as separate keys: @@ -45,7 +45,7 @@ In this format, each return value is an object where the type and value informat } ---- -If you wish to also submit parameters with this format, set `Content-Type: application/vnd.neo4j.query.v1.1` in the request headers. +If you wish to also submit parameters with this format, set `Content-Type: application/vnd.neo4j.query.v1.2` in the request headers. [[examples]] @@ -60,8 +60,8 @@ If you wish to also submit parameters with this format, set `Content-Type: appli ---- 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 +Accept: application/vnd.neo4j.query.v1.2 +Content-Type: application/vnd.neo4j.query.v1.2 ---- [source, JSON] @@ -83,7 +83,7 @@ Content-Type: application/vnd.neo4j.query.v1.1 [source, headers] ---- 202: Accepted -Content-Type: application/vnd.neo4j.query.v1.1 +Content-Type: application/vnd.neo4j.query.v1.2 ---- [source, JSON] @@ -485,4 +485,22 @@ The dimension of the vector is implicitly defined by the length of the `coordina ---- label:new[Introduced in 2025.11] +| UUID +| UUID +| [source, JSON] +---- +{ + "$type": "UUID", + "_value": "550e8400-e29b-41d4-a716-446655440000" +} +---- +[source, JSON] +---- +{ + "$type": "UUID", + "_value": "00000000-0000-0000-0000-000000000000" +} +---- +label:new[Introduced in 2026.07] + |=== From cfc1218cb900655f53ce042f2d8444252bb9a9c6 Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Wed, 1 Jul 2026 11:00:05 +0200 Subject: [PATCH 2/4] Move latest typed json version in variable --- antora.yml | 1 + modules/ROOT/pages/streaming.adoc | 2 +- modules/ROOT/pages/typed-json.adoc | 14 +++++++------- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/antora.yml b/antora.yml index 324ae21..091f1ba 100644 --- a/antora.yml +++ b/antora.yml @@ -8,3 +8,4 @@ asciidoc: attributes: page-origin-private: false neo4j-version: '5' + typed-json-version: 'vnd.neo4j.query.v1.2' diff --git a/modules/ROOT/pages/streaming.adoc b/modules/ROOT/pages/streaming.adoc index ff683b2..e81a20f 100644 --- a/modules/ROOT/pages/streaming.adoc +++ b/modules/ROOT/pages/streaming.adoc @@ -8,7 +8,7 @@ This allows clients to process data incrementally as it arrives, improving memor You enable streaming by tweaking the `Accept` header: * For xref:plain-json.adoc[Plain JSON], `application/jsonl`. -* For xref:typed-json.adoc[Typed JSON], add the suffix `+jsonl`. For example, `application/vnd.neo4j.query.v1.2+jsonl`. +* For xref:typed-json.adoc[Typed JSON], add the suffix `+jsonl`. For example, `{typed-json-version}+jsonl`. [NOTE] For clarity, JSON objects in this page are formatted with line breaks. diff --git a/modules/ROOT/pages/typed-json.adoc b/modules/ROOT/pages/typed-json.adoc index 2a243ce..c729912 100644 --- a/modules/ROOT/pages/typed-json.adoc +++ b/modules/ROOT/pages/typed-json.adoc @@ -32,7 +32,7 @@ If you care about what type each returned value is, you can use Neo4j's extended [[enable]] == Enable Typed JSON -To receive the result in Typed JSON format, set `Accept: application/vnd.neo4j.query.v1.2` in the request headers. +To receive the result in Typed JSON format, set `Accept: application/{typed-json-version}` in the request headers. In this format, each return value is an object where the type and value information are stored as separate keys: @@ -45,7 +45,7 @@ In this format, each return value is an object where the type and value informat } ---- -If you wish to also submit parameters with this format, set `Content-Type: application/vnd.neo4j.query.v1.2` in the request headers. +If you wish to also submit parameters with this format, set `Content-Type: application/{typed-json-version}` in the request headers. [[examples]] @@ -56,12 +56,12 @@ If you wish to also submit parameters with this format, set `Content-Type: appli [discrete] === Example request -[source, headers] +[source, headers, subs="attributes+"] ---- POST http://localhost:7474/db/neo4j/query/v2 Authorization: Basic bmVvNGo6dmVyeXNlY3JldA== -Accept: application/vnd.neo4j.query.v1.2 -Content-Type: application/vnd.neo4j.query.v1.2 +Accept: application/{typed-json-version} +Content-Type: application/{typed-json-version} ---- [source, JSON] @@ -80,10 +80,10 @@ Content-Type: application/vnd.neo4j.query.v1.2 [discrete] === Example response -[source, headers] +[source, headers, subs="attributes+"] ---- 202: Accepted -Content-Type: application/vnd.neo4j.query.v1.2 +Content-Type: application/{typed-json-version} ---- [source, JSON] From 263f60b1a09f40a2845b5c747592db86de3739c2 Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Thu, 2 Jul 2026 17:22:49 +0200 Subject: [PATCH 3/4] Update modules/ROOT/pages/plain-json.adoc --- modules/ROOT/pages/plain-json.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/plain-json.adoc b/modules/ROOT/pages/plain-json.adoc index 7aa6f0e..2b713cb 100644 --- a/modules/ROOT/pages/plain-json.adoc +++ b/modules/ROOT/pages/plain-json.adoc @@ -281,6 +281,6 @@ To create vectors, use the link:https://neo4j.com/docs/cypher-manual/current/val label:new[Introduced in 2026.07] [NOTE] -UUID values can only be retrieved from the database, but cannot be passed as parameters in Plain JSON. +UUID values can only be retrieved from the database in plain JSON format. To pass them as parameters, use xref:typed-json.adoc[typed JSON]. |=== From 44e6a33dec0cb62a825b6e3903cc6cbcb6c868eb Mon Sep 17 00:00:00 2001 From: Stefano Ottolenghi Date: Tue, 21 Jul 2026 16:13:21 +0200 Subject: [PATCH 4/4] remove nil example --- modules/ROOT/pages/typed-json.adoc | 7 ------- 1 file changed, 7 deletions(-) diff --git a/modules/ROOT/pages/typed-json.adoc b/modules/ROOT/pages/typed-json.adoc index c729912..a018d29 100644 --- a/modules/ROOT/pages/typed-json.adoc +++ b/modules/ROOT/pages/typed-json.adoc @@ -494,13 +494,6 @@ label:new[Introduced in 2025.11] "_value": "550e8400-e29b-41d4-a716-446655440000" } ---- -[source, JSON] ----- -{ - "$type": "UUID", - "_value": "00000000-0000-0000-0000-000000000000" -} ----- label:new[Introduced in 2026.07] |===