Shapes are the schema objects that structure and store data in your project.
Shapes can be configured from the web client or by directly editing your schema file. Each method provides its own benefits: the web client is fast and easy, but allows for a more limited range of edits; editing the schema files requires more manual work, but allows for much more flexibility and power.
The easiest way to work with shapes in your project is through the TakeShape web client.
From any project, start by visiting the schema page. You'll see a table of shapes in your project, as well as an option to add a new one:
Clicking on any shape or clicking the Add Shape button will open the shape editor. Here, you can customize every aspect of your shape: update its name, change its model type, drag-and-drop new fields into your shape, and edit each field's properties.
When you have built-in services like Shopify connected to your project, you'll also be able to drag in fields and data from the connected service, too!
When you add or edit shapes in the web client, TakeShape will automatically create or update queries and mutations that provide common functionality to your GraphQL API.
When creating a Single type shape, the web client will create a
getShape query and an
updateShape mutation. When creating Multiple
or Taxonomy type shapes, the web client will also create a
getShapeList query, as well as
You can directly edit your project schema to add shapes that work with data inside TakeShape or in connected services. This is the best way to add more complex fields and functionality that's not supported in the TakeShape web client, especially when dealing with connected GraphQL or REST services.
Start by exporting your schema file After editing your schema, you can then upload it to your project using the CLI or API.
All shapes should be added to the
shapes top-level schema object.
Since the schema is designed to be as flat as possible, each shape
should be its own entry in the object. Shapes can be linked from inside
other shapes' properties by using
Shapes also contain their own sub-schema, under the
schema key. This
sub-schema contains a
properties object for each data field in the
In the following example, we'll add a "Product" model shape to our schema that uses data from a connected Shopify service:
First we'll add the basic metadata properties. The object key and
should match, the
id can be any unique string, and the title can be
human readable with spaces and punctuation, if desired.
Next, we set the
model to use the
"type": "multiple" configuration.
This means that in our GraphQL API we will be able to add as many items
as we like that use this shape, and we can query for paginated lists of
this shape's items.
Finally, we start off with a simple shape schema that contains a single
name. We define a
name to tell
TakeShape where it can find the data for this field. We're storing this
field's value in TakeShape's data store, so we map the value to the data
takeshape:local:Product and name the column it will use,
Note: If you decide to change the name of the property later on,
you'll need to keep the
@mapping property the same, otherwise you'll
lose data! You can always change the mapping to a new column, but note
that the column will be empty after we create it.
Next, we'll add fields to support getting remote data from Shopify. To
Product.schema.properties, we'll add:
The first field we're adding will allow us to set a specific Shopify Product ID on each shape item. It also has a validation regex pattern configured to validate data submitted on the field.
The second field is where things get interesting. Rather than define a
@mapping as our field's data source, we're configuring a
on the field. It uses the value of the
shopifyProductId field as an
input argument to a query to a connected Shopify store. The value of
this field will be dynamically resolved whenever we query for a shape,
based on the value of each shape's
We provide a complete spec for shapes and their sub-schemas in the Schema Spec Reference.
- The easiest way to work with Shapes is in the web client. The web client only creates Model Shapes, creates references to other shapes for you, and automatically generates queries and mutations for working with your Shape in the GraphQL API.
- The most powerful way to work with Shapes is by directly editing your schema file. It allows you to specifically configure the data storage for your shape's data and supports dynamic resolution of properties using resolvers.