JSON Schema or Samples

This handler allows you to load any remote REST service and describe its request/response using the YAML config.

You can easily customize and control the built GraphQL schema with this handler.

To get started, install the handler library:

npm i @graphql-mesh/json-schema

yarn add @graphql-mesh/json-schema

pnpm add @graphql-mesh/json-schema

bun add @graphql-mesh/json-schema

Now, you can use it directly in your Mesh config file:

sources:
  - name: MyApi
    handler:
      jsonSchema:
        endpoint: https://some-service-url/endpoint-path/
        operations:
          - type: Query
            field: users
            path: /users
            method: GET
            responseSchema: ./json-schemas/users.json

Headers

Read about configuration and examples

From Arguments

Mesh automatically generates arguments for operations if needed;

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        endpoint: https://some-service-url/endpoint-path/
        operations:
          - type: Query
            field: user
            path: /user/{args.id}
            method: GET
            responseSchema: ./json-schemas/user.json

This example operation definition will generate a root field with id: ID argument. Mesh will interpolate the expression in path to get id value from args.

From JSON Samples

Mesh can also load JSON samples from a remote service. Add a json-samples directory in your project root, and put the JSON samples there (responseSample: ./jsons/MyField.response.json{:yaml} - Create a new folder like Jsons). By declaring the responseSample, you can use the JSON sample in the GraphQL schema.

Mesh Sample Example - .meshrc.yml file

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        endpoint: https://some-service-url/endpoint-path/
        operations:
          - type: Query
            field: MyField
            path: /MyField?id={args.id}
            method: GET
            responseSample: ./jsons/MyField.response.json
            responseTypeName: MyResponseName
            argTypeMap:
              id:
                type: string

Mesh Sample Example - ./jsons/MyField.response.json file

Any JSON sample file can be used.

Query Parameters

There are a few methods to define the query parameters, select the one that fits your needs (Or combine them):

Auto declare:

Mesh automatically generates arguments for operations if needed. Note that the arguments are generated as nullable strings by default.

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        endpoint: https://some-service-url/endpoint-path/
        operations:
          - type: Query
            field: user
            path: /user?id={args.id}
            method: GET
            responseSchema: ./json-schemas/user.json

With samples:

You can use the JSON samples to define the query parameters.

In this example we declare limit and offset properties:

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        endpoint: https://some-service-url/endpoint-path/
        operations:
          - type: Query
            field: getUsers
            path: /users
            method: GET
            queryParamsSample: ./jsons/MyField.queryParams.json
            responseSample: ./jsons/MyField.response.json

In ./jsons/MyField.queryParams.json:

{
  "limit": 10,
  "offset": 0
}

Manual declare:

You can define the arguments of the operation using the argTypeMap config field, according to the JSON Schema spec.

type: number will set the property to Float and type: integer will set it as Int.

In this example we declare page argument as an object with limit and offset properties:

argTypeMap:
  page:
    type: object
    properties:
      limit:
        type: integer
      offset:
        type: integer

Array can be defined as type: array with items: and their own type:

argTypeMap:
  page:
    type: array
    items:
      limit:
        type: integer
      offset:
        type: integer

If you need to use symbols that will cause GraphQL to error like ’:’ or ’[’ in the query param name, you can map an alternative definition. With the below example using name_like in the query will end up being name:like as the API call.

argTypeMap:
  name_like:
    type: string
queryParamArgMap:
  'name:like': name_like

In addition, especially for non-primitive types, the arguments should be added to the path using the queryParamArgMap config field.

Here we add the page argument to the query parameters:

queryParamArgMap:
  page: page

And here is the final config:

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        endpoint: https://some-service-url/endpoint-path/
        operations:
          - type: Query
            field: users
            path: /getUsers
            method: GET
            responseSample: ./jsons/MyField.response.json
            responseTypeName: MyResponseName
            argTypeMap:
              page:
                type: object
                properties:
                  limit:
                    type: integer
                  offset:
                    type: integer
            queryParamArgMap:
              page: page

Global arguments

Query arguments could be defined globally, on handler level, so they are added to all operations.

In this example we declare limit parameter with the default value of 10, and api_key with dynamic value taken from the environment:

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        endpoint: https://some-service-url/endpoint-path/
        queryParams:
          limit: 10
          api_key: '{env.MY_API_KEY}'

CodeSandBox Example

You can check out our example that uses the JSON Schema handler with mock data.

Config API Reference

• source (type: String)
• endpoint (type: String)
• operationHeaders (type: JSON)
• schemaHeaders (type: JSON)
• operations - (required) Array of:
  • object:
    • field (type: String, required) - This Field based on the field name of the URL path. Example: “https://MyAPIURL.com/FieldNameHere/”, so we will set the “field: FieldNameHere”.
    • description (type: String) - Your chance to describe the operation! Make sure the description is clear and concise.
    • type (type: String (Query | Mutation | Subscription), required) - Type field is set the opertion type: Query, Mutation or Subscription.
    • requestSchema (type: Any) - Your chance to provide request schema name.
    • requestSample (type: Any) - The path definition of the JSON Schema sample. Example: ”./jsons/questions.response.json”.
    • requestTypeName (type: String) - Inset any name for the type of the request body.
    • requestBaseBody (type: Any) - This body will be merged with the request body sent with the underlying HTTP request
    • responseSchema (type: Any) - Yay! Now you can provide the response schema name.
    • responseSample (type: Any) - Did you use Sample? Provide the response sample path.
    • responseTypeName (type: String) - Inset any name for the type of the response body.
    • responseByStatusCode (type: Any) - You can define your response schemas by status codes;

responseByStatusCode:
  200:
    responseSchema: ./someschema.json#/somepath
  404:
    responseSample: ./error-sample.json
    responseTypeName: MyError

* `exposeResponseMetadata` (type: `Boolean`) - Expose response details done to the upstream API

When you enable this, you will see a new field in the response type;

type MyResponseType {
  myFooField: String
  _response: ResponseMetadata
}

# And a new type for the response metadata object
type ResponseMetadata {
  url: URL
  status: Int
  method: String
  headers: JSON
  body: String
}

* `argTypeMap` (type: `JSON`) - Mapping the JSON Schema and define the arguments of the operation.

# Example:
argTypeMap:
  user_id:
    type: string

* `queryParamArgMap` (type: `JSON`) - JSON object representing the mapping of query search parameters (added to the route path) and the matching argument.

# Example:
queryParamArgMap:
  id: user_id

* `path` (type: `String`, required)
* `method` (type: `String (GET | HEAD | POST | PUT | DELETE | CONNECT | OPTIONS | TRACE | PATCH)`)
* `headers` (type: `JSON`)
* `binary` (type: `Boolean`) - If true, this operation cannot have requestSchema or requestSample

And the request body will be passed as binary with its mime type unless you define an explicit Content-Type header * deprecated (type: Boolean) - If true, @deprecated will be added to the field definition

• object:
  • field (type: String, required)
  • description (type: String)
  • type (type: String (Query | Mutation | Subscription), required)
  • requestSchema (type: Any)
  • requestSample (type: Any)
  • requestTypeName (type: String)
  • requestBaseBody (type: Any) - This body will be merged with the request body sent with the underlying HTTP request
  • responseSchema (type: Any)
  • responseSample (type: Any)
  • responseTypeName (type: String)
  • argTypeMap (type: JSON)
  • pubsubTopic (type: String, required)
  • deprecated (type: Boolean) - If true, @deprecated will be added to the field definition
• ignoreErrorResponses (type: Boolean)
• queryParams (type: Any)
• queryStringOptions (type: Object):
  • indices (type: Boolean) - When arrays are stringified, by default they are not given explicit indices: a=b&a=c&a=d You may override this by setting the indices option to true: a[0]=b&a[1]=c&a[2]=d
  • arrayFormat (type: String (indices | brackets | repeat | comma)) - You can configure how to format arrays in the query strings.

Note: when using arrayFormat set to ‘comma’, you can also pass the commaRoundTrip option set to true or false, to append [] on single-item arrays, so that they can round trip through a parse.

• commaRoundTrip (type: Boolean) - Even if there is a single item in an array, this option treats them as arrays (default: false)
• jsonStringify (type: Boolean) - Stringify the nested objects as JSON (default: false)
• timeout (type: Int) - Timeout for the HTTP request in milliseconds