Light editorial on #4380

Author: benjie

website/pages/docs/advanced-custom-scalars.mdx

@@ -100,25 +100,36 @@ describe('DateTime scalar', () => {
 Integrate the scalar into a schema and run real GraphQL queries to validate end-to-end behavior.
 
 ```js
-const { graphql, buildSchema } = require('graphql');
+const { graphql, GraphQLSchema, GraphQLObjectType } = require('graphql');
+const { DateTimeResolver as DateTime } = require('graphql-scalars');
+
+const Query = new GraphQLObjectType({
+  name: 'Query',
+  fields: {
+    now: {
+      type: DateTime,
+      resolve() {
+        return new Date();
+      },
+    },
+  },
+});
 
-const schema = buildSchema(`
+/*
   scalar DateTime
 
   type Query {
     now: DateTime
   }
-`);
-
-const rootValue = {
-  now: () => new Date('2024-01-01T00:00:00Z'),
-};
+*/
+const schema = new GraphQLSchema({
+  query: Query,
+});
 
 async function testQuery() {
   const response = await graphql({
     schema,
     source: '{ now }',
-    rootValue,
   });
   console.log(response);
 }
@@ -181,13 +192,22 @@ If you need domain-specific behavior, you can wrap an existing scalar with custo
 ```js
 const { EmailAddressResolver } = require('graphql-scalars');
 
-const StrictEmail = new GraphQLScalarType({
+const StrictEmailAddress = new GraphQLScalarType({
   ...EmailAddressResolver,
+  name: 'StrictEmailAddress',
   parseValue(value) {
-    if (!value.endsWith('@example.com')) {
+    const email = EmailAddressResolver.parseValue(value);
+    if (!email.endsWith('@example.com')) {
+      throw new TypeError('Only example.com emails are allowed.');
+    }
+    return email;
+  },
+  parseLiteral(literal, variables) {
+    const email = EmailAddressResolver.parseLiteral(literal, variables);
+    if (!email.endsWith('@example.com')) {
       throw new TypeError('Only example.com emails are allowed.');
     }
-    return EmailAddressResolver.parseValue(value);
+    return email;
   },
 });
 ```

website/pages/docs/custom-scalars.mdx

@@ -80,6 +80,10 @@ providing a name, description, and three functions:
 - `serialize`: How the server sends internal values to clients.
 - `parseValue`: How the server parses incoming variable values.
 - `parseLiteral`: How the server parses inline values in queries.
+- `specifiedByURL` (optional): A URL specifying the behavior of your scalar;
+  this can be used by clients and tooling to recognize and handle common scalars
+  such as [date-time](https://scalars.graphql.org/andimarek/date-time.html)
+  independent of their name.
 
 The following example is a custom `DateTime` scalar that handles ISO-8601 encoded
 date strings:
@@ -90,6 +94,7 @@ const { GraphQLScalarType, Kind } = require('graphql');
 const DateTime = new GraphQLScalarType({
   name: 'DateTime',
   description: 'An ISO-8601 encoded UTC date string.',
+  specifiedByURL: 'https://scalars.graphql.org/andimarek/date-time.html',
 
   serialize(value) {
     if (!(value instanceof Date)) {