Schema
Retrieve and update the schema of an instance.
Retrieve Schema Snapshot
Retrieve the current schema. This endpoint is only available to admin users.
Request
Query Parameters
Supports the export query parameter.
Response
Returns the JSON object containing schema details by default, or downloads it in an alternative format when export query parameter is used.
Example
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. Relies on a multipart/form-data encoded request like regular file uploads. Check Upload a File for more information.
Different versions and vendors
This endpoint does not allow different Directus versions and database vendors by default. This is to avoid any unintentional diffs from being generated. You can opt in to bypass these checks by passing the force query parameter.
Request
Query Parameters
force boolean
Bypass version and database vendor restrictions.
Request Body
JSON object containing collections, fields, and relations to apply.
Alternatively, send a JSON or YAML schema file in a multipart/form-data request. See Upload a File for more information.
Response
Returns the differences between the current instance's schema and the schema passed in the request body.
Toggle Open to See Sample Response
{
"hash": "2b3c71570228b864e16098147e5497f61b245a42",
"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": []
}
}{
"hash": "2b3c71570228b864e16098147e5497f61b245a42",
"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": []
}
}Example
Apply Schema Difference
Update the instance's schema by passing the diff previously retrieved via /schema/diff endpoint in the request body. This endpoint is only available to admin users.
Request
See Example
Query Parameters
This endpoint doesn't currently support any query parameters.
Request Body
JSON object containing hash and diffs of collections, fields, and relations to apply.
Alternatively, upload a JSON or YAML schema file. Relies on a multipart/form-data encoded request like regular file uploads. Check Upload a File for more information.
Response
Empty body.
Example
Hashes
The hash property in the diff is based on the target instance's schema and version. It is used to safeguard against changes that may happen after the current diff was generated which can potentially incur unexpected side effects when applying the diffs without this safeguard. In case the schema has been changed in the meantime, the diff must be regenerated.