---
title: "GraphQL in Apps"
slug: "graphql-in-gladly"
updated: 2025-05-29T18:30:55Z
published: 2025-05-29T18:30:55Z
canonical: "help.gladly.com/graphql-in-gladly"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.gladly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL in Apps

Apps use GraphQL schemas to describe the type signatures of requests and responses.

- **Data Schema (**`data/data_schema.graphql`**)**: Defines the types and fields for data retrieved from external systems via Data Pulls
- **Actions Schema (**`actions/actions_schema.graphql`**)**: Defines the mutations (actions) that can be performed from Gladly

Gladly uses these schemas to understand what data can be displayed and what operations can be performed through the integrated app.

**Example**

```graphql
type Order {
    orderId: String
    orderDate: DateTime
}
```

**GraphQL references**

- [Introduction to GraphQL](https://graphql.org/learn/)

### **GraphQL Directives**

We utilize only the built-in GraphQL directives (`@deprecated`, `@include`, and `@skip`) plus three additional directives below (`@dataType`, `@childIds`, `@parentId`).

#### **Standard**

GraphQL provides several built-in directives that are commonly used in GraphQL schemas. These directives include:

1. `@deprecated` – Indicates that a field or enum value is deprecated and should not be used. It takes an optional reason argument to explain why the field is deprecated.
2. `@include(if: Boolean)` – Conditionally includes a field in the response based on the value of the `if` argument. If `if` is true, the field is included; otherwise, it is omitted.
3. `@skip(if: Boolean)` – Conditionally skips a field in the response based on the value of the `if` argument. If `if` is true, the field is skipped; otherwise, it is included.

These directives allow us to control the shape and content of GraphQL responses based on runtime conditions and deprecation status.

#### **Add-on**

We have added three additional directives for you to use:

- `@dataType` – We use the `@dataType` directive to associate a GraphQL type with a given data type from a data pull in Gladly. For example, below, you will see the GraphQL type GladlyCustomer is associated with the `gladly_customer` Data Pull version `"1.0"`

```javascript
type GladlyCustomer @dataType(name: "gladly_customer", version: "1.0") {
...
}
```

- `@childIds` – This directive specifies how child entities are identified within a parent entity. It typically takes a template as an argument, which is used to construct the unique identifiers of child entities based on the parent entity’s data. For example, `@childIds(template: "{{.productId}}")` might indicate that each child entity’s ID is derived from the `productId` field of the parent entity.
- `@parentId` – This directive identifies the parent entity associated with a child entity. It often takes a template argument as well, which is used to construct the unique identifier of the parent entity based on the child entity’s data. For instance, `@parentId(template: "{{.id}}")` could indicate that the parent entity’s ID is derived from the id field of the child entity.

These directives help establish hierarchical relationships between data types in GraphQL schemas, allowing for structured and efficient data retrieval.

Gladly supports the standard GraphQL data types (Int, Float, String, Boolean, ID) and the following additional types.

| **Data Type** | **Format** | **Description** |
| --- | --- | --- |
| DateTime | String value in ISO8601 date format | DateTime fields can be used in conditionals and can be manipulated. |
| Currency | String representation of currency value (real number) | Representing currency values as a string ensures no loss of precision. Gladly ensures that no precision is lost when manipulating Currency values. |

### Validate and Run GraphQL

1. Once your GraphQL data schema has been written, it is time to validate and test it.
2. Start by running the `vּalidate` command.
3. If your data schema passes validation, please run each GraphQL entry points.

```
appcfg run data-graphql -d success -q customer -s '{"apiToken": "token"}'
```

```
appcfg run data-graphql -d success -q orders -s '{"apiToken": "token"}'
```