Contracts / shared language
P2 · Advanced
Schemas & Ontology Versioning
Define the structure and meaning of application data, keep a version history, and manage compatibility as the app changes.
This block has two related resources. A schema describes structure. An ontology describes semantic relationships. Both live on ultrahost.contracts.
Paths in the tables are relative to https://api.ultrahost.com/v1/projects/{projectId}. Pagination, idempotency, and errors are described in Conventions.
Create
Schemas
| SDK | REST | Description |
|---|---|---|
contracts.createSchema(name, schema) | POST /contracts/schemas | Create a schema |
contracts.getSchema(name, version?) | GET /contracts/schemas/{name} | Retrieve a schema |
contracts.listSchemas() | GET /contracts/schemas | List schemas |
contracts.publishSchema(name, version) | POST /contracts/schemas/{name}/versions | Publish a version |
contracts.listVersions(name) | GET /contracts/schemas/{name}/versions | Version history |
contracts.deprecate(name, version) | POST /contracts/schemas/{name}/versions/{version}/deprecate | Deprecate a version |
Ontologies
| SDK | REST | Description |
|---|---|---|
contracts.createOntology(name, definition) | POST /contracts/ontologies | Create an ontology |
contracts.getOntology(name, version?) | GET /contracts/ontologies/{name} | Retrieve an ontology |
contracts.listOntologies() | GET /contracts/ontologies | List ontologies |
contracts.updateOntology(name, definition) | PATCH /contracts/ontologies/{name} | Update the draft |
contracts.publishOntology(name, version) | POST /contracts/ontologies/{name}/versions | Publish a version |
await ultrahost.contracts.createSchema("property", {
type: "object",
required: ["address", "rent"],
properties: {
address: { type: "string" },
rent: { type: "number" }
}
});Configure
Published versions are immutable. A rollback moves the active version pointer. It does not delete history.
updateOntology edits the draft. publishOntology freezes a version. Deprecating a schema version keeps it readable and marks it as no longer the one callers should write against. getSchema(name, version) without a version returns the active version.
Use
| SDK | REST | Description |
|---|---|---|
contracts.validate(name, data, version?) | POST /contracts/schemas/{name}/validate | Validate data against a schema |
contracts.compare(name, from, to) | POST /contracts/schemas/{name}/compare | Compare two versions |
contracts.validateOntology(name, data) | POST /contracts/ontologies/{name}/validate | Validate semantic relationships |
const result = await ultrahost.contracts.validate("property", propertyData);Validation belongs at the boundary of a write: in a function, or before documents.create(). The document store does not replace schemas. They work together when a collection's configuration points at a schema name.