GraphQL Configuration Formats

The Tailcall CLI's check command enables the conversion of configuration files between three supported formats: gql or graphql, yml or yaml, and json, with graphql set as the default format.

The three formats, GraphQL, YAML, and JSON, are supported due to their distinct advantages. GraphQL is chosen for its ability to clearly define types and their relationships. YAML and JSON are included for their widespread use in platform tools, with JSON also favored for its role as a transport format, allowing configurations to be auto generated and exposed as APIs for consumption by the GraphQL server.

Converting Formats

To convert files between different formats, use the following command:

tailcall check format_type < input_files > --format

Let's try to convert a Tailcall graphql file to json and then back to graphql

To convert graphql to json

tailcall check examples/jsonplaceholder.graphql --format json > "examples/jsonplaceholder.json"

Now to convert back to graphql

tailcall check examples/jsonplaceholder.json --format graphql > "examples/jsonplaceholder2.graphql"

To learn more about writing configuration to leverage the full power of Tailcall, explore the Directives documentation.

Format Conversions

graphql

schema @server(port: 8000, hostname: "0.0.0.0") @upstream(httpCache: 42, batch: {delay: 100}) {
  query: Query
}

type Query {
  posts: [Post] @http(url: "http://jsonplaceholder.typicode.com/posts")
  users: [User] @http(url: "http://jsonplaceholder.typicode.com/users")
  user(id: Int!): User @http(url: "http://jsonplaceholder.typicode.com/users/{{.args.id}}")
}

type User {
  id: Int!
  name: String!
  username: String!
  email: String!
  phone: String
  website: String
}

type Post {
  id: Int!
  userId: Int!
  title: String!
  body: String!
  user: User @call(query: "user", args: {id: "{{.value.userId}}"})
}

yml

server:
  hostname: 0.0.0.0
  port: 8000
upstream:
  httpCache: 42
  batch:
    maxSize: 100
    delay: 100
    headers: []
schema:
  query: Query
types:
  Post:
    fields:
      body:
        type:
          name: String
          required: true
        cache: null
      id:
        type:
          name: Int
          required: true
        cache: null
      title:
        type:
          name: String
          required: true
        cache: null
      user:
        type:
          name: User
        cache: null
      userId:
        type:
          name: Int
          required: true
        cache: null
    cache: null
  Query:
    fields:
      posts:
        type:
          list:
            name: Post
        http:
          url: http://jsonplaceholder.typicode.com/posts
        cache: null
      user:
        type:
          name: User
        args:
          id:
            type:
              name: Int
              required: true
        http:
          url: http://jsonplaceholder.typicode.com/users/{{.args.id}}
        cache: null
      users:
        type:
          list:
            name: User
        http:
          url: http://jsonplaceholder.typicode.com/users
        cache: null
    cache: null
  User:
    fields:
      email:
        type:
          name: String
          required: true
        cache: null
      id:
        type:
          name: Int
          required: true
        cache: null
      name:
        type:
          name: String
          required: true
        cache: null
      phone:
        type:
          name: String
        cache: null
      username:
        type:
          name: String
          required: true
        cache: null
      website:
        type:
          name: String
        cache: null
    cache: null

json

{
  "server": {
    "hostname": "0.0.0.0",
    "port": 8000
  },
  "upstream": {
    "httpCache": 42,
    "batch": {
      "maxSize": 100,
      "delay": 100,
      "headers": []
    }
  },
  "schema": {
    "query": "Query"
  },
  "types": {
    "Post": {
      "fields": {
        "body": {
          "type": {
            "name": "String",
            "required": true
          },
          "cache": null
        },
        "id": {
          "type": {
            "name": "Int",
            "required": true
          },
          "cache": null
        },
        "title": {
          "type": {
            "name": "String",
            "required": true
          },
          "cache": null
        },
        "user": {
          "type": {
            "name": "User"
          },
          "cache": null
        },
        "userId": {
          "type": {
            "name": "Int",
            "required": true
          },
          "cache": null
        }
      },
      "cache": null
    },
    "Query": {
      "fields": {
        "posts": {
          "type": {
            "list": {
              "name": "Post"
            }
          },
          "http": {
            "url": "http://jsonplaceholder.typicode.com/posts"
          },
          "cache": null
        },
        "user": {
          "type": {
            "name": "User"
          },
          "args": {
            "id": {
              "type": {
                "name": "Int",
                "required": true
              }
            }
          },
          "http": {
            "url": "http://jsonplaceholder.typicode.com/users/{{.args.id}}"
          },
          "cache": null
        },
        "users": {
          "type": {
            "list": {
              "name": "User"
            }
          },
          "http": {
            "url": "http://jsonplaceholder.typicode.com/users"
          },
          "cache": null
        }
      },
      "cache": null
    },
    "User": {
      "fields": {
        "email": {
          "type": {
            "name": "String",
            "required": true
          },
          "cache": null
        },
        "id": {
          "type": {
            "name": "Int",
            "required": true
          },
          "cache": null
        },
        "name": {
          "type": {
            "name": "String",
            "required": true
          },
          "cache": null
        },
        "phone": {
          "type": {
            "name": "String"
          },
          "cache": null
        },
        "username": {
          "type": {
            "name": "String",
            "required": true
          },
          "cache": null
        },
        "website": {
          "type": {
            "name": "String"
          },
          "cache": null
        }
      },
      "cache": null
    }
  }
}

Editor Support

To leverage autocomplete and validation for GraphQL configurations, the init command can be used to automatically create .tailcallrc.graphql for GraphQL configurations and .tailcallrc.schema.json for JSON and YAML configurations. These files enhance editor support by providing schema definitions, facilitating faster and error-free configuration.

GraphQL

When you run tailcall init, it creates a .tailcallrc.graphql file containing your GraphQL schema definitions and a .graphqlrc.yml file configured to use this schema. The .graphqlrc.yml file is set up as follows:

schema:
  - "./.tailcallrc.graphql"
  - "./app.graphql"

This file contains the path to the .tailcallrc.graphql file and the path to the main GraphQL configuration file which is app.graphql. This setup allows GraphQL IDE plugins and Language Server Protocols (LSP) to automatically pick up the schema for autocomplete and validation, enhancing your development experience with real-time feedback and suggestions.

JSON & YAML

For JSON or YAML configurations, tailcall init also creates a .tailcallrc.schema.json file. To enable validation and autocomplete in your JSON files, reference the .tailcallrc.schema.json in the $schema attribute at the beginning of your JSON file:

{
  "$schema": "./.tailcallrc.schema.json"
}

This reference enables your IDE to validate and autocomplete using the JSON schema, offering a streamlined configuration process with instant error and typo detection.