Implementing a Schema

To implement a schema, you can simply 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 CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}
 
// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

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.

// An example of saving the schema defined in a given file (yaml/JSON)
const file = fs.readFileSync(option.input, 'utf8'); // Read the file
const schema: AuthzSchema = JSON.parse(file); // Parse the file into a schema object
const upgrade = false; // Don't delete existing parts of the schema that are not specified in the inputted yaml file
 
await descopeClient.management.authz.saveSchema(schema, upgrade);

Delete a schema

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

await descopeClient.management.authz.deleteSchema()

Load a schema

The loadSchema function returns the current project's schema.

const schema: AuthzSchema = await descopeClient.management.authz.loadSchema();

Save (create or update) a namespace

The saveNamespace function allows for creation or updating of a namespace. An oldName can be passed in as a parameter to overwrite an existing namespace. schemaName is also optional and allows for setting of the schema name.

const namespace: AuthzNamespace = [namespace];
const oldName = "oldname"
const schemaName = "schemaName"
 
await descopeClient.management.authz.saveNamespace(namespace);

Delete a namespace

The deleteNamespace function deletes a namespace. schemaName is optional to track schema version.

const name: string = "name";
const schemaName: string = "schemaName";
 
await descopeClient.management.authz.deleteNamespace(namespace);

Save (create or update) a relation definition

The saveRelationDefinition function creates or updates a relation definition. The namespace parameter is required and corresponds to the namespace the relation definition is being added to. oldName and schemaName are optional and used to update an existing relation definition and track schema version respectively.

const relationDefinition: AuthzRelationDefinition = [relationDefinition];
const namespace: string = "namespace";
const oldName: string = "oldName";
const schemaName: string = "schemaName";
 
await descopeClient.management.authz.saveRelationDefinition(relationDefinition, namespace);

Delete a relation definition

The deleteRelationDefinition function deletes a specified relation definition.

const name: string = "name of relation definition";
const namespace: string = "namespace relation definition is a part of";
const schemaName: string = "schemaName";
 
await descopeClient.management.authz.deleteRelationDefinition(name, namespace)

We'll move on to creating relations.

Was this helpful?