1Goals

This specification defines the custom scalar type JSON that is useful for specifying accepted JSON payloads. This specification is based on this spec, unless otherwise mentioned here.

Note: All mentions of JSON refer to the scalar type defined by this specification. All mentions of JSON refer to a user-declared scalar name.

2Definition

• A scalar type with any name can be marked as JSON using the built-in @specifiedBy directive. The URL to mark the type as JSON in the @specifiedBy directive is https://ibm.github.io/graphql-specs/custom-scalars/json.html.
• Only in the absence of the @specifiedBy directive, an implementation may treat a scalar type as JSON if the name of the type is JSON.

3Example of the JSON Type

The following example uses the JSON type:

Example № 1scalar MyJSON @specifiedBy (url: "https://ibm.github.io/graphql-specs/custom-scalars/json.html")
scalar JSON
scalar UnknownScalar

type Query {  
  takesMyJSON(arg: MyJSON): Int
  takesJSON(arg: JSON): Int
}

schema {
  query: Query
}

In this example, the following points should be noted:

• MyJSON is considered to be JSON because the @specifiedBy directive uses the URL for this JSON specification.
• Despite the absence of a URL, JSON may be recognized as a JSON because the name of the scalar type is JSON and there is no @specifiedBy directive to indicate otherwise.
• UnknownScalar is not considered to be JSON as neither of the preceding two conditions is satisfied.
• The arg arguments used in Query.takesMyJSON and Query.takesJSON each expect a JSON value.

This is a simple example query that matches the schema:

Example № 2query example {
   takesMyJSON (arg: "{\"EV\" : \"Tesla\"}")
}

4Customizing the JSON Type

JSON can be customized using the @scalarParam directive as defined here.

Data types

The following configurable @scalarParam parameters specify the data types that JSON accepts.

• ObjectAllowed accepts JSON objects.
• ArrayAllowed accepts JSON arrays.
• ScalarAllowed accepts JSON scalars.

When any of these parameters are set to true, data of the specified type passes validation. When set to false, the specified type is invalid. The default value for each of these parameters is true.

JSON components restrictions

The following configurable @scalarParam parameters apply restrictions to the input that the JSON accepts.

• MaxDocumentSize specifies the maximum size in bytes of the JSON string. The accepted range is 0 - 5368709121. The default value is 16000. A value of 0 indicates an unlimited string size.
• MaxNameLength specifies the maximum name length in bytes of the name portion of the JSON name-value pair. The length includes any white space that is contained between quotation marks. The accepted range is 0 - 8192. The default value is 256. A value of 0 indicates an unlimited name length.
• MaxNestingDepth specifies the maximum level of nested name-value pairs, the maximum number of nested arrays, or the maximum number of combinations of name-value pairs and arrays. The accepted range is 0 - 4096. The default value is 8. A value of zero indicates unlimited nesting depth.
• MaxNumberLength limits the number of bytes in the value portion of a name-value pair when the value is a number. The number must be a contiguous string of bytes without whitespace. The number can include a minus sign and a positive or negative exponent. The accepted range is 0 - 256. The default value is 128. A value of 0 indicates an unlimited number length.
• MaxUniqueNames specifies the maximum number of unique names accepted in a JSON string. The accepted range is 0 - 1048575. The default value is 512. A value of 0 indicates an unlimited number of unique names.
• MaxValueLength specifies the maximum length in bytes of a string value. The length includes any white space that is contained between quotation marks. The accepted range is 0 - 5368709121. The default value is 8192. A value of 0 indicates an unlimited value length.
• MaxWidth specifies the maximum width of a payload. For a JSON object, it indicates the maximum number of properties. For a JSON array, it indicates the maximum number of items in the array. The accepted range is 0 - 65535. The default value is 128. A value of 0 indicates unlimited width.

5Example of JSON Type Customization

The following example demonstrates how to customize JSON using the @scalarParam directive:

Example № 3scalar ObjectJSON @specifiedBy (url: "https://ibm.github.io/graphql-specs/custom-scalars/json.html")
                  @scalarParam (name : "UniqueNames", value: "10")
                  @scalarParam (name : "DocumentSize", value: "100")
                  @scalarParam (name : "ValueLength", value: "10")
                  @scalarParam (name : "ArrayAllowed", value: "false")
                  @scalarParam (name : "ScalarAllowed", value: "false")
     
scalar ScalarOnlyJSON @specifiedBy (url: "https://ibm.github.io/graphql-specs/custom-scalars/json.html")
                      @scalarParam (name : "ObjectAllowed", value: "false")
                      @scalarParam (name : "ArrayAllowed", value: "false")

scalar ObjectArrayJSON @specifiedBy (url: "https://ibm.github.io/graphql-specs/custom-scalars/json.html")
                       @scalarParam (name : "ScalarAllowed", value: "false")

type Query {  
  takesObjJSON (arg: ObjectJSON): Int
  takesScalarJSON (arg: ScalarOnlyJSON): Int
  takesObjArrJSON (arg: ObjectArrayJSON): Int
}

schema {
  query: Query
}

6Result Coercion

Input

Only a string formatted as a valid JSON is accepted.

Output

The output value is a string formatted as a valid JSON.

7Literal Coercion

Input

Only a string formatted as a valid JSON is accepted.

Output

The output value is a string formatted as a valid JSON.

8Value Coercion

Input

Only a string formatted as a valid JSON is accepted.

Output

The output value is a string formatted as a valid JSON.