Schema language
Last update: Tue Sep 12 2023 00:00:00 GMT+0000 (Coordinated Universal Time)
CREATED FOR:
- Beginner
- Intermediate
- Developer
This is part 4 of the series for GraphQL and ÃÛ¶¹ÊÓƵ Commerce. The queries and mutations used rely on a specific data graph being implemented at the server, which the GraphQL runtime consumes and uses to resolve the query. The GraphQL specification defines an agnostic language for expressing the types and relationships of your data graph.
The queries and mutations that we are sending to GraphQL endpoints and the fields and arguments that we’re including in our requests obviously must match a schema or data graph that exists on the endpoint on the server that we are making requests to. And so the last thing to talk about here is the type or schema definition language that the GraphQL specification defines that can be easily used to define the hierarchy of types defining the schema at your server. In ÃÛ¶¹ÊÓƵ Commerce, there are files in the Etsy directory of individual modules called schema.graphqls that contain expressions in this schema definition language for defining all of the different types of data that are available in ÃÛ¶¹ÊÓƵ Commerce’s GraphQL coverage. Now there are some things that are specific to ÃÛ¶¹ÊÓƵ Commerce that are thrown into that language in those schema definition files in those modules. We are just going to look at the very basics of the GraphQL definition language. Here’s an example of the GraphQL type definition language. And we see that it mostly consists of defining types and the fields that are applicable to them with each field also defining what its type is and also defining any arguments it has and their types. Wherever the type of a field or argument is another complex type rather than a scalar type then we simply need a definition for that type and so on and so on until we get down to scalar types and have a complete data graph or schema definition. So what we’re looking at here are the hypothetical types that would be required for the queries and mutations that we’ve looked at or in actuality these are the real type names that exist in the ÃÛ¶¹ÊÓƵ Commerce schema just very stripped down. So we’ve reduced these to the fields and the arguments relevant to the query and mutation that we saw. So we saw the categories query to which we were passing the argument filters which has a name subfield which is of a type that itself has a subfield match to which we were passing the search value that we wanted to match for categories. And we see here that for the root query type we have a field called categories that returns a certain complex type as its result and has an argument called filters which itself has a type category filter input. That type definition is up here and we can see that the name field has its own type and we find the type for filter match type input with its own definition here and there’s that match field where we finally get down to a scalar type string. So this is basically how the type definition works. We basically just define types and their fields and arguments and we continue to define types until we get down to the branches of the tree that have scalar type definitions. So that’s a bird’s eye overview of GraphQL queries and mutations and the type definition language but there’s tons more to learn here and so you will want to read more extensively on the GraphQL documentation site on ÃÛ¶¹ÊÓƵ Experience League and developer.adobe.com and you can also check out the course and training videos that we have available for GraphQL at SwiftDaughter.com.
Example schema
Here is an abbreviated type schema that supports the queries and mutations you’ve looked at so far:
input FilterMatchTypeInput {
match: String
}
type Money {
value: Float
}
type Country {
id: String
full_name_english: String
}
interface ProductInterface {
sku: String
name: String
related_products: [ProductInterface]
}
type CategoryFilterInput {
name: FilterMatchTypeInput
}
type CategoryProducts {
items: [ProductInterface]
}
type CategoryTree {
name: String
products(pageSize: Int, currentPage: Int): CategoryProducts
}
type CategoryResult {
items: [CategoryTree]
}
type Products {
items: [ProductInterface]
}
type Query {
country (id: String): Country
categories (filters: CategoryFilterInput): CategoryResult
products (search: String): Products
}
input CartItemInput {
sku: String!
quantity: Float!
}
type CartPrices {
grand_total: Money
}
type Cart {
prices: CartPrices
total_quantity: Float!
}
type AddProductsToCartOutput {
cart: Cart!
}
type Mutation {
addProductsToCart(cartId: String!, cartItems: [CartItemInput!]!): AddProductsToCartOutput
}
You can delve into to learn about the details of the type system, including syntax for some concepts not represented here. The above example, however, is self-explanatory. (Also, note how similar the syntax is to query syntax.) Defining a GraphQL schema is simply a matter of expressing the available arguments and fields of a given type, along with the types of those fields. Each complex field type must itself have a definition, and so on, through the tree, until you get to simple scalar types like String.
The input declaration is in all respects like a type but defines a type that can be used as input for an argument. Also note the interface declaration. This serves a function more or less the same as interfaces in PHP. Other types inherit from this interface.
The syntax [CartItemInput!]! looks tricky but is fairly intuitive in the end. The ! inside the bracket declares that every value in the array must be non-null, while the one outside declares that the array value itself must be non-null (for example, an empty array).
The logic for how data is fetched and formatted according to a schema, and how such logic is mapped to particular types, is up to the GraphQL runtime implementation. Implementations, however, should follow a conceptual flow that makes sense in light of an understanding around nested fields: A resolve operation associated with the root Query or Mutation type is performed, which examines each field specified in the request. For each field that resolves to a complex type, a similar resolve is done for that type, and so on, until everything has resolved into scalar values.
