Metadata grammar

This example metadata section is taken from the Elevator Management domain's class model.

metadata
    Title : Elevator Management Class Model
    Author : Leon Starr
    Document ID : mint.elevator3.td.1
    Version : 3.4.1
    Creation date : June 21, 2018
    Modification date : June 22, 2026
    Organization : Model Integration, LLC / www.modelint.com
    Copyright notice > MIT
    Organization logo > mint

Now let's see how the grammar excerpt below defines the overall structure.

// Metadata
metadata = metadata_header data_item*
metadata_header = "metadata" EOL* // Metadata header
data_item = INDENT item_name SP* (resource_item / text_item) EOL* // Metadata item
item_name = iword (delim word)* // Meta data item starts with initial cap
resource_item = '>' SP* word (delim word)* // Resource is a name
text_item = ':' SP* r'.*' // Field content can be any text

The metadata section starts with an unindented header which is just the keyword metadata.

This header is followed by any number of data items, each indented and naming either an item or a resource.

Item

Document ID : mint.elevator3.td.1

The name of an item is followed by a colon and a text_item which is any string you want to supply. The single white space on each side of the colon is for readability, but not required by the grammar.

Resource

    Copyright notice > MIT

Here the name of the item is followed by a > symbol and a resource_item. The grammar itself does not resolve the resource to a file name, but the information is passed along to whatever Blueprint module uses it.

For example, the flatland module passes the name MIT to the tablet-svg module which resolves it to a file name in the user's ~/.config/mi-tablet/images directory using the dictionary defined in the ~/.config/mi-tablet/images.yaml file.

Unlike an item, the text describing a resource_item is not an arbitrary string. Rather, it is a series of one or more word tokens delimited by single spaces. This helps ensure that the item can be mapped to a proper URL. See the // Words and delimiters section of the grammar file for more detail.

Do I need all these fields?

The grammar itself doesn't care. But your downstream modules might. Flatland, for example, uses many of these if you specify a title block, but I believe (apologies for the lack of conviction here, been a while since I've looked at the code) that it will just display empty space or nothing at all if the metadata is missing.

The general rule is that if something breaks downstream, you should get an informative error telling you that there is an issue with your metadata.

Can I add my own fields?

Absolutely. No downstream module should care if there is metadata it doesn't use.