Prerequisites
- TerminusDB running on
localhost:6363— see installation guide - A database created: Create a Database guide
- A connected client: TypeScript or Python
What you'll achieve
By the end of this guide, you will have defined a schema (document types) in your TerminusDB database using the HTTP API, TypeScript, or Python.
Define a schema
A schema in TerminusDB defines your document types — their fields, data types, keys, and relationships. Schema documents are JSON objects with @type: "Class".
HTTP API
curl -u admin:root -X POST \
"http://localhost:6363/api/document/admin/mydb?graph_type=schema&author=admin&message=Add+schema" \
-H "Content-Type: application/json" \
-d '[
{"@type": "Class", "@id": "Country", "@key": {"@type": "Lexical", "@fields": ["name"]}, "name": "xsd:string"},
{"@type": "Class", "@id": "Person", "@key": {"@type": "Lexical", "@fields": ["name"]}, "name": "xsd:string", "nationality": "Country"}
]'Expected response:
Example: JSON
["terminusdb:///schema#Country", "terminusdb:///schema#Person"]Example: TypeScript
const schema = [
{
"@type": "Class",
"@id": "Country",
"@key": { "@type": "Lexical", "@fields": ["name"] },
"name": "xsd:string",
},
{
"@type": "Class",
"@id": "Person",
"@key": { "@type": "Lexical", "@fields": ["name"] },
"name": "xsd:string",
"nationality": "Country",
},
];
const result = await client.addDocument(schema, { graph_type: "schema" });
console.log("Schema created:", result);
// ["terminusdb:///schema#Country", "terminusdb:///schema#Person"]Example: Python
schema = [
{"@type": "Class", "@id": "Country", "@key": {"@type": "Lexical", "@fields": ["name"]}, "name": "xsd:string"},
{"@type": "Class", "@id": "Person", "@key": {"@type": "Lexical", "@fields": ["name"]}, "name": "xsd:string", "nationality": "Country"},
]
results = client.insert_document(schema, graph_type="schema")
print("Schema created:", results)
# ["terminusdb:///schema#Country", "terminusdb:///schema#Person"]Schema concepts
| Concept | Description | Example |
|---|---|---|
@type: "Class" | Declares a document type | {"@type": "Class", "@id": "Person"} |
@key | Determines how document IDs are generated | {"@type": "Lexical", "@fields": ["name"]} |
| Field types | Properties use XSD types or references to other classes | "name": "xsd:string", "nationality": "Country" |
@subdocument | Embedded objects without independent identity | "@subdocument": [] |
Key strategies
- Lexical — deterministic IDs from field values (e.g.,
Person/Alice) - Hash — content-addressed IDs from a hash of specified fields
- ValueHash — IDs derived from all field values (immutable documents)
- Random — auto-generated unique IDs (default)
Next steps
- Add Documents — insert data conforming to your schema
- Schema Reference — complete schema specification
- Edit Documents — update existing documents