diff --git a/format.md b/format.md index 5712701..ea948b6 100644 --- a/format.md +++ b/format.md @@ -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`* |