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.
Request Body
Responses
POST /schema/apply
import { createDirectus, rest, schemaApply } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').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: [],
},
})
);
// Not supported in GraphQL
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.
Query Parameters
Bypass version and database vendor restrictions.
Request Body
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.
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
POST /schema/diff
::: 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: [],
})
);
console.dir(result, { depth: null });
:::
// Not supported in GraphQL
{
"diff": {
"collections": [
{
"diff": [
{}
]
}
],
"fields": [
{
"diff": [
{}
]
}
],
"relations": [
{
"diff": [
{}
]
}
]
}
}
Retrieve Schema Snapshot
Retrieve the current schema. This endpoint is only available to admin users.
Query Parameters
Saves the API response to a file. Accepts one of csv, json, xml, yaml.
Responses
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.
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.
GET /schema/snapshot
import { createDirectus, rest, schemaSnapshot } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(schemaSnapshot());
// Not supported in GraphQL
{
"version": 1,
"collections": [
{
"collection": "customers",
"translations": [],
"item_duplication_fields": []
}
],
"fields": [
{
"collection": "about_us",
"field": "id",
"special": [],
"options": {},
"translations": []
}
],
"relations": [
{
"id": 1,
"many_collection": "directus_activity",
"many_field": "user",
"one_collection": "directus_users",
"one_field": null,
"one_allowed_collections": [],
"junction_field": null
}
]
}