Skip to main content

Editing your project schema

Your project schema is the heart of your project; it defines what queries you can make and what data you can use.

So it's vitally important to understand how to customize and edit your project schema. This guide will show you how.

The two main ways to edit your project schema are in the Web Client and the CLI. Let's jump into some examples to see how.

Not sure what a schema is? Check out our explanation here.

Finding your schema

To edit your project schema, sign in.

You'll then be asked to either select a project or create a project. Check out our doc on creating a project if you don't have one yet.

Our example will be based off of the Shop starter project.

If you do have a project, once you select it from the menu, you'll be taken to your project dashboard. Select the Schema tab, and you'll be shown your schema in the admin UI, which is just a list of all the shapes in your project.

Now that you know where to find your schema, you can:

Editing shapes from the web client admin UI

If you're not sure what a shape is or why it matters, check out our doc on the subject.. Select the Add Shape button on the Schema page to begin.

To learn more about creating Shapes from the web client, check out our guide on the subject.

For our purposes, we'll just title our shape test, name it Test, and give it a description of test shape. For our built-in data storage option, we'll leave it set to Multiple. Read our doc on the data store to learn more about that option.

Here's what it should look like:

On the left, you may have noticed some options that you can drag and drop onto your shape. Scroll down the central panel of the page until you see the section marked Workflow. You're going to drag the Single Line text element onto this space. It should look like this:

To learn more about this using this editor, check out our doc on working with shapes in the web client.

Now let's edit our single line element. Select on the single line element in the Workflow section near the bottom of the page. Once you select that, you'll set a set of inputs on the right side of your page.

Make the title Single Line. The name should be testLine. The description: Just a test line.

Now at the top you'll see an Update Shape button if you're editing a shape. You'll see a Create Shape button if it's new shape entirely. Select that, and you'll go back to the Shapes page.

You may have to scroll down to find your new shape.

Now select the play button on the right side to go to the API Explorer.

The code should look like this:

API Explorer
{
getTestList {
items {
_id
testLine
}
}
}

Now you have your own query. You can see now how a shape translates to a query.

Unfortunately if you run this query, it will produce an error. This is because your shape does not fetch any specific data and is not connected to an external service.

See our docs on all the services we support if you'd like to pursue that.

To learn about setting up data in our data store, we have a doc for that right here.

If you'd rather edit your schema JSON directly, continue reading below.

Editing shapes in the JSON directly

Editing JSON in the web client

From your project's dashboard, select on the Schema tab up top. You'll see a page with two tabs below the navbar. One says Summary and the other says JSON. Select JSON.

From here, you can edit your schema directly. For mor information on adding queries and mutations to your schema, check out our doc on the subject.

Let's focus on the getCategoryList query to get a basic understanding of how a query corresponds to a shape.

schema editor
"queries": {
"getCategoryList": {
"shape": "PaginatedList<Category>",
"resolver": {
"name": "shapedb:list",
"service": "shapedb",
"options": {"model": "Category"}
},
"description": "Returns a list Category in natural order.",
"args": "TSListArgs<Category>"
},
}

For simplicity's sake, let's focus on the "shape" property, which says PaginatedList<Category>. This is where you assign a shape to a query, and in this case we're using the Category shape as a paginated list. To see the shape, scroll down to that section of your project schema.

Here, you can see how the Category shape matches up with the getCategoryList query.

project schema
"shapes": {
"Category": {
"id": "rk1zbZZBQ",
"name": "Category",
"title": "Category",
"model": {"type": "taxonomy"},
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"title": "Title",
"minLength": 1,
"@mapping": "shapedb:Category.SJibWZWSQ"
}
},
"required": ["title"]
}
}
}

You can learn more about the different properties on the above shape by checking out the schema spec documentation.

Let's focus on the "properties" of the shape, though. Every object within "properties" is a GraphQL property which can be specified when you use the getCategoryList query. Our only defined property is "title", and it is required to run the query.

Select the API tab at the top to be taken to the API Explorer.

In the API Explorer, we're running the query:

API Explorer
query{
getCategoryList{
items{
title
}
}
}

The result we get on the right is:

API Explorer
{
"data": {
"getCategoryList": {
"items": [
{
"title": "Footwear"
},
{
"title": "Shirts"
},
{
"title": "Pants"
},
{
"title": "Outerwear"
}
]
}
}
}

As you can see above, the getCategoryList query receives a paginated list of items, which are each of the Category shape. Each item has a property of title, as defined in the Category shape.

Now you have a rough overview of how shapes can map to queries, which defines the structure of the data you can request and receive.

Let's move on to editing your schema outside of the web client.

Editing the schema in your favorite editor

If you'd rather work with your schema directly in your favorite text editor, you can always select the Export option.

This will allow you to save your JSON to your local machine.

Once you've made your edits, you'll want to import your schema. You could paste your schema into the web client's JSON editor, but we recommend using the CLI or making a POST request to your project's API endpoint.

Your project's API endpoint: api.takeshape.io/project/PROJECT-ID/schema

Substitute your Project ID into the above url. To send the schema, just set your API Key as a Bearer Token in the headers, and assign your updated schema to the body of your request.

Learn more about creating API Keys here.

If you want to get in depth on editing your schema outside of the web client, check out our doc on exporting and importing your schema.

Editing your schema with the CLI

You can also use our CLI to edit your schema. You'll still be using your favorite editor or IDE, but you'll import and export your schema to and from your project in the command line.

Open a terminal in the root directory of a local code base you'd like to use.

First, you'll install the CLI. We recommend installing it globally:

npm install -g @takeshape/cli

Now you need to log into your account. We'll use the CLI's login option.

Logging in through the browser

Enter the following into the terminal

takeshape login

Your default browser will open, and you'll be asked to log in. If all goes well, you should see a screen telling you that the login was successful, and you can close the tab and return to the CLI.

If it failed, you may see a screen that says you've successfully logged in, but we've lost connection with the CLI.

Note

If you're using a browser with plugins that block certain browser permissions, like aggressive adblockers, you may have trouble logging in from the CLI through the browser. This is also the case if you use browsers like Brave, which have built-in tools for blocking certain browser features.

Check out our section below for info on logging in without opening the browser.

Logging in through the terminal

You may be unable to login through the CLI from the browser, or you may not want to. Either way, the CLI has you covered. To log in from the terminal, enter the login command with the below option:

takeshape login --cliLogin

You'll be prompted to enter your account email, and then password. On success, you'll see the message Saving personal access token to C:\Users\your-user-name\.takeshaperc.

Interacting with your project from the CLI

Now that you're logged in, use the link command to link your local environment to the remote project you'd like to work with:

takeshape link

You'll see a list of your projects in the terminal, which you can scroll through. Hit enter when you've selected the project you're interested in.

You'll get .graphqlconfig, takeshape-project.graphql, and .takeshape.src files put into the root of your project.

Now you just run the export command.

takeshape export --schema

And you'll get a lovely schema.json file downloaded to the root directory of your project.

Now all you have to do is edit your schema.json file, and use the import command.

takeshape import --schema --from schema.json

And you're done.

Still need help? Get in touch with us.