Add @specifiedBy directive (#2276)

Co-Authored-By: christopher butcher <chrisbutcher@users.noreply.github.com>

docs/APIReference-TypeSystem.md

@@ -206,6 +206,7 @@ class GraphQLScalarType<InternalType> {
 type GraphQLScalarTypeConfig<InternalType> = {
  name: string;
  description?: ?string;
+ specifiedByUrl?: string;
  serialize: (value: mixed) => ?InternalType;
  parseValue?: (value: mixed) => ?InternalType;
  parseLiteral?: (valueAST: Value) => ?InternalType;

src/type/__tests__/definition-test.js

@@ -49,6 +49,16 @@ describe('Type System: Scalars', () => {
  expect(() => new GraphQLScalarType({ name: 'SomeScalar' })).to.not.throw();
  });
 
+ it('accepts a Scalar type defining specifiedByUrl', () => {
+ expect(
+ () =>
+ new GraphQLScalarType({
+ name: 'SomeScalar',
+ specifiedByUrl: 'https://example.com/foo_spec',
+ }),
+ ).not.to.throw();
+ });
+
  it('accepts a Scalar type defining parseValue and parseLiteral', () => {
  expect(
  () =>
@@ -128,6 +138,19 @@ describe('Type System: Scalars', () => {
  'SomeScalar must provide both "parseValue" and "parseLiteral" functions.',
  );
  });
+
+ it('rejects a Scalar type defining specifiedByUrl with an incorrect type', () => {
+ expect(
+ () =>
+ new GraphQLScalarType({
+ name: 'SomeScalar',
+ // $DisableFlowOnNegativeTest
+ specifiedByUrl: {},
+ }),
+ ).to.throw(
+ 'SomeScalar must provide "specifiedByUrl" as a string, but got: {}.',
+ );
+ });
 });
 
 describe('Type System: Objects', () => {

src/type/__tests__/introspection-test.js

@@ -30,6 +30,7 @@ describe('Introspection', () => {
  });
  const source = getIntrospectionQuery({
  descriptions: false,
+ specifiedByUrl: true,
  directiveIsRepeatable: true,
  });
 
@@ -46,6 +47,7 @@ describe('Introspection', () => {
  {
  kind: 'OBJECT',
  name: 'QueryRoot',
+ specifiedByUrl: null,
  fields: [
  {
  name: 'onlyField',
@@ -67,6 +69,7 @@ describe('Introspection', () => {
  {
  kind: 'SCALAR',
  name: 'String',
+ specifiedByUrl: null,
  fields: null,
  inputFields: null,
  interfaces: null,
@@ -76,6 +79,7 @@ describe('Introspection', () => {
  {
  kind: 'SCALAR',
  name: 'Boolean',
+ specifiedByUrl: null,
  fields: null,
  inputFields: null,
  interfaces: null,
@@ -85,6 +89,7 @@ describe('Introspection', () => {
  {
  kind: 'OBJECT',
  name: '__Schema',
+ specifiedByUrl: null,
  fields: [
  {
  name: 'description',
@@ -189,6 +194,7 @@ describe('Introspection', () => {
  {
  kind: 'OBJECT',
  name: '__Type',
+ specifiedByUrl: null,
  fields: [
  {
  name: 'kind',
@@ -227,6 +233,17 @@ describe('Introspection', () => {
  isDeprecated: false,
  deprecationReason: null,
  },
+ {
+ name: 'specifiedByUrl',
+ args: [],
+ type: {
+ kind: 'SCALAR',
+ name: 'String',
+ ofType: null,
+ },
+ isDeprecated: false,
+ deprecationReason: null,
+ },
  {
  name: 'fields',
  args: [
@@ -362,6 +379,7 @@ describe('Introspection', () => {
  {
  kind: 'ENUM',
  name: '__TypeKind',
+ specifiedByUrl: null,
  fields: null,
  inputFields: null,
  interfaces: null,
@@ -412,6 +430,7 @@ describe('Introspection', () => {
  {
  kind: 'OBJECT',
  name: '__Field',
+ specifiedByUrl: null,
  fields: [
  {
  name: 'name',
@@ -512,6 +531,7 @@ describe('Introspection', () => {
  {
  kind: 'OBJECT',
  name: '__InputValue',
+ specifiedByUrl: null,
  fields: [
  {
  name: 'name',
@@ -574,6 +594,7 @@ describe('Introspection', () => {
  {
  kind: 'OBJECT',
  name: '__EnumValue',
+ specifiedByUrl: null,
  fields: [
  {
  name: 'name',
@@ -636,6 +657,7 @@ describe('Introspection', () => {
  {
  kind: 'OBJECT',
  name: '__Directive',
+ specifiedByUrl: null,
  fields: [
  {
  name: 'name',
@@ -733,6 +755,7 @@ describe('Introspection', () => {
  {
  kind: 'ENUM',
  name: '__DirectiveLocation',
+ specifiedByUrl: null,
  fields: null,
  inputFields: null,
  interfaces: null,
@@ -893,6 +916,26 @@ describe('Introspection', () => {
  },
  ],
  },
+ {
+ name: 'specifiedBy',
+ isRepeatable: false,
+ locations: ['SCALAR'],
+ args: [
+ {
+ defaultValue: null,
+ name: 'url',
+ type: {
+ kind: 'NON_NULL',
+ name: null,
+ ofType: {
+ kind: 'SCALAR',
+ name: 'String',
+ ofType: null,
+ },
+ },
+ },
+ ],
+ },
  ],
  },
  },

src/type/definition.d.ts

@@ -291,6 +291,7 @@ export type Thunk<T> = (() => T) | T;
 export class GraphQLScalarType {
  name: string;
  description: Maybe<string>;
+ specifiedByUrl: Maybe<string>;
  serialize: GraphQLScalarSerializer<any>;
  parseValue: GraphQLScalarValueParser<any>;
  parseLiteral: GraphQLScalarLiteralParser<any>;
@@ -301,6 +302,7 @@ export class GraphQLScalarType {
  constructor(config: Readonly<GraphQLScalarTypeConfig<any, any>>);
 
  toConfig(): GraphQLScalarTypeConfig<any, any> & {
+ specifiedByUrl: Maybe<string>;
  serialize: GraphQLScalarSerializer<any>;
  parseValue: GraphQLScalarValueParser<any>;
  parseLiteral: GraphQLScalarLiteralParser<any>;
@@ -327,6 +329,7 @@ export type GraphQLScalarLiteralParser<TInternal> = (
 export interface GraphQLScalarTypeConfig<TInternal, TExternal> {
  name: string;
  description?: Maybe<string>;
+ specifiedByUrl?: Maybe<string>;
  // Serializes an internal value to include in a response.
  serialize: GraphQLScalarSerializer<TExternal>;
  // Parses an externally provided value to use as an input.

src/type/definition.js

@@ -568,6 +568,7 @@ function undefineIfEmpty<T>(arr: ?$ReadOnlyArray<T>): ?$ReadOnlyArray<T> {
 export class GraphQLScalarType {
  name: string;
  description: ?string;
+ specifiedByUrl: ?string;
  serialize: GraphQLScalarSerializer<mixed>;
  parseValue: GraphQLScalarValueParser<mixed>;
  parseLiteral: GraphQLScalarLiteralParser<mixed>;
@@ -579,6 +580,7 @@ export class GraphQLScalarType {
  const parseValue = config.parseValue ?? identityFunc;
  this.name = config.name;
  this.description = config.description;
+ this.specifiedByUrl = config.specifiedByUrl;
  this.serialize = config.serialize ?? identityFunc;
  this.parseValue = parseValue;
  this.parseLiteral =
@@ -588,6 +590,14 @@ export class GraphQLScalarType {
  this.extensionASTNodes = undefineIfEmpty(config.extensionASTNodes);
 
  devAssert(typeof config.name === 'string', 'Must provide name.');
+
+ devAssert(
+ config.specifiedByUrl == null ||
+ typeof config.specifiedByUrl === 'string',
+ `${this.name} must provide "specifiedByUrl" as a string, ` +
+ `but got: ${inspect(config.specifiedByUrl)}.`,
+ );
+
  devAssert(
  config.serialize == null || typeof config.serialize === 'function',
  `${this.name} must provide "serialize" function. If this custom Scalar is also used as an input type, ensure "parseValue" and "parseLiteral" functions are also provided.`,
@@ -613,6 +623,7 @@ export class GraphQLScalarType {
  return {
  name: this.name,
  description: this.description,
+ specifiedByUrl: this.specifiedByUrl,
  serialize: this.serialize,
  parseValue: this.parseValue,
  parseLiteral: this.parseLiteral,
@@ -650,6 +661,7 @@ export type GraphQLScalarLiteralParser<TInternal> = (
 export type GraphQLScalarTypeConfig<TInternal, TExternal> = {|
  name: string,
  description?: ?string,
+ specifiedByUrl?: ?string,
  // Serializes an internal value to include in a response.
  serialize?: GraphQLScalarSerializer<TExternal>,
  // Parses an externally provided value to use as an input.

src/type/directives.d.ts

@@ -59,6 +59,11 @@ export const GraphQLIncludeDirective: GraphQLDirective;
  */
 export const GraphQLSkipDirective: GraphQLDirective;
 
+/**
+ * Used to provide a URL for specifying the behavior of custom scalar definitions.
+ */
+export const GraphQLSpecifiedByDirective: GraphQLDirective;
+
 /**
  * Constant string used for default reason for a deprecation.
  */

src/type/directives.js

@@ -192,13 +192,29 @@ export const GraphQLDeprecatedDirective = new GraphQLDirective({
  },
 });
 
+/**
+ * Used to provide a URL for specifying the behaviour of custom scalar definitions.
+ */
+export const GraphQLSpecifiedByDirective = new GraphQLDirective({
+ name: 'specifiedBy',
+ description: 'Exposes a URL that specifies the behaviour of this scalar.',
+ locations: [DirectiveLocation.SCALAR],
+ args: {
+ url: {
+ type: GraphQLNonNull(GraphQLString),
+ description: 'The URL that specifies the behaviour of this scalar.',
+ },
+ },
+});
+
 /**
  * The full list of specified directives.
  */
 export const specifiedDirectives = Object.freeze([
  GraphQLIncludeDirective,
  GraphQLSkipDirective,
  GraphQLDeprecatedDirective,
+ GraphQLSpecifiedByDirective,
 ]);
 
 export function isSpecifiedDirective(

src/type/introspection.js

@@ -195,7 +195,7 @@ export const __DirectiveLocation = new GraphQLEnumType({
 export const __Type = new GraphQLObjectType({
  name: '__Type',
  description:
- 'The fundamental unit of any GraphQL Schema is the type. There are many kinds of types in GraphQL as represented by the `__TypeKind` enum.\n\nDepending on the kind of a type, certain fields describe information about that type. Scalar types provide no information beyond a name and description, while Enum types provide their values. Object and Interface types provide the fields they describe. Abstract types, Union and Interface, provide the Object types possible at runtime. List and NonNull types compose other types.',
+ 'The fundamental unit of any GraphQL Schema is the type. There are many kinds of types in GraphQL as represented by the `__TypeKind` enum.\n\nDepending on the kind of a type, certain fields describe information about that type. Scalar types provide no information beyond a name, description and optional `specifiedByUrl`, while Enum types provide their values. Object and Interface types provide the fields they describe. Abstract types, Union and Interface, provide the Object types possible at runtime. List and NonNull types compose other types.',
  fields: () =>
  ({
  kind: {
@@ -239,6 +239,11 @@ export const __Type = new GraphQLObjectType({
  resolve: (type) =>
  type.description !== undefined ? type.description : undefined,
  },
+ specifiedByUrl: {
+ type: GraphQLString,
+ resolve: (obj) =>
+ obj.specifiedByUrl !== undefined ? obj.specifiedByUrl : undefined,
+ },
  fields: {
  type: GraphQLList(GraphQLNonNull(__Field)),
  args: {