#Schema as code

#Overview

Schema as code is a feature in the Management API and Management SDK that lets you generate code for your existing project schema. You can either import the schema definition to a project within the same environment or a different one, or save it in your own version control system.

#How do you extract project schema as code?

#1. Get the environment name

First, you need the environment name. For this query, you need to provide the project ID. You can find the Project ID in Project settings or in the project URL - https://app.hygraph.com/<projectId>/<environmentId>/.

The query to the ManagementApi looks like this:

query MyQuery {
  viewer {
    project(id: "<your-project-id>") {
      environments {
        name
        id
      }
    }
  }
}

#2. Generate schema as code

After getting the environment name, generate the project schema as code.

query schemaAsCode {
  viewer {
    project(id: "<your-project-id>") {
      environment(name: "<your-environment-name>") {
        schemaDefinition
      }
    }
  }
}

The response lists the complete project schema definition in the specified environment. You can now save this schema definition in your version control system, or import the schema in another project.

#3. (Optional) Import schema to another project

In Studio, navigate to the project that you want to import the schema. This project can be in the same or a different environment. In the API Playground, use the API selector dropdown to select the Management API.

Here's an example mutation in the ManagementApi. You can find the target environment ID by using the first query in this document.

mutation ApplySchemaDefinitionMutation(
  $schemaDefinition: [BatchMigrationChangeInput!]!
) {
  submitBatchChanges(
    data: { environmentId: "<your-environment-id>", changes: $schemaDefinition }
  ) {
    migration {
      id
      status
    }
  }
}

In the above example, $schemaDefinition is the environment variable with the value equal to the schemaDefinition object from the second query in this document. This can be supplied like so:

#Supported schema elements

The following schema elements are supported:

• Models
• Components
• Locales
• Simple fields
• Conditional visibility in fields
• Relational fields
• Enumerations
• Enumerable fields
• Initial values in enumeration fields
• Stages
• Union fields
• Apps
• Custom renderers and app fields
• Sidebar elements
• Remote fields
• Remote type definitions
• Remote sources

#Limitations

Note the following limitations when using schema as code.

#Existing schema in new project

Importing a schema in a project is an additive process. This means that the existing project schema is not replaced, nor is it merged. You need to ensure that the schema does not contain any existing entities with the same names as those in the new schema. If any such entry exists, your schema import will fail.

#Remote Sources with OAuth

If a remote source uses OAuth authentication, the code will exclude the clientSecret. You must manually add the actual secret before importing the new schema.

You must manually replace CLIENT_SECRET with your actual secret before applying the batch mutation.

So, for instance, this:

"clientSecret": "CLIENT_SECRET",

Would turn into this:

"clientSecret": "23sad-129132", //actual secret value