Experiment Definition (--expdef)#

SIERRA is capable of reading --expdef-template from a number of formats via --expdef plugins. Before diving into the details of the plugins, it is important to clarify terminology around the different components in files passed to --expdef-template:

Attribute - The value part of a <key, value> pair within an --expdef-template which maps to a native primitive such as a bool, int, or string. An array also counts as an attribute, but only when all of its members are primitives (e.g. [80, 443]); an array whose members are themselves maps or lists is treated as an element (see below). Attributes cannot contain other attributes. Whether array-valued attributes are supported depends on the format: JSON and YAML plugins support them because the language spec supports them, while the XML plugin does not because XML attribute values are always scalars.
Element - The value part of a <key, value> pair within an --expdef-template which maps to a sub-tree of configuration. Thus, elements can contain other elements, as well as attributes (depending on markup format). A list whose members are maps/lists (for example a list of objects) is an element, not an attribute.
Tag - The key part of a <key, value> pair within an --expdef-template which maps either to an element or an attribute.

The differences between these components is best illustrated with some simple examples:

XML

<menu id="file" value="File">
 <popup>
   <menuitem value="New" onclick="CreateNewDoc()" />
   <menuitem value="Open" onclick="OpenDoc()" />
   <menuitem value="Close" onclick="CloseDoc()" />
 </popup>
</menu>

JSON

{"menu": {
   "id": "file",
   "value": "File",
   "popup": {
     "menuitem": [
       {"value": "New", "onclick": "CreateNewDoc()"},
       {"value": "Open", "onclick": "OpenDoc()"},
       {"value": "Close", "onclick": "CloseDoc()"}
      ]
   }
}}

YAML

menu:
  id: file
  value: File
  popup:
    menuitem:
       - value: New
         onclick: CreateNewDoc()
       - value: Open
         onclick: OpenDoc()
       - value: Close
         onclick: CloseDoc()

In the above, {menu, popup, menuitem} are tags, and each identify unique elements. {id, value, onclick} are tags identifying attributes.

The distinction between an array-valued attribute and an element is illustrated below (JSON/YAML only; XML attribute values are always scalars):

JSON

{"server": {
   "ports": [80, 443],
   "backends": [
     {"host": "a", "weight": 1},
     {"host": "b", "weight": 2}
   ]
}}

YAML

server:
  ports:
    - 80
    - 443
  backends:
    - host: a
      weight: 1
    - host: b
      weight: 2

Here ports is a tag identifying an attribute: its value is a flat array of scalars, so SIERRA can read and modify it as an attribute. backends is a tag identifying an element: its value is an array whose members are maps, so it is a sub-tree, not an attribute.

Builtin --expdef Plugins#

With that understanding in place, the supported formats that come with SIERRA are summarized below, followed by per-format details.

Built-in `--expdef` format comparison#
Capability	XML	JSON	YAML
Selected via	`--expdef=expdef.xml`	`--expdef=expdef.json`	`--expdef=expdef.yaml`
Path/query language	XPath	JSONPath	YAMLPath
Multiple path matches	only the first match is modified	all matches modified (all-or-nothing)	all matches modified
Array-valued attributes	No (attribute values are always scalars)	Yes (flat array of scalars)	Yes (flat array of scalars)
Flattening (`flatten()`)	Not supported	Supported	Supported

Additional formats can be supported via New Experiment Definition File Plugin (--expdef).