copyedit, amendments

selene 2026-01-30 16:01:04 +01:00
parent ec676007b5
commit b744f6cc4f
Signed by: sel
SSH key fingerprint: SHA256:33R/4Rx5Lu4o81LyJyXdMrmP5CJ6j7j1Soo0Dn7mKc0

@ -4,7 +4,7 @@
The **modular object format** is a framework-esque *informal* set of schemas & an *informal* specification, for analyzing and performing basic operations on structured computer data, referred to as **object instances**.
The basic data structure of object instances is defined in `wgu::types::ObjectInstance` / by the **base template**, available below. Object instances are key-value stores, where keys are generally referred to as 'properties'. Property names may contain [alphanumerics](https://en.wikipedia.org/wiki/Alphanumericals), `-` (dashes), and `_` (underscores). `.` (dots) represent a level of nesting.
The basic data structure of object instances is defined in the struct `wgu::types::ObjectInstance` / by the **base template**, available below. Object instances are key-value stores, where keys are generally referred to as 'properties'. Property names may contain [alphanumerics](https://en.wikipedia.org/wiki/Alphanumericals), `-` (dashes), and `_` (underscores). `.` (dots) represent a level of nesting.
When transmitted over a network or stored on disk, object instances are generally serialized into [JSON](https://www.json.org/json-en.html) [object literals](https://benalman.com/news/2010/03/theres-no-such-thing-as-a-json/).
@ -104,11 +104,11 @@ Similarly to [transformations](#transformations), subobjects are defined in the
## Template structure
Object templates (also referred to as 'templates') are a collection of [TOML tables](https://toml.io/en/v1.1.0#table) representing & named after each property. Modules may expose templates (`wgu::modules::ModuleItem::Template`), which extend the base template for object instances of a specific `object_type`.
Object templates (also referred to as 'templates') are a collection of [TOML tables](https://toml.io/en/v1.1.0#table) representing & named after each property. Modules may expose templates (enum variant `wgu::modules::ModuleItem::Template`), which extend the base template for object instances of a specific `object_type`.
For referencing templates, the name of the module and the name of the template are used, separated by a `/` (slash) symbol.
> **Example:** `meta/text:input.value`
> **Example:** `meta/text`
A good example is the (possibly simplest) module-exposed template of the [`meta/dummy`](meta-dummy.md) object type.
@ -161,3 +161,25 @@ conditions = [
### `array`
If `true`, the property will act as a collection of properties (referred to as an 'array'). When used as a transform destination, arrays add the source property's value to the first (0th) position.
## Functions
Functions (enum variant `wgu::modules::ModuleItem::Function`) are for calculating more object instances from existing object instances.
### Validators
Validators (enum variant `wgu::modules::ModuleItem::Validator`) are for ensuring the integrity and accuracy of data contained within object instances. Validators take one object instance, and return one log (struct `wgu::types::Log`) about the state of said object instance.
## Modularity
The modular object format is, by definition, modular.
Module items (enum `wgu::modules::ModuleItem`) should be exposed as a key-value store, where the key is a reference string and the value is the module item (see function `wgu::modules::item_registry` -> `HashMap<&'static str, ModuleItem>`).
The reference strings for module items are defined as follows:
| variant of `wgu::modules::ModuleItem` | reference string |
| ------------------------------------- | ------------------------------------------ |
| `Template` | *`object type`* |
| `Validator` | *`object type`*`:func:validator` |
| `Function` | *`(optional) object type`*`:func:`*`name`* |