document lastly merged breaking changes

Author: MacondoExpress

modules/ROOT/pages/migration/index.adoc

@@ -358,7 +358,7 @@ With a standard entity query:
 }
 ----
 
-The result will show "The Nutty Professor" only once (nodes are deduplicated):
+The result shows "The Nutty Professor" only once (nodes are deduplicated):
 
 [source, json, indent=0]
 ----
@@ -430,12 +430,13 @@ The result preserves both relationships with their distinct properties:
 }
 ----
 
-=== The `@private` directive has been removed.
+=== Removed the `@private` directive
 
 This directive was intended to be used with the library `@neo4j/graphql-ogm` which is no longer supported.
 
-=== Schema generation fails if there are conflicting plural names in types
+=== Schema generation avoids conflicting plural names
 
+Schema generation now detects conflicting plural names in types and fails intentionally.
 For example, the following schema will fail due to ambiguous `Techs` plural:
 
 [source, graphql, indent=0]
@@ -487,8 +488,7 @@ type Movie @node @fulltext(
 ----
 
 Full-text search was previously available in two different locations.
-
-The following form has now been completely removed:
+The following form has been completely removed:
 
 [source, graphql, indent=0]
 ----
@@ -583,9 +583,9 @@ The `implicitSet` option of `excludeDeprecatedFields` has been removed.
 
 === `@coalesce` directive affects projection field values
 
-In version 7.0.0, the `@coalesce` directive now applies to both filter operations and field projections. Previously, the fallback values specified in the `@coalesce` directive were only used when those fields were used in filters, but not on the returned fields.
-
-Now, when you select a field annotated with `@coalesce`, null values will be replaced with the specified fallback value in the query result.
+In version 7.0.0, the `@coalesce` directive now applies to both filter operations and field projections.
+Previously, the fallback values specified in the `@coalesce` directive were only used when those fields were used in filters, but not on the returned fields.
+Now, when you select a field annotated with `@coalesce`, null values are replaced with the specified fallback value in the query result.
 
 Consider this schema:
 
@@ -621,7 +621,7 @@ query {
 }
 ----
 
-Now, the same query will return the coalesced value:
+Now, the same query returns the coalesced value:
 
 [source, json, indent=0]
 ----
@@ -639,7 +639,8 @@ This ensures consistent behavior between filtering and projecting fields with th
 
 === Set `addVersionPrefix` to true by default
 
-In version 7.0.0, the `addVersionPrefix` option is now set to `true` by default. This means that all generated Cypher queries will automatically be prefixed with the Cypher version:
+In version 7.0.0, the `addVersionPrefix` option is set to `true` by default.
+This means that all generated Cypher queries are automatically prefixed with the Cypher version:
 
 [source, cypher, indent=0]
 ----
@@ -648,9 +649,10 @@ CYPHER 5
 MATCH(this:Movie)
 ----
 
-This ensures that the correct Cypher version is used when queries are executed in Neo4j. However, this change may be incompatible with older versions of Neo4j.
+This ensures that the correct Cypher version is used when queries are executed in Neo4j.
+However, this change may be incompatible with older versions of Neo4j.
 
-If you need to disable this behavior, you can set `cypherQueryOptions.addVersionPrefix` to `false` in the context:
+Set `cypherQueryOptions.addVersionPrefix` to `false` to disable this behavior:
 
 [source, javascript, indent=0]
 ----
@@ -677,11 +679,11 @@ await startStandaloneServer(server, {
 ----
 
 
-=== Changed DateTime and Time value conversion behavior
+=== Changed `DateTime` and `Time` value conversion behavior
 
-In version 7.0.0, `DateTime` and `Time` values are now converted from strings into temporal types directly in the generated Cypher queries, rather than in server code using the Neo4j driver.
+In version 7.0.0, `DateTime` and `Time` values are converted from Strings to temporal types directly in the generated Cypher queries, rather than in server code using the Neo4j driver.
 
-For example, if you have a date string in your GraphQL query:
+For example, if you have a date String in your GraphQL query:
 
 [source, graphql, indent=0]
 ----
@@ -702,14 +704,16 @@ WHERE this.releaseDate > datetime($param0)
 RETURN this { .title, .releaseDate } as this
 ----
 
-=== Mutation operations now follow the relationship direction defined in the `@relationship` argument queryDirection
+=== Mutation operations follow relationship directions
 
-Mutation operations now respect the `queryDirection` value defined in the `@relationship` directive when matching existing relationships. This ensures consistent behavior between queries and mutations regarding how relationships are traversed.
+Mutation operations now respect the `queryDirection` value defined in the `@relationship` directive when matching existing relationships.
+This ensures consistent behavior between queries and mutations regarding how relationships are traversed.
 
-Important to note:
-
-- When creating new relationships, the physical direction stored in the database is still determined by the `direction` argument.
-- The change affects only how existing relationships are matched during mutation operations.
+[NOTE]
+====
+ When creating new relationships, the physical direction stored in the database is still determined by the `direction` argument.
+The change affects only how existing relationships are matched during mutation operations.
+====
 
 For example, consider the following schema:
 
@@ -726,13 +730,13 @@ type Person @node {
 }
 ----
 
-With `queryDirection: UNDIRECTED`, mutations will now traverse existing relationships in both directions when matching nodes, regardless of the base `direction` value. This is consistent with how queries work with the same directive configuration.
-
+With `queryDirection: UNDIRECTED`, mutations now traverse existing relationships in both directions when matching nodes, regardless of the base `direction` value.
+This is consistent with how queries work with the same directive configuration.
 Previously, mutations would always follow the explicit `direction` value when matching existing relationships, which could lead to inconsistent behavior between queries and mutations.
 
 === Moved `where` field in nested update operations
 
-The `where` field for nested update operations has been removed, in favour of the `where` inside the nested update input.
+The `where` field for nested update operations has been removed in favor of the `where` inside the nested update input.
 
 [cols="1,1"]
 |===
@@ -802,7 +806,8 @@ type Actor @node {
 }
 ----
 
-Previously, when using `single` or `some` filters with unions, conditions inside these filters were evaluated separately for each concrete type in the union, requiring all of them to match. This was incorrect behavior.
+Previously, when using `single` or `some` filters with unions, conditions inside these filters were evaluated separately for each concrete type in the union, requiring all of them to match.
+This behavior was incorrect.
 
 [source, graphql, indent=0]
 ----
@@ -823,15 +828,55 @@ The fixed behavior in version 7.0.0:
 * `some`: Now correctly returns actors with at least one matching related node of any type in the union.
 
 This change provides more logical and consistent results, but may affect existing queries that relied on the previous behavior.
-
 This fix applies to both the new filter syntax and the deprecated filters (e.g., `actedIn_SINGLE` and `actedIn_SOME`).
 
+=== List of nullable elements no longer supported
+
+List of nullable elements such are no longer supported in types annotated with the `@node` directive.
+
+The following type definition is no longer supported:
+
+[source, graphql, indent=0]
+----
+type Actor @node {
+  name: String
+  pseudonyms: [String]!
+}
+----
+
+This is due the fact that Neo4j does not support storing NULL values as part of a List.
+
+=== Interfaces and unions cannot be implemented by a mix of `@nodes` and no `@nodes` types.
+
+Interfaces and unions can only be implemented by types that are all annotated with the `@node` directive or none of them.
+
+The following type definition is no longer supported:
+
+[source, graphql, indent=0]
+----
+interface Production @node {
+  title: String
+}
+type Movie @node implements Production {
+  title: String
+}
+type Series implements Production {
+  title: String
+}
+----
+
+=== Relationship fields now require `@node` types
+
+The `@relationship` directive can only be applied to fields whose types are annotated with the `@node` directive. 
+
+This also applies to fields defined as interfaces and unions where they must be implemented exclusively by `@node` types.
+
 
 == Deprecations
 
 === Deprecated mutations operators outside dedicated input
 
-The following operators:
+The following operators are now deprecated:
 
 - `_SET`
 - `_POP`
@@ -843,7 +888,7 @@ The following operators:
 - `_MULTIPLY`
 - `_DIVIDE`
 
-are now deprecated. You should now use the dedicated input object versions:
+Use the dedicated input object versions instead:
 
 [cols="1,1"]
 |===
@@ -893,7 +938,8 @@ const neoSchema = new Neo4jGraphQL({
 
 === Deprecated the _EQ filter syntax
 
-The `_EQ` filter syntax is now deprecated. You should now use the dedicated input object versions:
+The `_EQ` filter syntax is now deprecated.
+Use the dedicated input object versions instead:
 
 [cols="1,1"]
 |===
@@ -1019,7 +1065,8 @@ const neoSchema = new Neo4jGraphQL({
 
 === Deprecated relationship filters outside dedicated input
 
-The relationship filtering syntax outside dedicated input like `_SOME`, `_ALL`, and `_NONE` is now deprecated. You should use the dedicated input object versions:
+The relationship filtering syntax outside dedicated input like `_SOME`, `_ALL`, and `_NONE` is now deprecated.
+Use the dedicated input object versions instead:
 
 [cols="1,1"]
 |===