The manifest.

The five sections

{
  "datasets": [
    { "key": "products", "name": "Products", "access": "ro", "api": "rw", "needForBoot": true },
    { "key": "orders", "partition": "shop", "retention": { "days": 400 }, "size": "200MB" }
  ],
  "settings": [
    { "key": "currency", "caption": "Currency", "type": "select", "options": ["GBP", "EUR"], "default": "GBP" },
    { "key": "till_no", "caption": "Till number", "type": "number", "perDevice": true }
  ],
  "files": { "needForBoot": ["logos"] },
  "partition": {
    "caption": "Shop",
    "required": true,
    "options": [ { "value": "11", "caption": "High Street" }, { "value": "15", "caption": "Market Square" } ]
  },
  "screen": { "orientation": "landscape", "writable": { "portal": false } }
}

Every section is optional. An app with no manifest still runs, but its project has no datasets and no settings: the portal does not create either, they come only from the manifest.

datasets

settings

files

One key, needForBoot: "*" (every file), one folder name, or a list of folder names under /storage/. Those folders are fetched first and the app starts once they are present. Absent: no file holds the app back.

partition

The portal uses the block only when the project's Setup has Data partition: use the app's list turned on; it is off by default, and then a device's partition is typed in. Without the block, the portal shows a free text box. A device whose partition was set before the block existed keeps its value; one the options do not name is shown as "31 (not in the app's list)".

The choices from a dataset

Instead of a list written in the manifest, options may name a dataset whose records are the choices. Opening a branch is then a record (sent through the HTTP API or edited in the portal), not a commit.

{
  "datasets": [
    { "key": "branches", "access": "ro" },
    { "key": "prices", "partition": "branch" }
  ],
  "partition": {
    "caption": "Branch",
    "required": true,
    "options": { "dataset": "branches", "value": "id", "caption": "name" }
  }
}

• dataset names a dataset declared in the same manifest, and that dataset must not be partitioned itself: the pack fails otherwise.
• value names the record field that holds a device's partition value; caption the field a person picks by. caption is optional and defaults to the value field.
• The choices are that dataset's current records. A record without the value field (or with an empty one, or one over 80 characters) is skipped; when two records have the same value, the first one counts; the list is sorted by caption, at most 1000 choices.
• As with a written list, the project's Setup must have Data partition: use the app's list turned on (off by default). Off, the partition is a free text box whatever the manifest says.
• A device whose partition is no longer in the list keeps it, and the portal marks it as not in the app's list. Nothing moves a device's partition for it.

screen

Which way a device draws its screen — for tablets, and anything else that can turn. The block presets every device of the project; a device's Setup › Android in the portal, or PATCH /v1/devices/{uid}/policy in the HTTP API, may choose differently for one device unless the block locks it.

{
  "screen": { "orientation": "landscape", "writable": { "portal": false, "api": false } }
}

An Android device turns its screen to it from ArdaPlayer v1.3.0 (Android devices); a Linux device keeps the fact and draws as before. A player that does not know the key logs it and ignores it, so the block is safe to ship ahead of the fleet.

How it is checked

• Strictly by ArdaForm. When a commit is packed, an unknown key, a wrong type or a bad value fails the pack, and every fault is listed at once. No device is told about a release whose manifest is wrong.
• Leniently by the player. A key the player does not know is logged and ignored, so a manifest written for a newer platform never stops an older device. A key it knows, written in a shape it cannot read, is different: that device ignores the whole manifest (the case of partition.options as a dataset on players up to v1.1.16, and of a select's options as {"device": …} on players up to v1.2.0).
• In developer mode the player watches the file: a save takes effect within about two seconds, and a broken save keeps the last good one.

When the manifest changes

• Additive automatically, destructive by hand. Packing a commit creates missing datasets and setting fields and updates their definitions, before any device is told. Nothing is ever deleted and no value is touched.
• A dataset the new manifest no longer names becomes an orphan in the portal: its records are kept, and the portal offers a Delete. Devices stop syncing it when they swap to the new version.
• A setting's default only seeds a value when the field is created. Changing it later does not change what operators have set.
• A setting's key is written into your code; treat it as permanent. Renaming it is a new setting and an orphaned old one.
• On a project whose app has a manifest, the portal edits values only; definitions come from the file.

Never put secrets in it

The manifest is in your repository and inside every device's copy of the app. Passwords, tokens and keys belong in settings an operator fills in (for a password, a secret field of a rows setting), not in a default.

Checked: the example above and every rule in the tables were checked against ArdaForm's pack-time parser (lib/manifest.js in the control plane) by running it on the example, and against the player's parser (internal/manifest).