QUAC field reference

QUAC is the set of fields Groundwork adds to a STAC catalogue, each named with the quac: prefix. Groundwork turns every source a map connects to into a STAC catalogue, and these fields carry what STAC itself has no field for, such as a QGIS project’s form settings and the relations between its layers.

This is version 0.1.0. It is provisional and may change before version 1.0. Groundwork builds its catalogues as it loads a map and does not publish them as files yet. A field is written only when the source declares it, so a missing field means the source said nothing.

The tables below are built from the QUAC schema, schema.json, a JSON Schema (draft-07). Groundwork’s tests check the catalogues it builds against the same file.

On a Collection

Field	Value	Meaning
`quac:cross_origin`	`true`	Request this layer's tiles with cross-origin access, so an exported map image can include them.
`quac:dark_style`	text	For a layer drawn from style documents: the style drawn in a dark theme, by its name.
`quac:filters`	array of `{ field, name }`	The filters the source sets up for the Collection, in its order: a field each, and the name it is shown under. Groundwork puts each one in the layer's filter row when the map opens, ready for values to be picked. Written from the filters the Mergin Maps plugin saves in a QGIS project.
`quac:form_order`	array of text	The names of the fields the source's form layout places, in its order. A column not listed is left out of the form. Written from a QGIS layer's Drag and Drop Designer form.
`quac:icon`	text	The address of the icon drawn before this Collection's name, in the colour of the text beside it. Written from the layer variable named quac_icon.
`quac:legend_image`	text	The image the source shows in place of this Collection's legend, embedded as a data URL. Written from a QGIS layer's Legend placeholder image when QGIS embeds the file in the project.
`quac:light_style`	text	For a layer drawn from style documents: the style drawn in a light theme, by its name.
`quac:locks`	`{ add, attributes, delete, geometry }`	The edits the source locks on the Collection: adding a feature, changing its attributes, changing its geometry, and deleting it. Each is true, locked for every feature, or an expression, locked for a feature while the QGIS expression comes out true for it. Written from a QGIS project's QGIS Server WFS settings and from the QFieldSync plugin's permissions.
`quac:max_zoom`	whole number	The deepest tile level requested; past it, the last level's tiles are enlarged. Written from a QGIS XYZ layer's maximum zoom.
`quac:measurement`	`{ area_unit, distance_unit }`	The area and distance units the source gives $area, $length and $perimeter in, each as the name QGIS saves, such as ha and meters. Written from a QGIS project's Measurements settings, onto every layer's Collection. Absent means square metres and metres.
`quac:overrides`	array of text	Adjustments applied to this Collection's style document, in order, each by a name Groundwork defines.
`quac:private`	`true`	The source keeps this Collection off its map and legend, such as a lookup table. Written from a QGIS layer's Private flag.
`quac:related_to`	array of `{ fields, id, name, parent_collection_id }`	The relations this Collection is the child side of, so its records hang off another Collection's features rather than being a map layer of their own. Written from a QGIS project's Relations.

On a table:columns entry

Field	Value	Meaning
`quac:attachment`	`{ default_root, filter, relative_storage, viewer }`	The field holds a path to a file rather than a value of its own. Written from a QGIS Attachment widget.
`quac:checkbox`	`{ allow_null, checked, show_stored, unchecked }`	A Checkbox widget. Written from a QGIS Checkbox widget.
`quac:color`	`true`	The field holds a colour, which the form shows as a swatch and changes with a colour picker. Written from a QGIS Color widget.
`quac:constraints`	`{ expression, not_null, unique }`	What the source checks a value against before it saves. Written from the Constraints group in QGIS's Attributes Form.
`quac:control`	`buttons` \| `dropdown`	How the edit form draws the field's list of choices: buttons shows each choice as a button, and dropdown a list that opens. A field that accepts typed text stays a dropdown. Written from the layer variable named quac_control_ followed by the field's name.
`quac:date_format`	text	The QGIS date pattern a text field stores its dates in, such as dd/MM/yyyy. Written from a QGIS Date/Time widget, only where the format is not ISO 8601.
`quac:default`	`{ expression, format, kind, on_update, value }`	A value the field is filled with. Written from the field's Default value and Apply default value on update in QGIS, or a UUID Generator widget.
`quac:duplicate_policy`	`default` \| `unset`	What the field does when a feature is duplicated: default takes the field's default value, unset clears it. Written from the field's Duplicate setting in QGIS.
`quac:editable`	`false`	The field is shown but no one can change it. Written from an unticked Editable box or a UUID Generator widget in QGIS's Attributes Form.
`quac:editable_when`	text	A QGIS expression: the source's form locks the field while it comes out false, and leaves it as its Editable box says when it comes out NULL. A field-type property is the field in double quotes, and a static one is true or false. Written from a placed field's data-defined Editable property in a Drag and Drop Designer form.
`quac:hidden`	`true`	The form never shows the field. Written from a QGIS Hidden widget.
`quac:icon`	text	The address of the icon drawn beside the field's name, in the colour of the text beside it. Written from the layer variable named quac_icon_ followed by the field's name.
`quac:in_form`	`false`	The source's form layout does not place the field, so its form leaves the field out. Written from a Drag and Drop Designer form that does not list it.
`quac:range`	`{ max, min, precision, step, suffix }`	The limits and format of a number. Written from a QGIS Range widget, or from an ArcGIS field's range domain.
`quac:reuse_last_value`	`true`	A new feature or record is offered the value last entered in the field. Written from QGIS's Reuse last entered value.
`quac:value_relation`	`{ allow_multi, allow_null, collection, descending, filter, key, order_by, order_field, value }`	The field's choices are the records of another Collection in the same catalogue. Written from a QGIS Value Relation widget.
`quac:visible_when`	array of text	The QGIS expressions that decide whether the form shows the field, outermost container first, each as QGIS wrote it. The field shows while all are true. Written from the enabled visibility expressions of the containers around it in a Drag and Drop Designer form.

In a Collection’s summaries

Field	Value	Meaning
`quac:geometry_type`	array of text	The layer's geometry type as a QGIS project names it, such as Point, as a one-item array.

On a Collection’s asset

Field	Value	Meaning
`quac:delimited_text`	`{ delimiter, escape, header, quote, skip_lines, trim }`	How the asset's file splits into rows and cells, where QGIS reads it with its Delimited Text provider rather than OGR. Written from the options a QGIS Delimited Text data source names. QGIS cannot edit a file it reads this way, so neither does Groundwork.
`quac:feature_filter`	`{ dialect, expression }`	The filter that keeps some of the features of the asset's data, so the Collection holds only those. Written from a QGIS file or WFS layer's Provider Feature Filter (Layer Properties > Source > Query Builder), in the language of the provider that reads the data.
`quac:geometry_filter`	array of `Point` \| `LineString` \| `Polygon`	The geometry types in the asset's file that the Collection holds, so a layer shows only those features. A multi-part geometry, such as a MultiPoint, counts as its single-part type. Written from QGIS file layers' geometrytype= option, which QGIS uses to split a file holding several geometry types into one layer per type; one Collection made from two such layers lists both their types, and one made from all three has no filter, so it holds the whole file.
`quac:layer_name`	text	The table of the asset's GeoPackage that the Collection reads, where the file holds several. Written from a QGIS layer's layername= option, for a GeoPackage only, and for each table of a GeoPackage dropped onto the map with no project.

On a Catalog

Field	Value	Meaning
`quac:active_collection`	text	On the top-level Catalog: the id of the Collection whose layer the map opens with as the active layer, unless the person opening it has already chosen one. Written from a QGIS project's Initial active layer, which the QFieldSync plugin sets.
`quac:mutually_exclusive`	`true`	The group shows only one of its children at a time, as a QGIS mutually exclusive group does. Written from a QGIS project's layer tree or QGIS Server's GetProjectSettings.

Members of the object fields

`quac:filters`

Each entry of the array:

Member	Value	Meaning
`field`	text	The field the filter filters. Always written.
`name`	text	The name the filter is shown under, in place of the field's own. Absent where the source gives none.

`quac:locks`

Member	Value	Meaning
`add`	`true` or `{ expression }`	Adding a feature. Locked for a new feature, before it has values, so an expression locks every new feature.
`attributes`	`true` or `{ expression }`	Changing a feature's attributes.
`delete`	`true` or `{ expression }`	Deleting a feature.
`geometry`	`true` or `{ expression }`	Moving or reshaping a feature.

`quac:measurement`

Member	Value	Meaning
`area_unit`	text	Always written.
`distance_unit`	text	Always written.

`quac:related_to`

Each entry of the array:

Member	Value	Meaning
`fields`	array of `{ child, parent }`	The field pairs joining the two, in source order. Several pairs make one composite key. Always written.
`id`	text	The relation's id within this catalogue. Always written.
`name`	text	The relation's display name.
`parent_collection_id`	text	The id of the Collection holding the parent records. Always written.

`quac:attachment`

Member	Value	Meaning
`default_root`	text	The folder the source says the files live in.
`filter`	text	The file types offered, in the source's own wording.
`relative_storage`	`absolute` \| `project` \| `default-root`	What a stored path is relative to. Always written.
`viewer`	`image` \| `web` \| `audio` \| `video`	How the file is meant to be shown.

`quac:checkbox`

Member	Value	Meaning
`allow_null`	`true`	A blank is a third state.
`checked`	text	The value a text field stores when ticked.
`show_stored`	`true`	Show the stored value rather than true and false.
`unchecked`	text	The value a text field stores when unticked.

`quac:constraints`

Member	Value	Meaning
`expression`	`{ description, expression, strength }`	A QGIS expression the values must make true, the message shown when they do not, and its strength.
`not_null`	`enforced` \| `warn`	A blank value is refused (enforced) or saved with a warning (warn).
`unique`	`enforced` \| `warn`	A value another feature holds is refused (enforced) or saved with a warning (warn).

`quac:default`

Member	Value	Meaning
`expression`	text	For expression: a QGIS expression over the record's other values.
`format`	`with_braces` \| `without_braces` \| `id128`	For uuid: with_braces, without_braces, or id128 (32 hex digits).
`kind`	`now` \| `uuid` \| `fixed` \| `expression`	now: the moment of the create or save. uuid: a new random identifier. fixed: value. expression: the result of expression. Always written.
`on_update`	true or false	Fill the field again on every save that adds or changes the feature, not only when a new feature's form opens. Always written.
`value`	text, number, true or false, null	For fixed: the value.

`quac:range`

Member	Value	Meaning
`max`	number	The largest value allowed.
`min`	number	The smallest value allowed.
`precision`	whole number	Decimal places shown.
`step`	number	The step a spin box moves by.
`suffix`	text	Text shown after the number.

`quac:value_relation`

Member	Value	Meaning
`allow_multi`	`true`	The column stores several keys.
`allow_null`	`true`	The list offers a blank choice.
`collection`	text	The id of the Collection holding the choices. Always written.
`descending`	`true`	The order is reversed.
`filter`	text	A QGIS expression narrowing the choices.
`key`	text	The field of that Collection the column stores. Always written.
`order_by`	`value` \| `field`	value orders the list by the shown value, field by order_field. Absent, it is ordered by key.
`order_field`	text	With order_by field: the field the list is ordered by.
`value`	text	The field shown for it. Always written.

`quac:delimited_text`

Member	Value	Meaning
`delimiter`	text	The characters that each end a cell.
`escape`	text	The characters that each make the next character literal. A quote character here escapes only itself.
`header`	true or false	Whether the first row read holds the column names.
`quote`	text	The characters that each open and close a quoted cell.
`skip_lines`	whole number	The lines skipped before the header or the first row.
`trim`	true or false	Whether space around an unquoted cell is removed.

`quac:feature_filter`

Member	Value	Meaning
`dialect`	`ogr_sql` \| `qgis_expression` \| `wfs_sql` \| `ogc_filter`	The filter's language: ogr_sql for GDAL's OGR SQL WHERE clause, which QGIS's OGR provider hands to GDAL; qgis_expression for a QGIS expression, which QGIS's Delimited Text provider reads and its WFS provider sends to the server; wfs_sql for the SELECT statement a QGIS WFS layer can carry instead; or ogc_filter for the OGC Filter XML it can carry in place of either. Always written.
`expression`	text	The filter as the QGIS project writes it. Always written.