Using Literal Values

Use literal values to enhance your graph with data that doesn't come directly from your REST API responses. Using literal values, you can add constants and create new data structures to complement the data from your APIs.

Common use cases for literal values

Literal values serve several important purposes in GraphQL schema mapping:

• Adding metadata: Append version numbers, timestamps, or source information to your GraphQL responses

• Standardizing formats: Transform inconsistent response formats into a consistent structure

Using literal values

You can use literal values with $() like so:

body: """
hello: $("world")
theAnswer: $(42)
isTrue: $(true)
anObject: $({ key: "value" })
aList: $([1, 2, 3])
"""

To avoid using the $() wrapper repeatedly, you can wrap an entire object with $():

body: """
$({
  hello: "world",
  theAnswer: 42,
  isTrue: true,
  anObject: { key: "value" },
  aList: [1, 2, 3],
})
"""

Inside the $()expression, you can use any JSON literal: numbers, strings, booleans, arrays, objects, and null.

Combining literal values with API data

You can seamlessly combine literal values with data from your API response:

1selection: """
2id
3name
4metadata: $({
5  source: "product-api",
6  version: "1.0",
7  features: ["search", "filter", "sort"]
8})
9"""

This creates a response with both API-sourced data (id and name) and literal values (metadata).

Variables in literals

You can use variables, like $args and $this, in literal values.

selection: """
names: $([             # a list field like `names: [String]`
  $args.input.name,    # a variable
  results->first.name  # a selection
])
"""

Given the following inputs for the example above:

{
  "$args": {
    "input": {
      "name": "Alice"
    }
  }
}

{
  "results": [
    { "name": "Bob" }
    { "name": "Charlie" }
  ]
}

The selection mapping results in:

{ "names": ["Alice", "Bob"] }

Using literals with @connect

The following rules apply when using literal values with the @connect directive:

1. All literal values in the body argument are always allowed.

2. Scalar literal values (strings, numbers, booleans) and lists of scalars are allowed in the selection argument.

3. Literal values can't be mapped to a field that returns a nested object or list of nested objects.

4. Literal objects and lists and lists of objects are allowed only if they're mapped to a custom scalar field.

See corresponding examples of these rules below. The number in parentheses, for example, (1) on line 6 shows an example of rule 1.

1type Mutation {
2  createPost(input: CreatePostInput!): PostPayload
3    @connect(
4      http: {
5        POST: "https://api.example.com/posts"
6        body: "$({ id: 1, title: "Hello, world!" })" # ✅ (1)
7      }
8      selection: """
9      success: $(true) # ✅ (2)
10      post: $({ id: 1, title: "Hello, world!" }) # ❌ (3)
11      metadata: $({ key: "value" }) # ✅ (4)
12      """
13    )
14
15type PostPayload {
16  success: Boolean
17  post: Post # ⚠️ Object type
18  metadata: JSON
19}
20
21scalar JSON

Additional resources

• Refer to the mapping language reference for a complete overview of mapping syntax and usage.

• See the variables reference to see which variables you can use with literals

• See methods reference for examples of more complex data manipulation