Managing a Schema

Once you've defined your schema, you can implement it in Descope using either the Console or programmatically via SDKs and APIs.

Managing Schemas in the Console

The easiest way to create and manage schemas is through the Descope Console. Navigate to the Authorization page and select the FGA tab.

From the FGA tab, you can:

Create new schemas - Start from scratch or use a template
Edit existing schemas - Modify your schema directly in the editor
Delete schemas - Remove schemas and all associated relations

The Console provides a visual editor where you can write your schema in DSL format, validate it, and save it directly to your project.

Managing Schemas with SDKs and APIs

To implement a schema programmatically, you can create a YAML or JSON file that defines the schema and make a saveSchema call via API or SDK. Or, use the other schema management functions to create, update, and delete schemas, namespaces, and relation definitions.

Install SDK

Terminal

npm i --save @descope/node-sdk

Import and initialize Management SDK

import DescopeClient from '@descope/node-sdk';
 
const managementKey = "xxxx"
 
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize a custom domain within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

Save (create or update) a schema

The saveSchema function allows for creation or updating of a schema. If the schema already exists, the upgrade parameter determines whether the existing schema will be overwritten entirely.

This code shows how to save the schema defined in a given file (YAML/JSON). An example of this schema file can be found in the Define Schema page.

const schema = `<schema>`;
await descopeClient.management.fga.saveSchema(schema);

Delete a schema

The deleteSchema function deletes an existing schema, including all relations.

await descopeClient.management.fga.deleteSchema()

Load a schema

The loadSchema function returns the current project's schema.

// Note: loadSchema may be available through the fga namespace
const schema = await descopeClient.management.fga.loadSchema();

Dry run a schema

The dryRunSchema function validates a schema without saving it and returns what would be deleted from the current schema. This is useful for testing schema changes before applying them.

// Dry run a schema to see what would be deleted
// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
 
dryRunResponse, err := descopeClient.Management.FGA().DryRunSchema(ctx, schema)
if err != nil {
    // handle error
}
 
// dryRunResponse contains information about what would be deleted
// This allows you to review changes before applying them

Delete a namespace

The deleteNamespace function deletes a specific namespace and all related relations. This operation cannot be undone.

# Delete a namespace
# Args:
# name (str): namespace name to delete
# schema_name (str): optional, can be used to track the current schema version
# Legacy Authz interface - not recommended for new code
descope_client.mgmt.authz.delete_namespace("doc", schema_name="")

Was this helpful?

On this page