What are some GraphQL schema naming best practices?

Question

I'm beginning development on a nontrivial application for which we're considering GraphQL. When working on the initial draft of our schema, I've become a bit paralyzed trying to establish naming conventions that will scale as the product matures. I would really appreciate some insight from anyone who has had to grow a schema and run into, or successfully avoided dead ends or inconsistencies:

Is it generally useful/idiomatic to keep the name "Interface" in the name of an interface? For example, would Profile or ProfileInterface be preferable in a large app?
```
interface ProfileInterface {
  # fields here...
}

type UserProfile implements ProfileInterface {
  # implemented fields here...
}
```

Is it common to specify single-enum values as "constants"?

enum GeoJSONFeatureTypeConstant {
  feature
}

interface GeoJSONFeatureInterface {
  id: ID
  type: GeoJSONFeatureTypeConstant!
  geometry: GeoJSONGeometryInterface!
  properties: GeoJSONProperties
}

Is it best practice to declare all-or-nothing objects as scalar or type, and where is the line drawn between the two? Imagine a Point type that is would typically be represented as an array [x,y]; which would be more idiomadic?
```
scalar Point

type Point {
  x: Float
  y: Float
}
```
Any other best-practices specifically related to naming conventions or type declarations in GraphQL that would be difficult to know without experience.

Thanks in advance!

This question hasn't gained the momentum I would have liked, so I'm going to start posting useful snippets as I find them, which may evolve into an answer of sorts.

Naming input types with Input on the end is a useful convention, because you will often want both an input type and an output type that are slightly different for a single conceptual object.

http://graphql.org/graphql-js/mutations-and-input-types/

Enums: should have their type name in PascalCase, and their value names in ALL_CAPS, since they are similar to constants. source: apollographql.com/docs/guides/schema-design.html — Tanzeel

Unknown Unknown · Accepted Answer · 2017-07-18T15:06:35

I pondered about these same questions and I hope this will be helpful to you.

1. I don't believe that appending Interface at the end of every interface is idiomatic. It is much better to have a descriptive name instead. Consider the example provided in the GraphQL Specification relating to Interfaces. They don't append Interface to any of their types.

2. Enums are only advantageous when there are multiple related values. I don't see how including type is helpful when there is only one possible value. Enum values are also named with all caps and underscores per the GraphQL Specification relating to Enums.

3. If you decided to implement a scalar type then it is up to you to validate the field. In this specific case, providing Point as a type makes the most sense as a Point could be 2-D or 3-D. Defining it as a type is more declarative.

Values such as Date, Email and Url are common examples for scalar types. They provide semantic value and clients will know what to expect from these fields.

Here's the relevant section for custom scalars. Here's an example.

4. You will find this article by Lee Byron helpful.

What are some GraphQL schema naming best practices?

2 Answers