alias	foatho8aip
description	An overview of the Graphcool service definition file `graphcool.yml` and its YAML structure.

Service definition: `graphcool.yml`

Overview

The service definition file graphcool.yml has the following root properties:

types: References your type definition file(s).
functions: Defines all the functions you're using in your service.
permissions: Defines all the permission rules for your service.
rootTokens: Lists all the root token you've configured for your service.

The exact structure of graphcool.yml is defined with JSON schema. You can find the corresponding schema definition here.

Example `graphcool.yml` service definition file

Here is a simple example of a service definition file:

# Type definitions
types: ./types.graphql


# Functions
functions:

  # Resolver for authentication
  authenticateCustomer:
    handler:
      # Specify a managed function as a handler
      code:
        src: ./src/authenticate.js
        # Define environment variables to be used in function
        environment:
          SERVICE_TOKEN: aequeitahqu0iu8fae5phoh1joquiegohc9rae3ejahreeciecooz7yoowuwaph7
          STAGE: prod
    type: resolver

  # Operation-before hook to validate an email address
  validateEmail:
    handler:
      # Specify a managed function as a handler; since no environment variables
      # are specified, we don't need `src`
      code: ./src/validateEmail.js
    type: operationBefore
    operation: Customer.create

  # Subscription to pipe a new message into Slack
  sendSlackMessage:
    handler:
      # Specify a webhook as a handler
      webhook:
        url: http://example.org/sendSlackMessage
        headers:
            Content-Type: application/json
            Authorization: Bearer cha2eiheiphesash3shoofo7eceexaequeebuyaequ1reishiujuu6weisao7ohc
    type: subscription
    query: ./src/sendSlackMessage/newMessage.graphql


# Permission rules
permissions:
# Everyone can read messages
- operation: Message.read

# Only authenticated users can create messages
- operation: Message.create
  authenticated: true

# To update a message, users need to be authenticated and the
# permission query in `./permissions/updateMessage.graphql` has
# to return `true`; note that this permission only applies to the
# `text` and `attachments` fields of the `Message` type, no other
# fields may be updated
- operation: Message.update
  authenticated: true
  fields:
    - text
    - attachments
  query: ./permissions/updateMessage.graphql

# To delete a message, users need to be authenticated and
# the permission query in `./permissions/deleteMessage.graphql`
# has to return `true`
- operation: Message.delete
  authenticated: true
  query: ./permissions/deleteMessage.graphql

# Everyone can perform all CRUD operations for customers
- operation: Customer.read
- operation: Customer.create
- operation: Customer.update
- operation: Customer.delete


# You can edit the fields a permission is applied to
- operation: Customer.Read
  fields:
    - firstName
    - lastName

# Only authenticated users can connect a `Message`
# and `Customer` node via the `CustomerMessages`-relation
- operation: CustomerMessages.connect
  authenticated: true

# To disconnect a `Message` from a `Customer` node in the
# `CustomerMessages`-relation, users need to be authenticated and the
# permission query in `./permissions/disconnectCustomerMessages.graphql`
# has to return `true`
- operation: CustomerMessages.disconnect
  authenticated: true
  query: ./permissions/disconnectCustomerMessages.graphql

# Root tokens
rootTokens:
  - rootToken1
  - RootToken2 # can also start with uppercase letters

This service definition expects the following file structure:

.
├── graphcool.yml
├── types.graphql
├── src
│   ├── authenticate.js
│   ├── validateEmail.js
│   └── sendSlackMessage
│       └── newMessage.graphql
└── permissions
    ├── updateMessage.graphql
    └── deleteMessage.graphql

YAML structure

`types`

The types root property accepts a single string or a list of strings. Each string references a .graphql-file that contains GraphQL type definitions written in the SDL.

There are two kinds of types that can be referenced:

Model types: Determine the types that are to be persisted in the database. These types need to be annotated with the @model-directive and typically represent entities from the application domain. Read more in the Database chapter.
Transient types: These types are not persisted in the database but typically represent input or return types for certain API operations.

Examples

Referring to a single type definition file

types: ./types.graphql

`functions`

The functions root property accepts a map from string (which specifies the function's name) to function. The key represents the name of the function, the value is an object that follows the function structure and defines the precise configuration of the function to be invoked.

Definition: `function`

All functions have the following three properties:

type (required)
- Type: string
- Description: Determines whether this function is a resolver, subcription or a hook.
- Possible values: resolver, subscription, operationBefore, operationAfter
handler (required)
- Type: handler (described below)
- Description: Specifies the details of how to invoke the function. Can either contain references to a local file that contains the implementation of the function or otherwise define a webhook that'll be called when the function is invoked.
isEnabled (optional, default: false)
- Type: boolean
- Description: The function will only be invoked if set to true.
- Possible values: true or false

Only resolver functions have the following property:

schema (optional, if not provided, the extension of Query or Mutation has to live inside a file that's referenced from the types root property)
- Type: string
- Description: References a .graphql-file that contains the extension of the Query or Mutation type which defines the API of the resolver.
- Possible values: any string that references a .graphql-file

Only subscription functions have the following property:

query (required)
- Type: string
- Description: References a .graphql-file that contains the subscription query which determines the event upon which the function should be invoked as well as the payload for the event.
- Possible values: any string that references a .graphql-file

Only hook functions have the following property:

operation (required)
- Type: string
- Description: Describes an operation from the Graphcool CRUD API. The value is composed of the name of a model type and the name of an operation (read, create, update or delete), separated by a dot.
- Possible values: <Model Type>.<Operation> (e.g. Customer.create, Article.create, Image.update, Movie.delete)

Definition: `handler`

A handler specifies the details of how to invoke the function. It can either be a managed function that references a local file or otherwise define a webhook that'll be called when the function is invoked.

Define managed function

Managed function structure:

code:
  # source file that contains the implementation of the function
  src: <file>
  # specify environment variables the function has access to
  environment:
    <variable1>: <value1>
    <variable2>: <value2>

Notice that if no environment variables are specified, you can also use the short form without explicitly spelling out src:

code: <file>

A handler for a managed function has the following properties:

code (required)
- Type: map (see managed function structure above)
- Description: Describes all the details about how to invoke the managed function and optionally provides environment variables that can be used inside the function at runtime.
src (required)
- Type: string
- Description: A reference to the file that contains the implementation for the function.
- Possible values: Any string that references a valid source file.
environment (optional)
- Type: [string:string]
- Description: Specifies a number of environment variables .
- Possible values: Any combination of strings that does not contain the empty string.

Reference webhook

Webhook structure:

webhook:
  # HTTP endpoint that represents the webhook
  url: <url>
  # HTTP headers to send along when invoking the webhook
  headers:
    <header1>: <value1>
    <header2>: <value2>

Notice that if no HTTP headers are specified, you can also use the short form without explicitly spelling out url:

webhook: <url>

A handler for a managed function has the following properties:

webhook (required)
- Type: map (see webhook structure above)
- Description: Describes all the details about how to invoke the webhook and optionally specify HTTP headers that will be attached to the request when the webhook is called.
url (required)
- Type: string
- Description: The HTTP endpoint where the webhook can be invoked.
- Possible values: Any string that's a valid HTTP URL and references a webhook.
headers (optional)
- Type: [string:string]
- Description: Specifies a number of HTTP headers.
- Possible values: Any combination of strings that does not contain the empty string.

Examples

functions:

  authenticateCustomer:
    handler:
      # Specify a managed function as a handler
      code:
        src: ./src/authenticate.js
        # Define environment variables for function
        environment:
          SERVICE_TOKEN: aequeitahqu0iu8fae5phoh1joquiegohc9rae3ejahreeciecooz7yoowuwaph7
          STAGE: prod
    type: resolver

  # Operation-before hook to validate an email address
  validateEmail:
    handler:
      # Specify a managed function as a handler; since no environment variables
      # are specified, we don't need `src`
      code: ./src/validateEmail.js
    type: operationBefore
    operation: Customer.create

  # Subscription to pipe a new message into Slack
  sendSlackMessage:
    handler:
      # Specify a webhook as a handler
      webhook:
        url: http://example.org/sendSlackMessage
        headers:
            Content-Type: application/json
            Authorization: Bearer cha2eiheiphesash3shoofo7eceexaequeebuyaequ1reishiujuu6weisao7ohc
    type: subscription
    query: ./src/sendSlackMessage/newMessage.graphql

`permissions`

The permissions root property accepts a list of permissions. To see a practical example of the Graphcool permission system, check out this example service.

Definition: `permission`

All permissions have the following four properties:

operation (required)
- Type: string
- Description: Specifies for which API operation this permission holds. Refers to an operation from the Graphcool CRUD API. The value is composed of the name of a model type and the name of an operation (read, create, update or delete), separated by a dot.
- Possible values: <Model Type>.<Operation> (e.g. Customer.create, Article.create, Image.update, Movie.delete)
authenticated (optional, default: false)
- Type: boolean
- Description: If set to true, only authenticated users will be able to perform the associated operation.
- Possible values: true or false
query (optional)
- Type: string
- Description: References a file that contains a permission query.
- Possible values: Any string that references a .graphql-file containing a permission query.
fields (optional)
- Type: [string]
- Description: References a list of fields the permission is applied to. Only applicable for type permissions.
- Possible values: A list of any string that references a field of the type the permission belongs to.

Examples

permissions:
# Everyone can read messages
- operation: Message.read

# Only authenticated users can create messages
- operation: Message.create
  authenticated: true

# To update a message, users need to be authenticated and the
# permission query in `./permissions/updateMessage.graphql` has
# to return `true`; note that this permission only applies to the
# `text` and `attachments` fields of the `Message` type, no other
# fields may be updated
- operation: Message.update
  authenticated: true
  fields:
    - text
    - attachments
  query: ./permissions/updateMessage.graphql

# To delete a message, users need to be authenticated and
# the permission query in `./permissions/deleteMessage.graphql`
# has to return `true`
- operation: Message.delete
  authenticated: true
  query: ./permissions/deleteMessage.graphql

# Everyone can perform all CRUD operations for customers
- operation: Customer.read
- operation: Customer.create
- operation: Customer.update
- operation: Customer.delete


# You can edit the fields a permission is applied to
- operation: Customer.Read
  fields:
    - firstName
    - lastName

# Only authenticated users can connect a `Message`
# and `Customer` node via the `CustomerMessages`-relation
- operation: CustomerMessages.connect
  authenticated: true

# To disconnect a `Message` from a `Customer` node in the
# `CustomerMessages`-relation, users need to be authenticated and the
# permission query in `./permissions/disconnectCustomerMessages.graphql`
# has to return `true`
- operation: CustomerMessages.disconnect
  authenticated: true
  query: ./permissions/disconnectCustomerMessages.graphql

`rootTokens`

The rootTokens property accepts a list of strings. Each string is the name of a root token which will be created whenever the service deployed.

Examples

rootTokens:
  - rootToken1
  - RootToken2 # can also start with uppercase letters

Using variables

Variables allow you to dynamically replace configuration values in your service definition file.

They are especially useful when providing secrets for your service and when you have a multi-staging developer workflow.

To use variables inside graphcool.yml, you need to reference the values enclosed in ${} brackets:

# graphcool.yml file
yamlKeyXYZ: ${variableSource} # see list of current variable sources below
# this is an example of providing a default value as the second parameter
otherYamlKey: ${variableSource, defaultValue}

A variable source can be either of the following two options:

A recursive self-reference to another value inside the same service
An environment variable
An option from the command line

Note that you can only use variables in property values - not in property keys. So you can't use variables to generate dynamic logical IDs in the custom resources section for example.

Recursive self-reference

You can recursively reference other property values that live inside the same graphcool.yml file.

When using a recursive self-reference as a variable, the value that you put into the bracket is composed of:

the prefix self:
(optional) the path to the referenced property

If no path is specified, the value of the variable will be the full YAML file.

In the following example, the createCRMEntry function uses the same subscription query as the sendWelcomeEmail function:

functions:
  sendWelcomeEmail:
    handler:
      code:
        src: ./src/sendWelcomeEmail.js
    type: subscription
    query: ./src/newUserSubscription.graphql
  createCRMEntry:
    handler:
      code:
        src: ./src/createCRMEntry.js
    type: subscription
    query: ${self:functions.sendWelcomeEmail.handler.query}

Environment variable

You can reference environment variables inside the service definition file.

When using an environment variable, the value that you put into the bracket is composed of:

the prefix env:
the name of the environment variable

In the following example, an environment variable is referenced to specify the URL and the authentication token for a webhook:

functions:
  initiatePayment:
    handler:
      webhook:
        url: ${env:PAYMENT_URL}
        headers:
            Content-Type: application/json
            Authorization: Bearer ${env:AUTH_TOKEN}
    type: subscription

CLI options

You can reference CLI options that you passed when invoking a graphcool command inside your graphcool.yml service definition file.

When referencing a CLI option, the value that you put into the bracket is composed of:

the prefix opt:
the name of the CLI option

Note: It is valid to use the empty string as the name of the CLI option. This looks like ${opt:} and the result of declaring this in your graphcool.yml is to embed the complete options object (i.e. all the command line options from your graphcool command).

For the following example, assume the following graphcool command was just ran in the terminal:

graphcool deploy --stage prod

To reference the value of the stage option inside graphcool.yml, you can now specify the following:

webhook:
  url: http://myapi.${opt:stage}.com/example

When the command is invoked, the value of webhook.url will be deployed as http://myapi.prod.com/example.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Service definition: `graphcool.yml`

Overview

Example `graphcool.yml` service definition file

YAML structure

`types`

Examples

`functions`

Definition: `function`

Definition: `handler`

Define managed function

Reference webhook

Examples

`permissions`

Definition: `permission`

Examples

`rootTokens`

Examples

Using variables

Recursive self-reference

Environment variable

CLI options

FilesExpand file tree

02-graphcool.yml.md

Latest commit

History

02-graphcool.yml.md

File metadata and controls

Service definition: graphcool.yml

Overview

Example graphcool.yml service definition file

YAML structure

types

Examples

functions

Definition: function

Definition: handler

Define managed function

Reference webhook

Examples

permissions

Definition: permission

Examples

rootTokens

Examples

Using variables

Recursive self-reference

Environment variable

CLI options

Service definition: `graphcool.yml`

Example `graphcool.yml` service definition file

`types`

`functions`

Definition: `function`

Definition: `handler`

`permissions`

Definition: `permission`

`rootTokens`