world.ensurecommandsince 0.1
Declares a world in one call: the project and its entity types, entities, predicates and axes. It creates what is missing and leaves the rest as it is.
Request
umwelt call story.umw world.ensure '{
"project": { "id": "ball", "name": "The Ball", "timescale": "scene" },
"entityTypes": [{ "id": "person", "name": "Person", "kind": "agent" }],
"entities": [
{ "id": "ana", "typeId": "person", "name": "Ana" },
{ "id": "gardener", "typeId": "person", "name": "The gardener" }
],
"predicates": [
{
"id": "stole",
"label": "stole",
"object": "entity",
"cardinality": "many"
}
]
}'Request
const result = await client.worldEnsure({
project: { id: 'ball', name: 'The Ball', timescale: 'scene' },
entityTypes: [{ id: 'person', name: 'Person', kind: 'agent' }],
entities: [
{ id: 'ana', typeId: 'person', name: 'Ana' },
{ id: 'gardener', typeId: 'person', name: 'The gardener' },
],
predicates: [
{
id: 'stole',
label: 'stole',
object: 'entity',
cardinality: 'many',
},
],
});Request
var result = engine.WorldEnsure(new EnsureWorldInput
{
Project = new WorldProject { Id = "ball", Name = "The Ball", Timescale = "scene" },
EntityTypes = new()
{
new WorldEntityType
{
Id = "person",
Name = "Person",
Kind = EntityKind.Agent,
},
},
Entities = new()
{
new WorldEntity { Id = "ana", TypeId = "person", Name = "Ana" },
new WorldEntity
{
Id = "gardener",
TypeId = "person",
Name = "The gardener",
},
},
Predicates = new()
{
new PredicateDef
{
Id = "stole",
Label = "stole",
Object = ObjectKind.Entity,
Cardinality = Cardinality.Many,
},
},
});Response
{
"created": {
"axes": [],
"entities": ["gardener"],
"entityTypes": [],
"predicates": [],
"project": false
},
"project": {
"id": "ball",
"version": 17,
"name": "The Ball",
"createdAt": "2026-11-11T18:21:58.5898875Z",
"timescale": "scene",
"vocabularyMode": "strict"
}
}Payload
| Field | Type | Description |
|---|---|---|
projectrequired | WorldProject | The project: id, name, timescale, and optionally description and vocabularyMode. |
entityTypes | WorldEntityType[]default [] | Entity types, each with an id, a name, a kind and optionally fields. |
entities | WorldEntity[]default [] | Entities, each with an id, a typeId, a name, and optionally aliases, fields, an externalRef and createdAt. |
predicates | PredicateDef[]default [] | Predicates, as in predicate.define. |
axes | AxisDef[]default [] | Additional time axes, as in axis.define. |
Result
| Field | Type | Description |
|---|---|---|
projectalways | Project | The project as stored. |
createdalways | WorldCreated | What this call created: project (true or false) and the ids of the entityTypes, entities, predicates and axes that were new. |
Rules
All of it or nothing. Everything missing is created in one transaction.
Sending it again changes nothing. What already exists with the same definition is left as it is, so an application can send its manifest every time it opens the file.
It never overwrites. Anything that exists with another definition refuses the whole manifest, and details.divergences lists each one as { kind, id, field }.
Entities may change in play. An existing entity only has to keep its typeId. Its name, aliases and fields are neither compared nor rewritten; change them with entity.update.
Errors
VALIDATION_FAILEDThe payload is malformed, an id is empty or listed twice, a predicate or axis id is reserved, or an entity has a field its type does not define.CONFLICTSomething exists with another definition. Nothing was changed.NOT_FOUNDAn entity names a type that is neither stored nor in the manifest.HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.Every code is listed in Errors.
See also
entity.ensureBatchentities with your own idsentity.updatechange an entityproject.createone project alone
Was this page helpful?