refact: add description for scalars

README.md

@@ -83,7 +83,7 @@ directive @authenticated on
   | INTERFACE
   | SCALAR
   | ENUM
-directive @requiresScopes(scopes: [[Scope!]!]!) on
+directive @requiresScopes(scopes: [[federation__Scope!]!]!) on
     FIELD_DEFINITION
   | OBJECT
   | INTERFACE
@@ -96,7 +96,7 @@ directive @policy(policies: [[federation__Policy!]!]!) on
   | SCALAR
   | ENUM
 scalar federation__Policy
-scalar Scope
+scalar federation__Scope
 scalar FieldSet
 
 ```

federation_spec/federation-v2.5.graphql

@@ -35,11 +35,11 @@ directive @authenticated on
   | INTERFACE
   | SCALAR
   | ENUM
-directive @requiresScopes(scopes: [[Scope!]!]!) on
+directive @requiresScopes(scopes: [[federation__Scope!]!]!) on
     FIELD_DEFINITION
   | OBJECT
   | INTERFACE
   | SCALAR
   | ENUM
-scalar Scope
+scalar federation__Scope
 scalar FieldSet

federation_spec/federation-v2.6.graphql

@@ -35,7 +35,7 @@ directive @authenticated on
   | INTERFACE
   | SCALAR
   | ENUM
-directive @requiresScopes(scopes: [[Scope!]!]!) on
+directive @requiresScopes(scopes: [[federation__Scope!]!]!) on
     FIELD_DEFINITION
   | OBJECT
   | INTERFACE
@@ -48,5 +48,5 @@ directive @policy(policies: [[federation__Policy!]!]!) on
   | SCALAR
   | ENUM
 scalar federation__Policy
-scalar Scope
+scalar federation__Scope
 scalar FieldSet

graphene_federation/apollo_versions/v2_5.py

@@ -2,7 +2,7 @@
 from graphql import GraphQLArgument, GraphQLDirective, GraphQLList, GraphQLNonNull
 
 from .v2_4 import get_directives as get_directives_v2_4
-from graphene_federation.scalars import Scope
+from graphene_federation.scalars import FederationScope
 
 authenticated_directive = CustomDirective(
     name="authenticated",
@@ -29,7 +29,9 @@
     args={
         "scopes": GraphQLArgument(
             GraphQLNonNull(
-                GraphQLList(GraphQLNonNull(GraphQLList(GraphQLNonNull(Scope))))
+                GraphQLList(
+                    GraphQLNonNull(GraphQLList(GraphQLNonNull(FederationScope)))
+                )
             )
         ),
     },

graphene_federation/scalars/__init__.py

@@ -1,7 +1,7 @@
 from ._any import _Any
 from .federation_policy import FederationPolicy
+from .federation_scope import FederationScope
 from .field_set_v1 import _FieldSet
 from .field_set_v2 import FieldSet
 from .link_import import link_import
 from .link_purpose import link_purpose
-from .scope import Scope

graphene_federation/scalars/_any.py

@@ -5,7 +5,7 @@
 class _Any(Scalar):
     name = "_Any"
     __typename = String(required=True)
-    description = None
+    description = "A JSON serialized used for entity representations"
     specified_by_url = None
 
     @staticmethod

graphene_federation/scalars/federation_policy.py

@@ -46,6 +46,7 @@ def _parse_string_literal(value_node: ValueNode, _variables: Any = None) -> str:
 # Reference: https://www.apollographql.com/docs/federation/subgraph-spec/
 FederationPolicy = GraphQLScalarType(
     name="federation__Policy",
+    description="This string-serialized scalar represents an authorization policy.",
     serialize=_serialize_string,
     parse_value=_coerce_string,
     parse_literal=_parse_string_literal,

graphene_federation/scalars/scope.py → graphene_federation/scalars/federation_scope.py

@@ -40,8 +40,9 @@ def _parse_string_literal(value_node: ValueNode, _variables: Any = None) -> str:
 
 
 # Reference: https://www.apollographql.com/docs/federation/subgraph-spec/
-Scope = GraphQLScalarType(
-    name="Scope",
+FederationScope = GraphQLScalarType(
+    name="federation__Scope",
+    description="This string-serialized scalar represents a JWT scope",
     serialize=_serialize_string,
     parse_value=_coerce_string,
     parse_literal=_parse_string_literal,

graphene_federation/scalars/field_set_v1.py

@@ -1,4 +1,12 @@
 from graphql import GraphQLScalarType
 
 # Reference: https://www.apollographql.com/docs/federation/subgraph-spec/
-_FieldSet = GraphQLScalarType(name="_FieldSet")
+_FieldSet = GraphQLScalarType(
+    name="_FieldSet",
+    description=" ".join(
+        (
+            "A string-serialized scalar represents a set of fields that's passed to a federated directive,",
+            "such as @key, @requires, or @provides",
+        )
+    ),
+)

graphene_federation/scalars/field_set_v2.py

@@ -1,4 +1,12 @@
 from graphql import GraphQLScalarType
 
 # Reference: https://www.apollographql.com/docs/federation/subgraph-spec/
-FieldSet = GraphQLScalarType(name="FieldSet")
+FieldSet = GraphQLScalarType(
+    name="FieldSet",
+    description=" ".join(
+        (
+            "A string-serialized scalar represents a set of fields that's passed to a federated directive,",
+            "such as @key, @requires, or @provides",
+        )
+    ),
+)

graphene_federation/scalars/link_import.py

@@ -49,10 +49,14 @@ def _parse_string_literal(value_node: ValueNode, _variables: Any = None) -> str:
     return value_node.value
 
 
-# Reference: https://www.apollographql.com/docs/federation/subgraph-spec/
-
 link_import = GraphQLScalarType(
     name="link__Import",
+    description=" ".join(
+        (
+            "A string serialized scalar specify which directives from an external federation specification",
+            "should be imported into the current schema when using @link",
+        )
+    ),
     serialize=_serialize_string,
     parse_value=_coerce_string,
     parse_literal=_parse_string_literal,

graphene_federation/scalars/link_purpose.py

@@ -4,6 +4,7 @@
 
 link_purpose = GraphQLEnumType(
     name="link__Purpose",
+    description="An Enum to clarify the type of directives (security, execution) in the specification",
     values={
         "SECURITY": GraphQLEnumValue(
             value="SECURITY",

tests/gql/test_annotation_corner_cases/test_annotate_object_with_meta_name_1.graphql

@@ -24,8 +24,13 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases/test_annotate_object_with_meta_name_2.graphql

@@ -14,8 +14,13 @@ type Potato @key(fields: "id") {
   id: ID
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases/test_annotated_field_also_used_in_filter_1.graphql

@@ -24,8 +24,13 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases/test_annotated_field_also_used_in_filter_2.graphql

@@ -14,8 +14,13 @@ type B @key(fields: "id") {
   id: ID
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases/test_camel_case_field_name_1.graphql

@@ -22,8 +22,13 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases/test_camel_case_field_name_2.graphql

@@ -12,8 +12,13 @@ type Camel  @key(fields: "autoCamel") @extends {
   aCamel: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases/test_camel_case_field_name_without_auto_camelcase_1.graphql

@@ -22,8 +22,13 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases/test_camel_case_field_name_without_auto_camelcase_2.graphql

@@ -12,8 +12,13 @@ type Camel  @extends {
   aCamel: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases/test_similar_field_name_1.graphql

@@ -32,8 +32,13 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases/test_similar_field_name_2.graphql

@@ -22,8 +22,13 @@ type ChatUser  @key(fields: "id") @extends {
   ID: ID
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar FieldSet
 
-scalar Scope
+"""This string-serialized scalar represents a JWT scope"""
+scalar federation__Scope
 
+"""This string-serialized scalar represents an authorization policy."""
 scalar federation__Policy

tests/gql/test_annotation_corner_cases_v1/test_annotate_object_with_meta_name_1.graphql

@@ -21,4 +21,7 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar _FieldSet

tests/gql/test_annotation_corner_cases_v1/test_annotate_object_with_meta_name_2.graphql

@@ -11,4 +11,7 @@ type Potato @key(fields: "id") {
   id: ID
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar _FieldSet

tests/gql/test_annotation_corner_cases_v1/test_annotated_field_also_used_in_filter_1.graphql

@@ -21,4 +21,7 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar _FieldSet

tests/gql/test_annotation_corner_cases_v1/test_annotated_field_also_used_in_filter_2.graphql

@@ -11,4 +11,7 @@ type B @key(fields: "id") {
   id: ID
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar _FieldSet

tests/gql/test_annotation_corner_cases_v1/test_camel_case_field_name_1.graphql

@@ -19,4 +19,7 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar _FieldSet

tests/gql/test_annotation_corner_cases_v1/test_camel_case_field_name_2.graphql

@@ -9,4 +9,7 @@ type Camel  @key(fields: "autoCamel") @extends {
   aCamel: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar _FieldSet

tests/gql/test_annotation_corner_cases_v1/test_camel_case_field_name_without_auto_camelcase_1.graphql

@@ -19,4 +19,7 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar _FieldSet

tests/gql/test_annotation_corner_cases_v1/test_camel_case_field_name_without_auto_camelcase_2.graphql

@@ -9,4 +9,7 @@ type Camel  @extends {
   aCamel: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar _FieldSet

tests/gql/test_annotation_corner_cases_v1/test_similar_field_name_1.graphql

@@ -29,4 +29,7 @@ type _Service {
   sdl: String
 }
 
+"""
+A string-serialized scalar represents a set of fields that's passed to a federated directive, such as @key, @requires, or @provides
+"""
 scalar _FieldSet