Merge pull request #2944 from Liam-Doodson/make-relationship-properties-directive-mandatory

Make the `@relationshipProperties` directive mandatory

Author: Liam-Doodson

.changeset/quick-insects-turn.md

@@ -0,0 +1,5 @@
+---
+"@neo4j/graphql": major
+---
+
+Made `@relationshipProperties` mandatory for relationship property interfaces

docs/modules/ROOT/pages/directives.adoc

@@ -113,13 +113,13 @@ Reference: xref::type-definitions/relationships.adoc[Relationships]
 
 == `@relationshipProperties`
 
-Optional syntactic sugar to help you distinguish between interfaces which are used for relationship properties, and otherwise.
+Required to help you distinguish between interfaces which are used for relationship properties, and otherwise.
 
 Can only be used on interfaces, as per its definition:
 
 [source, graphql, indent=0]
 ----
-"""Syntactic sugar to help differentiate between interfaces for relationship properties, and otherwise."""
+"""Required to differentiate between interfaces for relationship properties, and otherwise."""
 directive @relationshipProperties on INTERFACE
 ----
 

docs/modules/ROOT/pages/filtering.adoc

@@ -341,7 +341,7 @@ type Person {
     name: String
 }
 
-interface ActedIn {
+interface ActedIn @relationshipProperties {
     screenTime: Int
 }
 ----

docs/modules/ROOT/pages/guides/v2-migration/mutations.adoc

@@ -1,7 +1,7 @@
 [[v2-migration-mutations]]
 = Mutations
 
-The most broadly affected area of functionality by the 2.0.0 upgrade are the nested operations of Mutations, to faciliate the mutation of and filtering on relationship properties.
+The most broadly affected area of functionality by the 2.0.0 upgrade are the nested operations of Mutations, to facilitate the mutation of and filtering on relationship properties.
 
 The examples in this section will be based off the following type definitions:
 

docs/modules/ROOT/pages/guides/v4-migration/index.adoc

@@ -130,6 +130,75 @@ const neoSchema = new Neo4jGraphQL({
 })
 ----
 
+==== `requires` changes
+
+In version 4.0.0, it is now possible to require non-scalar fields. This means it is also possible to require fields on related type.
+To make this possible, the `requires` argument now accept a graphql selection set instead of a list of strings.
+
+Therefore, the following type definitions:
+
+[source, graphql, indent=0]
+----
+type User {
+    firstName: String!
+    lastName: String!
+    fullName: String! @customResolver(requires: ["firstName", "lastName"])
+}
+----
+
+Would need to be modified to use a selection set as below:
+
+[source, graphql, indent=0]
+----
+type User {
+    firstName: String!
+    lastName: String!
+    fullName: String! @customResolver(requires: "firstName lastName")
+}
+----
+
+Below is a more advanced example showing what the selection set is capable of:
+
+[source, graphql, indent=0]
+----
+interface Publication {
+    publicationYear: Int!
+}
+
+type Author {
+    name: String!
+    publications: [Publication!]! @relationship(type: "WROTE", direction: OUT)
+    publicationsWithAuthor: [String!]!
+        @customResolver(
+            requires: "name publications { publicationYear ...on Book { title } ... on Journal { subject } }"
+        )
+}
+
+type Book implements Publication {
+    title: String!
+    publicationYear: Int!
+    author: [Author!]! @relationship(type: "WROTE", direction: IN)
+}
+
+type Journal implements Publication {
+    subject: String!
+    publicationYear: Int!
+    author: [Author!]! @relationship(type: "WROTE", direction: IN)
+}
+----
+
+Additionally, the requires argument also validates the required selection set against your type definitions.
+Therefore, as there is no field called `someFieldThatDoesNotExist`, an error would be thrown on startup if you tried to use the following type definitions:
+
+[source, graphql, indent=0]
+----
+type User {
+    firstName: String!
+    lastName: String!
+    fullName: String! @customResolver(requires: "firstName someFieldThatDoesNotExist")
+}
+----
+
 [plural-migration]
 === `plural` argument removed from `@node` and replaced with `@plural`
 
@@ -406,76 +475,49 @@ type query {
 
 Additionally, escaping strings is no longer needed.
 
-=== `@customResolver` changes
+=== Mandatory `@relationshipProperties`
 
-In version 4.0.0, it is now possible to require non-scalar fields. This means it is also possible to require fields on related type.
-To make this possible, the `requires` argument now accept a graphql selection set instead of a list of strings.
+Upcoming changes to interfaces require us to distinguish between interfaces that are used to specify relationship properties, and others. Therefore, the `@relationshipProperties` directive is now required on all relationship property interfaces.
+If it is not included, an error will be thrown.
 
-Therefore, the following type definitions:
+As a result, in version 4.0.0, the following type definitions are invalid:
 
 [source, graphql, indent=0]
 ----
-type User {
-    firstName: String!
-    lastName: String!
-    fullName: String! @customResolver(requires: ["firstName", "lastName"])
+type Person {
+  name: String!
+  movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT, properties: "ActedIn")
 }
-----
 
-Would need to be modified to use a selection set as below:
+type Movie {
+  title: String!
+  actors: [Person!]! @relationship(type: "ACTED_IN", direction: IN, properties: "ActedIn")
+}
 
-[source, graphql, indent=0]
-----
-type User {
-    firstName: String!
-    lastName: String!
-    fullName: String! @customResolver(requires: "firstName lastName")
+interface ActedIn {
+  screenTime: Int!
 }
 ----
 
-Below is a more advanced example showing what the selection set is capable of:
+Instead, they would need to be updated as below:
 
 [source, graphql, indent=0]
 ----
-interface Publication {
-    publicationYear: Int!
+type Person {
+  name: String!
+  movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT, properties: "ActedIn")
 }
 
-type Author {
-    name: String!
-    publications: [Publication!]! @relationship(type: "WROTE", direction: OUT)
-    publicationsWithAuthor: [String!]!
-        @customResolver(
-            requires: "name publications { publicationYear ...on Book { title } ... on Journal { subject } }"
-        )
-}
-
-type Book implements Publication {
-    title: String!
-    publicationYear: Int!
-    author: [Author!]! @relationship(type: "WROTE", direction: IN)
-}
-
-type Journal implements Publication {
-    subject: String!
-    publicationYear: Int!
-    author: [Author!]! @relationship(type: "WROTE", direction: IN)
+type Movie {
+  title: String!
+  actors: [Person!]! @relationship(type: "ACTED_IN", direction: IN, properties: "ActedIn")
 }
-----
-
-Additionally, the requires argument also validates the required selection set against your type definitions.
-Therefore, as there is no field called `someFieldThatDoesNotExist`, an error would be thrown on startup if you tried to use the following type definitions:
 
-[source, graphql, indent=0]
-----
-type User {
-    firstName: String!
-    lastName: String!
-    fullName: String! @customResolver(requires: "firstName someFieldThatDoesNotExist")
+interface ActedIn @relationshipProperties {
+  screenTime: Int!
 }
 ----
 
-
 == Miscellaneous changes
 
 [[startup-validation]]

docs/modules/ROOT/pages/queries.adoc

@@ -24,7 +24,7 @@ type User {
     friends: [User!]! @relationship(type: "FRIENDS_WITH", direction: OUT)
 }
 
-interface PostedAt {
+interface PostedAt @relationshipProperties {
     date: DateTime
 }
 ----

docs/modules/ROOT/pages/subscriptions/events/create_relationship.adoc

@@ -226,7 +226,7 @@ type Influencer implements Reviewer {
     reputation: Int!
 }
 
-interface Review {
+interface Review @relationshipProperties {
     score: Int!
 }
 ```

docs/modules/ROOT/pages/subscriptions/events/delete_relationship.adoc

@@ -226,7 +226,7 @@ type Influencer implements Reviewer {
     reputation: Int!
 }
 
-interface Review {
+interface Review @relationshipProperties {
     score: Int!
 }
 ```

docs/modules/ROOT/pages/subscriptions/filtering.adoc

@@ -335,7 +335,7 @@ type Magazine implements Reviewer {
     reputation: Int!
 }
 
-interface Review {
+interface Review @relationshipProperties {
     score: Int!
 }
 ----

docs/modules/ROOT/pages/type-definitions/basics.adoc

@@ -39,7 +39,8 @@ Note there is a directive on each "end" of the relationship in this case, but it
 
 === Relationship properties
 
-In order to add relationship properties to a relationship, you need to add a new type to your type definitions, but this time it will be of type `interface`. For example, for your "ACTED_IN" relationship, add a property "roles":
+In order to add relationship properties to a relationship, you need to add a new type to your type definitions, but this time it will be of type `interface`. This interface must be decorated with the `@relationshipProperties` directive.
+For example, for your "ACTED_IN" relationship, add a property "roles":
 
 [source, graphql, indent=0]
 ----