A schema specifies the shape of data exchanged by an application. For a GraphQL service, it is the contract clients follow: it defines types, fields, and operations. It does not dictate where the data is stored; an API can use in-memory structures, a database, or multiple sources. section 4.4 section 4.5.3
A practical code-first route starts with Java model classes. SmallRye GraphQL translates them and annotated service methods into a GraphQL schema. In an inventory service, a Java class supplies car fields, while a query returns a list of cars and a mutation registers one. The initial inventory can remain in memory while the API takes shape. section 4.5.1 section 4.4
Read the generated GraphQL contract at http://localhost:8083/graphql/schema.graphql:
- The Query and Mutation root types list operations, their parameters, and their return types. section 4.5.3
- An output type and an input type are distinct, even when both are generated from the same Java class. section 4.5.3
- Square brackets denote a collection; an exclamation mark denotes a required, non-null value, barring an error on output. section 4.5.3
Listing 4.25 The GraphQL schema of the Inventory service
type Car {
id: BigInteger
licensePlateNumber: String
manufacturer: String
model: String
}
"Mutation root"
type Mutation {
register(car: CarInput): Car
remove(licensePlateNumber: String): Boolean!
}
"Query root"
type Query {
cars: [Car]
}
input CarInput {
id: BigInteger
licensePlateNumber: String
manufacturer: String
model: String
}
Inspect the generated schema to see the operation roots, separate input and output types, and type notation together. section 4.5.3
The schema also helps clients compose requests. GraphiQL suggests available operations and fields from its type information. A client can request only selected car fields; removing a field from the query removes it from the JSON result. section 4.5.2
Protocol Buffers uses a different schema workflow. A proto file declares each message field’s type, name, and order. Compiling it produces language-specific representation and serialization code. The inventory example uses proto3 and Java options; its binary messages are compact but not human-readable. section 4.6.2
Listing 4.31 Describing the Car model using Protocol Buffers
syntax = "proto3";
option java_multiple_files = true;
option java_package = "org.acme.inventory.model";
option java_outer_classname = "InventoryProtos";
package inventory;
message Car {
string license_plate_number = 1;
string manufacturer = 2;
string model = 3;
int64 id = 4;
}
Use the proto declaration to compare its explicitly numbered message fields with the GraphQL schema generated from Java. section 4.6.2
