Schema
Apply Schema Difference
Update the instance's schema by passing the diff previously retrieved via `/schema/diff` endpoint in the JSON request body or a JSON/YAML file. This endpoint is only available to admin users. Only the operations in the diff are applied, so a diff from a partial snapshot leaves everything outside its scope untouched. The `hash` is always checked against the full schema.
Query Parameters
When true, bypasses the hash check and applies the diff regardless of whether the current schema matches the snapshot it was generated from.
Request Body
Responses
import { createDirectus, rest, schemaApply } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(
schemaApply({
hash: '7d4499bc1e09bab3558b46cc09cd83fea2c05144',
diff: {
collections: [
{
collection: 'articles',
diff: [
{
kind: 'N',
rhs: {
collection: 'articles',
meta: {
accountability: 'all',
archive_app_filter: true,
archive_field: null,
archive_value: null,
collapse: 'open',
collection: 'articles',
color: null,
display_template: null,
group: null,
hidden: false,
icon: null,
item_duplication_fields: null,
note: null,
singleton: false,
sort: null,
sort_field: null,
translations: null,
unarchive_value: null,
},
schema: {
name: 'articles',
},
},
},
],
},
],
fields: [
{
collection: 'articles',
field: 'id',
diff: [
{
kind: 'N',
rhs: {
collection: 'articles',
field: 'id',
type: 'integer',
meta: {
collection: 'articles',
conditions: null,
display: null,
display_options: null,
field: 'id',
group: null,
hidden: true,
interface: 'input',
note: null,
options: null,
readonly: true,
required: false,
sort: null,
special: null,
translations: null,
validation: null,
validation_message: null,
width: 'full',
},
schema: {
name: 'id',
table: 'articles',
data_type: 'integer',
default_value: null,
max_length: null,
numeric_precision: null,
numeric_scale: null,
is_nullable: false,
is_unique: false,
is_primary_key: true,
is_generated: false,
generation_expression: null,
has_auto_increment: true,
foreign_key_table: null,
foreign_key_column: null,
},
},
},
],
},
{
collection: 'articles',
field: 'title',
diff: [
{
kind: 'N',
rhs: {
collection: 'articles',
field: 'title',
type: 'string',
meta: {
collection: 'articles',
conditions: null,
display: null,
display_options: null,
field: 'title',
group: null,
hidden: false,
interface: 'input',
note: null,
options: null,
readonly: false,
required: false,
sort: null,
special: null,
translations: null,
validation: null,
validation_message: null,
width: 'full',
},
schema: {
name: 'title',
table: 'articles',
data_type: 'varchar',
default_value: null,
max_length: 255,
numeric_precision: null,
numeric_scale: null,
is_nullable: true,
is_unique: false,
is_primary_key: false,
is_generated: false,
generation_expression: null,
has_auto_increment: false,
foreign_key_table: null,
foreign_key_column: null,
},
},
},
],
},
],
relations: [],
},
})
);
Retrieve Schema Difference
Compare the current instance's schema against the schema snapshot in JSON request body and retrieve the difference. This endpoint is only available to admin users. Alternatively, upload a JSON or YAML schema file. Does not allow different Directus versions and database vendors by default. You can opt in to bypass these checks by passing the `force` query parameter. Accepts partial snapshots, in which case the diff is scoped to the collections the snapshot references.
Query Parameters
Bypass version and database vendor restrictions.
mirror (default) returns all operations. merge returns an additive diff that excludes deletions.
Request Body
1 for a full snapshot, 2 for a partial snapshot.
Name of the collection. This matches the table name in the database.
Icon displayed in the Data Studio when working with this collection.
Short description displayed in the Data Studio.
How items in this collection should be displayed when viewed relationally in the Data Studio.
Whether or not this collection is hidden in the Data Studio.
Whether or not this collection is treated as a singleton.
How this collection's name is displayed in the different languages in the Data Studio.
What field in the collection holds the archived state.
What value the archive field should be set to when archiving an item.
What value the archive field should be set to when unarchiving an item.
What field holds the sort value on the collection. The Data Studio uses this to allow drag-and-drop manual sorting.
What data is tracked. One of all, activity.
What fields are duplicated during "Save as copy" action of an item in this collection.
What sort order of the collection relative to other collections of the same level.
The name of the parent collection.
What is the default behavior of this collection or "folder" collection when it has nested collections. One of open, closed, locked.
Whether or not Content Versioning is enabled for this collection.
Unique name of the collection this field is in.
Unique name of the field. Field name is unique within the collection.
Any special transform flags that apply to this field.
The interface used for this field.
The interface options configured for this field. The structure is based on the interface used.
The display used for this field.
The configured options for the used display.
If the field is considered readonly in the Data Studio.
If the field is hidden from the edit page in the Data Studio.
Where this field is shown on the edit page in the Data Studio.
How wide the interface is rendered on the edit page in the Data Studio. One of half, half-left, half-right, half-space, full, fill.
How this field's name is displayed in the different languages in the Data Studio.
Short description displayed in the Data Studio.
Indexes defined on system fields.
Unique identifier for the relation.
Collection that has the field that holds the foreign key.
Foreign key. Field that holds the primary key of the related collection.
Collection on the one side of the relationship.
Alias column that serves as the one side of the relationship.
Field on the junction table that holds the many field of the related relation.
Responses
::: details **Toggle Open to See Request**
import { createDirectus, rest, schemaDiff } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(
schemaDiff({
version: version_num,
directus: 'directus_version',
vendor: 'database_type',
collections: [
{
collection: 'collection_name',
meta: {
// Meta fields
},
schema: {
// Schema fields
},
},
],
fields: [
{
collection: 'collection_name',
field: 'field_1_id',
type: 'field_1_type',
meta: {
// Meta fields
},
schema: {
// Meta fields
},
},
{
collection: 'collection_name',
field: 'field_2_id',
type: 'field_2_type',
meta: {
// Meta fields
},
schema: {
// Meta fields
},
},
{
collection: 'collection_name',
field: 'field_3_id',
type: 'field_3_type',
meta: {
// Meta fields
},
schema: {
// Meta fields
},
},
],
relations: [],
}, {
mode: 'merge',
})
);
console.dir(result, { depth: null });
:::
{
"diff": {
"collections": [
{
"diff": [
{}
]
}
],
"fields": [
{
"diff": [
{}
]
}
],
"systemFields": [
{
"diff": [
{}
]
}
],
"relations": [
{
"diff": [
{}
]
}
]
}
}Retrieve Schema Snapshot
Retrieve the current schema. This endpoint is only available to admin users. Returns a full snapshot (version `1`) by default. Pass `includeCollections` or `excludeCollections` to scope it to a subset of collections, which returns a partial snapshot (version `2`).
Query Parameters
Saves the API response to a file. Accepts one of csv, csv_utf8, json, xml, yaml.
Restrict the snapshot to these collections. Unknown names are ignored. Mutually exclusive with excludeCollections.
Snapshot every collection except these. Mutually exclusive with includeCollections.
Responses
1 for a full snapshot, 2 for a partial snapshot.
Name of the collection. This matches the table name in the database.
Icon displayed in the Data Studio when working with this collection.
Short description displayed in the Data Studio.
How items in this collection should be displayed when viewed relationally in the Data Studio.
Whether or not this collection is hidden in the Data Studio.
Whether or not this collection is treated as a singleton.
How this collection's name is displayed in the different languages in the Data Studio.
What field in the collection holds the archived state.
What value the archive field should be set to when archiving an item.
What value the archive field should be set to when unarchiving an item.
What field holds the sort value on the collection. The Data Studio uses this to allow drag-and-drop manual sorting.
What data is tracked. One of all, activity.
What fields are duplicated during "Save as copy" action of an item in this collection.
What sort order of the collection relative to other collections of the same level.
The name of the parent collection.
What is the default behavior of this collection or "folder" collection when it has nested collections. One of open, closed, locked.
Whether or not Content Versioning is enabled for this collection.
Unique name of the collection this field is in.
Unique name of the field. Field name is unique within the collection.
Any special transform flags that apply to this field.
The interface used for this field.
The interface options configured for this field. The structure is based on the interface used.
The display used for this field.
The configured options for the used display.
If the field is considered readonly in the Data Studio.
If the field is hidden from the edit page in the Data Studio.
Where this field is shown on the edit page in the Data Studio.
How wide the interface is rendered on the edit page in the Data Studio. One of half, half-left, half-right, half-space, full, fill.
How this field's name is displayed in the different languages in the Data Studio.
Short description displayed in the Data Studio.
Indexes defined on system fields.
Unique identifier for the relation.
Collection that has the field that holds the foreign key.
Foreign key. Field that holds the primary key of the related collection.
Collection on the one side of the relationship.
Alias column that serves as the one side of the relationship.
Field on the junction table that holds the many field of the related relation.
import { createDirectus, rest, schemaSnapshot } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(schemaSnapshot());
// Partial snapshot
const partial = await client.request(
schemaSnapshot({ includeCollections: ['articles', 'authors'] })
);
{
"version": 1,
"collections": [
{
"collection": "customers",
"translations": [],
"item_duplication_fields": []
}
],
"fields": [
{
"collection": "about_us",
"field": "id",
"special": [],
"options": {},
"translations": []
}
],
"systemFields": [
{
"schema": {}
}
],
"relations": [
{
"id": 1,
"many_collection": "directus_activity",
"many_field": "user",
"one_collection": "directus_users",
"one_field": null,
"one_allowed_collections": [],
"junction_field": null
}
]
}