Skip to main content

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​

schema
  @server(port: 8000, hostname: "0.0.0.0")
  @upstream(baseURL: "http://jsonplaceholder.typicode.com", httpCache: 42, batch: {delay: 100}) {
  query: Query
}

type Query {
  posts: [Post] @http(path: "/posts")
  users: [User] @http(path: "/users")
  user(id: Int!): User @http(path: "/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}}"})
}

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.