Skip to main content

Schema Import/Export

TakeShape schemas can be exported to a JSON file, directly edited, and imported back into a project.

For expert users, this is the best way to add advanced functionality like custom queries and shape fields using external services. For novice users, this is a great way to explore the inner workings of your TakeShape project.


You can export your project schema as a JSON file from the web client, from the CLI, or from the API.

From the web client

To export from the web client, go to the Schema tab of a project. In the top right of the Schema page, you'll find a button to export your current schema version. Selecting this will trigger a download of your schema in JSON format.

You can also export any previous version of your schema from the Schema History page. Learn more about the Schema History in our guide on the subject.

From the CLI

You can also export your schema using the takeshape CLI.

First, you'll want to make sure you have the CLI installed and have a folder to export to:

npm i -g @takeshape/cli

Next, change directories into a folder dedicated to your TakeShape project. Enter the following commands into your terminal:

mkdir my-takeshape-project
cd my-takeshape-project

Then, you'll need to connect with the project you want to get the schema for. This will add a few files to your directory.

takeshape login
takeshape link

The above commands should start a login flow in your default browser. After successfully logging in, you should see a success message in the terminal. If this fails, try logging in directly from the CLI by using the --cliLogin flag.

takeshape login --cliLogin
takeshape link

Finally, run the command to export your schema. You may optionally provide an output path for it to download to.

From the API

You can export a complete schema file by sending a GET request to the{projectId}/schema endpoint. The response body will contain the JSON schema.

Learn more about the schema API by reading our schema API reference.


When importing a project schema, it'll first be validated. If it passes validation, it will be saved to your project as the current schema version.

There's currently no way to import a project schema from the web client---this must be done using the CLI or the API.

From the CLI

First, you'll want to make sure you have the takeshape CLI installed and you've initialized a directory with your TakeShape project.

# Install the CLI
npm i -g @takeshape/cli
# Create and init a project folder
mkdir my-project-folder
cd my-project-folder
takeshape login && takeshape link

You can use the schema-upload CLI command to import your schema file. You'll need to specify which file to upload using the --file flag:

takeshape import --schema --from schema.json

As long as your schema validates, the upload will succeed and your project will be updated.

From the API

You can import a complete schema file to a project by sending a POST request to the{projectId}/schema endpoint with the project schema as the request body. The schema will be validated and, if valid, saved to the project.

Learn more about the schema API by reading our schema API reference guide.

Still need help? Get in touch with us.