Data schema files

If an app has any data, it must have a schema file, that defines the contents of the app's CSV file(s). Schema files use the "Miga Data Schema" format, a simple .ini format that mostly just defines the type of each data column/field. Schema files can have any name, although they should end in ".ini". Here are the contents of "BooksSchema.ini", a schema file for a hypothetical app containing information about books and their authors:

[Books]
Title = Name
Author = List (,) of Entity (Authors/Name)
Number of pages = Number
Genre = List (,) of Text
Wikipedia URL = URL

[Authors]
Name = Name
Birth date = Date

The name of each "category" of information is contained in single brackets; by default, if a category is called "Books", Miga will look for the data in a file called "Books.csv".

You can change the name of the file the software looks for by adding a field called "_file". So, for instance, if the data from authors is contained in a file called "Authors_data_01022013.csv", and you don't want to rename the file, the second part of BooksSchema.ini should look like this:

[Authors]
_file = Authors_data_01022013.csv
Name = Name
Birth date = Date

You can also have the system get the CSV from an external URL. The "_file" value can be a URL, starting with "http".

After the name of each category, and potentially a file name or URL, comes that category's list of fields, with explanatory information about each one. Below are the list of field types, with an explanation of each.

Field types

Name

This field holds the name with which each item/row will be referred to in the application. A category/table should not have more than one "Name" field. The values of this field don't have to be unique - for the "Books" example above, there can be more than one author named "Tom Wolfe" - but it's better if they are unique. A category/table doesn't have to contain a field with type "Name", although if it doesn't, it will be an auxiliary category, displayed only in conjunction with other information - so it should contain one or more "Entity" fields (see below).

ID

This field holds a unique ID for each row. It is similar to the "Name" type in that it's used as a row identifier behind the scenes. What makes it distinct is that unlike "Name" (or any other type), it is not displayed on the screen.

Text

This is the most basic type. Fields of this type can hold a text string of any size, containing any characters.

Number

A number, either integer or with decimal points. If it holds decimal points, they must be separated by a ".", in the American style.

Date

A date, holding at least a year. The format is very flexible; essentially whatever Javascript is able to parse. One good, non-ambiguous format for dates is "YYYY-MM-DD", i.e. with a four-digit, two-digit and two-digit number respectively for the year, month and day.

Start time

Works exactly the same as date, but specifically defines the start time, if an entity represents an event. It is used to filter based on whether an event has happened yet or not. There should be no more than one field of type "Start time" per category.

End time

Defines the end time, if an entity represents an event (see "Start time"). Unlike "Start time", "End time" fields do not show up as filters.

URL

Any URL. URLs will be displayed as links in the application.

Image URL

The URL of an image. Values of this type will be displayed as images.

Video URL

The URL of a video. Values of this type will be displayed as videos, using the HTML <video> tag.

Audio URL

The URL of an audio file. Values of this type will be displayed with an audio player, using the HTML <audio> tag.

Coordinates

Geographical coordinates for locations on the Earth. Miga supports most coordinate formats, including both decimal numbers and degrees/minutes/seconds (DMS) notation. Coordinates must be a pair of values, the first for latitude and the second for longitude. Latitude and longitude must be contained in the same field; they cannot be split up across two separate fields.

Entity

This type indicates that the values in this field correspond to values in another field, in this or another table. The word "Entity" has to be followed by the name of the table/field combination that this field corresponds to, in parentheses. For the example above, the string after "Entity" is "(Authors/Name)" - that means that the system will try to match values for this field with values for the "Name" field in the "Authors" category. If there's a match for a particular book, then the book and author items will be linked together in the display - so that, when viewing the book, the author name will be a hyperlink; and when viewing the author, the book will be listed among books written by that author.
In practice, Entity fields almost always link to fields that are of either type "Name" or "ID".
An Entity field can point to another field in that same category - for example, a category called "People" could include a field called "Friend", or "Employee", or "Parent", that holds one or more entities pointing to the main identifier field of that same category.

Lists of fields

You can see in the example above that two of the field definitions start with the word "List". In real-life data, very often a single field will need to hold more than one value. You can easily specify that this is the case by using the syntax "List (delimiter) of type" - where delimiter is the character separating out values from one another - this will usually be a comma, but it can also be a semicolon, etc.