4. Metamodel

Contents of DESL 0.2

The metamodel says what a document of the designer type can hold: the kinds of elements, their attributes, and how they nest. Nothing in it is drawn connected; a link from one element to another is a reference attribute (4.7), shown as a value.

4.1 Overview

Property	Type	Description
`document`	`{attributes, children, doc}`	The attributes of the document as a whole: for a table, its name and the view it was last left in. (DESL 0.2) `children`, a Containment (4.6), says which types the document's own elements may be.
`enums`	map → Enum	Enumerations (4.4).
`types`	map → ElementType	Required. The element types (4.5).
`doc`	Doc

4.2 Primitive types

Type	CEL type	Stored as	Facets
`string`	`string`	a string, one line	`minLength`, `maxLength`, `pattern`
`text`	`string`	a string, any number of lines	as `string`
`int`	`int`	an integer	`min`, `max`
`number`	`double`	a number	`min`, `max`
`bool`	`bool`	`true` or `false`	–
`date`	`timestamp`	`"YYYY-MM-DD"`	–
`datetime`	`timestamp`	an RFC 3339 string	`timezone`: `"utc"`, or `"preserve"`, which keeps the offset each value was written with
`time`	`duration` since midnight	`"HH:MM[:SS]"`	–

How a value is written in a body (a YAML scalar's style, a JSON number's form, an XML attribute) is the binding's (FBL section 6.2).

4.3 Attributes

An Attribute ($defs/Attribute) is one named value of an element, of the document, or of an operation's parameters.

Property	Type	Description
`type`	primitive, enumeration or element type	Required. An element type makes the attribute a reference (4.7).
`label`, `doc`		Display name and help.
`required`	bool	The attribute must have a value; checked by `std.required` (6.5). Default `false`.
`default`	literal	The value of an attribute that has none stored.
`many`	bool	The attribute holds a list. Default `false`.
`readOnly`	bool	Not editable by the user; operations may still set it.
`min`, `max`	number or string	Bounds of an `int` or `number`; checked by `std.facets` (6.5).
`minLength`, `maxLength`, `pattern`		Facets of a `string` or `text`; checked by `std.facets`.
`timezone`	`"utc"`, `"preserve"`	How a `datetime` keeps its zone (4.2).
`mentions`	`{pattern, types}`	(DESL 0.2) A `string` or `text` attribute whose value names elements by id (below).

Mentions (DESL 0.2). A mentions facet makes the text of a string or text attribute name elements of the same document where it is written. pattern is a regular expression in FBL's common subset (FBL section 2.5) with a named group id; types (TypeRefs, required) are the element types a mention may name.

A runtime finds the matches of pattern in the value from left to right, each starting after the one before it ends. A match in which the group id takes part is a mention, naming the element whose id is that group's text; a match in which it takes no part is not, so an alternative before it can say what is not a mention: \[(?:ITEM|REQ)-\d+\]$[^)]*$|\[(?<id>(?:ITEM|REQ)-\d+)\] reads [REQ-0002] as a mention and the Markdown link [REQ-0002](https://…) as none.
A mention resolves to the element with its id, as a reference does (4.7), the first holder of a duplicated id included (5.3.4). A mention that names no element of types is reported by std.mentions (6.5), located at the mention itself.
A mention is text, and no runtime changes it: when the element it names is deleted, the text is kept as written and the mention is reported. This is what sets it apart from a reference, which a deletion unsets (4.7).

Reading an attribute that has no stored value yields its default, otherwise the zero value of its CEL type ('', 0, 0.0, false, [], null for a reference). has(self.attr) tests whether a value is stored. A writer leaves out a value that is not stored.

4.4 Enumerations

An Enum ($defs/Enum) lists its values in display order, by key: values (required, map simple identifier → EnumValue), ordered (the values have a meaningful order), label and doc. An EnumValue has value, its stored form (a non-empty string, default its key, unique within the enumeration), label, icon and doc. A reader MUST map a stored form back to its key; CEL always sees the key. A stored form no value has is kept as written and reported by std.facets.

4.5 Element types

An ElementType ($defs/ElementType) is one kind of element a document holds.

Property	Type	Description
`label`, `doc`		Display name and help.
`icon`	string	The type's icon, by name.
`attributes`	map → Attribute	Its attributes.
`children`	Containment	What its elements contain (4.6).
`labelAttribute`	attribute name	The attribute that names one of its elements in lists, findings and pickers. Default: the first required `string` attribute, else the first `string` attribute.

An element has one type. isA(t) (9.2) is true for an element of type t.

4.6 Containment

Containment ($defs/Containment) makes elements nest: a property contains its options, a row its cells, a view its settings. A contained element has exactly one parent, and deleting the parent deletes what it contains.

Property	Type	Description
`allowed`	TypeRef[]	The types that may be direct children.
`ordered`	bool	Child order is meaningful and kept.
`slots`	map → `{allowed, max, doc}`	Named places for children, when an element holds several kinds apart: a view's `columns`, `sorts` and `filter`. Each child records its slot.
`doc`	Doc

An element type without children contains nothing. Elements without a parent are the document's own, in document order (10.2). (DESL 0.2) metamodel.document.children allows the types they may be, as an element type's children does; without it, they may be of any type.

4.7 References

A reference is an attribute whose type is an element type. It stores the target's id, is resolved to the element in CEL, and is not containment. A reference that names no element is kept as written and reported by std.references (6.5); in CEL it reads null. Deleting an element MUST unset, in the same transaction, every reference to it that the specification's operations do not delete or change themselves.

A reference to an element of another document, such as a knowledge file's relation to the rows of another file, is not a reference in this sense: it is a value that names the other document and an id in it, resolved by the host (section 5.4).