--- title: Objects description: Define GraphQL object types from your application's data. --- We'll define a GraphQL type for a giraffe, using a TypeScript interface to describe its data. ### Defining an Object type Create `schema.ts` with a builder and a reference for the `Giraffe` type: playground-examples/objects/schema.ts#model The interface describes the **backing model**: the data returned by resolvers for this type. `objectRef` associates that model with the GraphQL name `Giraffe`. We can use the ref when defining fields that return a giraffe. ### Add some fields Next, call `implement` to define the object's fields. It accepts the options for the object type, including an optional description: playground-examples/objects/schema.ts#fields The `fields` function receives a field builder, usually named `t`. Here, `t.exposeString('name')` reads the `name` property from the backing model. The `height` field reads `heightInMeters`, giving that property a different name in the GraphQL schema. For `birthYear`, we write a resolver that computes an integer from the giraffe's birthday. Pothos infers the resolver's first argument as `Giraffe` from the ref. The backing model and GraphQL fields can have different shapes. Clients can query `name`, `height`, and `birthYear`; `birthday` is available to resolvers but isn't exposed as a field. We can add computed fields without adding properties to the backing model. The [fields guide](./fields) covers more field options. For a smaller example of mapping data to a different API shape, try [converting a stored height in meters to feet](/playground?example=foundations-overview). ## Add a query Add a field to the root `Query` type that returns a giraffe, then build the schema: playground-examples/objects/schema.ts#query The `type: GiraffeRef` option tells Pothos to check that the resolver returns data matching the `Giraffe` interface. That returned object becomes the first argument to the resolvers for `name`, `height`, and `birthYear`. You can run this schema immediately with a Playground action above. To run it in your own application, add the server below. ### Create a server `builder.toSchema()` builds a standard `GraphQLSchema`. To serve it with `graphql-yoga`, install `graphql-yoga` and save this as `server.ts` alongside `schema.ts`: ```typescript import { createServer } from 'node:http'; import { createYoga } from 'graphql-yoga'; import { schema } from './schema'; const yoga = createYoga({ schema }); const server = createServer(yoga); server.listen(3000); ``` ### Query your data Run `npx tsx server.ts`, then open [http://localhost:3000/graphql](http://localhost:3000/graphql) and run this query: ```graphql playground example="objects" query { giraffe { name birthYear height } } ``` The result is: ```json { "data": { "giraffe": { "name": "James", "birthYear": 2012, "height": 5.2 } } } ``` ## Different ways to define Object types This guide uses object refs with a TypeScript interface. You can also use an existing class or register backing models by name on the builder. These forms can be used together in the same schema. playground-examples/objects/schema.ts#model,fields playground-examples/objects/variant-classes/schema.ts#definition playground-examples/objects/variant-builder-types/schema.ts#definition ### Using Refs You can create and implement a ref in one expression: playground-examples/objects/variant-inline-refs/schema.ts#fields For types that reference each other, TypeScript may need ref creation and `implement` to be separate statements, as in the walkthrough above. See [circular references](./circular-references) for details. You can also pass a ref to `builder.objectType(GiraffeRef, { ... })` with the same options. ### Using classes If your app already represents its data with classes, prefer using those classes as backing models. Pass the class to `builder.objectType`: its instance type becomes the backing model, and the class itself can be used as a field's `type`: The Classes tab shows this definition. Its playground uses `type: Giraffe` in the query field and returns a `new Giraffe(...)` instance. The `name` option supplies the GraphQL type name. When resolving an [interface](./interfaces) or [union](./unions), you can also use an explicit `isTypeOf: (value) => value instanceof Giraffe` option to identify instances of the class. ### Using SchemaTypes You can declare backing models in `SchemaTypes` and pass it to `SchemaBuilder`. This lets you reference object types by their GraphQL names instead of importing refs. Using the `Giraffe` interface from above: The SchemaTypes tab shows the registration. Its playground uses `type: 'Giraffe'` in the query field. The `Objects` mapping tells Pothos which backing model belongs to each name. Here, it types the `Giraffe` field resolvers and checks the object returned by the `giraffe` query. You still define the GraphQL fields with `builder.objectType`; declaring a backing model doesn't expose its properties. The [SchemaBuilder guide](./schema-builder) covers the other type settings.