# GraphQL Naming Conventions

This document describes the GraphQL's Naming Conventions

## Case styles

* **Field names** should use `camelCase`. Many GraphQL clients are written in JavaScript, Java, Kotlin, or Swift, all of which recommend camelCase for variable names.
* **Type names** should use `PascalCase`. This matches how classes are defined in the languages mentioned above.
* **Enum names** should use `PascalCase`.
* **Enum values** should use `ALL_CAPS`, because they are similar to constants.

### Examples

```graphql
type Dog {
  id: String!
}

query DogQuery {
  dog {
    id
  }
}

enum Animal {
  DOG
  CAT
}
```

## Input objects naming conventions

Use a single, required, unique, input object type as an argument for easier execution on the client.

```graphql
query DogQuery {
  dog(input: DogQueryInput!) {
    id
  }
}

mutation PetDogMutation {
  petDog(input: PetDogInput!) {
    id
  }
}
```

## Query naming conventions

GraphQL is about asking for specific fields on objects, therefore it's essential that the query has exactly the same shape as the result. Naming queries the same as the type will help with that:

```graphql
query {
  dog {
    id
  }
}
```

will result in:

```graphql
data {
  dog {
    id
  }
}
```

You can make a sub-selection of fields for that object. GraphQL queries can traverse related objects and their fields.

```graphql
query {
  dog {
    id
    owner {
      id
    }
  }
}
```

### Fetching array of items

GraphQL list queries work quite differently from single field queries. We know which one to expect based on what is indicated in the schema, which will be denoted by a `plural` name.

The pagination structure should follow a simplified version of the Relay's connection pattern.

```graphql
query {
  dog {
    id
    owners(first: 10, after: $endCursor) {
      count
      items {
        id
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

## Mutation naming conventions

Make mutations as specific as possible. Mutations should represent semantic actions that might be taken by the user whenever possible.

Name your mutations verb first. Then the object, or “noun,” if applicable; `createAnimal` is preferable to `animalCreate`.

```graphql
mutation {
  createAnimal(input: CreateAnimalInput!) {
    id
  }
}
```

## Integrating naming conventions into shared api

**Now for the hard part!**

Since all of our `resolvers` will be merged into a shared `api`, we need to come up with a system to avoid overwriting previous resolvers. Let's take this example to understand the problem better.

We have two projects, `ProjectX` and `ProjectY`. Both of these projects need to query a `user`, but the user type references a different resource.

1. `ProjectX`'s resolvers are merged first with the `user` query that fetches users from the `National Registry`.
2. `ProjectY`'s resolvers are merged after with the `user` query that fetches users from the `RSK`.

Here the `ProjectY`'s user query will overwrite the `ProjectX`'s query and will break `ProjectX`.

### Solution

We need to prefix all `Mutations`, `Queries`, `Types`, `Scalars`, etc. with the name of the module that is merged into the `api`.

Mutations should still follow the verb first rule. Then the module name, following the object, or “noun,” if applicable.

#### Exception to the solution

If the name of the GraphQL type/query/mutation is the same as the module, then we don't need the prefix.

#### Example

```graphql
type ProjectXUser {
  id: String!
}

query {
  projectXUser {
    id
  }
}

mutation {
  createProjectXUser {
    id
  }
}
```

```graphql
# here we are working in the identity module, thus we won't name our type IdentityIdenty. Same exception applies for query/mutation

type Identity {
  id: UUID!
}

query {
  identity {
    id
  }
}

mutation {
  createIdentity {
    id
  }
}
```

## Conclusion

With these design principles you should be equipped to design an effective GraphQL system for your API.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.devland.is/technical-overview/api-design-guide/graphql-naming-conventions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.