Documents, models and CRUD
Ordinary records and optional schemas are the starting point for every RURAL workload.
Status: Development. The prototype implements document envelopes, optional schemas and bounded create, read, replace, patch, upsert, delete and batch operations. Full native acceptance, packaging and release remain open.
Begin with a record
A project, task, document or decision should be an ordinary record with a stable identity. Nested values let related attributes stay together; explicit relationships connect records when their lifecycles differ.
This illustrative task is data, not an executable command:
{
"id": "task:launch-review",
"title": "Review the launch checklist",
"status": "open",
"project": "project:website",
"owner": {"team": "operations"},
"estimate": null,
"labels": ["release", "review"]
}
The intended API supports create, read, replace/update, upsert and delete, individually or in a bounded transaction. Schemas and graph behavior build on those operations; they do not replace them.
Choose how much structure to require
An optional schema makes expectations explicit. For the task above, a model could require a string title and status, allow a nullable estimate, and decide whether unregistered fields are accepted.
| Rule | Purpose |
|---|---|
| Required field | Distinguish an absent attribute from a deliberately supplied value. |
| Nullability | Decide whether explicit null is valid for that field. |
| Field type | Reject values that do not match the declared model. |
| Unknown-field policy | Choose controlled extension or a closed field set. |
| Index or uniqueness rule | Support a declared lookup or invariant within a defined scope. |
Schema evolution must have a version and a migration policy. A new schema cannot silently reinterpret previously accepted data or make a branch merge valid without checking its constraints.
Preserve meaning at the boundary
Missing and null are different states. An absent estimate means the attribute was not supplied; an explicit null records a chosen empty value. Queries, validation and updates must preserve that distinction.
Numbers need an exact contract. Large identifiers and monetary values must not be silently rounded through a floating-point conversion. The document-layer implementation remains pending, so this requirement should not be confused with a currently available numeric API.
Source-owned documents also carry provenance. Reading a repository's governance file into RURAL does not transfer authority over that original file. Application-owned records and source observations need distinguishable ownership and mutation rules.
What the foundation does today
The prepared state engine operates on opaque byte keys and values. put inserts or replaces, create requires absence, and delete requires presence. Batches either publish together or leave the old root unchanged.
It does not validate the task model above, enforce field schemas or provide a complete application adapter. Those are the next layers of the design.