Schema Design and Evolution

strata_document checks schemas in the application. The server stores opaque ORMap state and does not enforce field types.

Choose stable keys

A field key is part of stored data. Renaming a key does not rename old data. Read the old key, write the new key, and delete the old key when all supported application versions can read the new key.

Do not use these reserved keys:

• __strata_document_clock;
• __schema.

set, delete, and write return ReservedKey for the internal clock key. The schema marker is reserved by convention.

Seal known fields

Use schema.sealed or schema.sealed_known when a document must reject active keys that the schema does not declare. An unsealed schema ignores unknown keys.

sealed_known works with schemas built by record1 through record9. It returns SealedKnownRequiresDeclaredKeys for a hand-written schema, so use sealed there instead.

Stamp a schema version

Wrap a schema with schema.versioned and call strata_document.stamp when you create a document. A read returns SchemaMismatch when a stored version differs. A versioned schema accepts an unstamped legacy document.

A version check detects an incompatible document. It does not migrate the document.

Plan a migration

1. Add readers that accept the old and new representation.
2. Deploy those readers.
3. Write the new representation during normal edits or a controlled migration.
4. Confirm that supported applications no longer need the old fields.
5. Remove old readers and fields in a later release.

Mixed application versions can write at the same time. Use additive changes when possible. Do not change the meaning of an existing key in place.

Handle read errors

Typed reads return Result because remote state is untrusted. Report SchemaMismatch, UnknownKeys, WrongValueType, and invalid JSON with enough document context to diagnose the source. Do not display an empty document as if the read succeeded.