civex schema
Manage schemas (data structure definitions)
| Command | Description |
|---|---|
add-field |
Add a field to a schema. |
add-unique |
Require a combination of fields to be unique. |
create |
Define a new schema. |
delete |
Delete a schema (and the records typed by it) to Recently Deleted. |
exports |
Exports saved with a schema: which files, how they are laid out |
lint |
Report schema and field names that aren't valid slugs. |
list |
List all schemas. |
purge |
Permanently delete a schema that's already in Recently Deleted. Irreversible. |
remove-field |
Remove a field from a schema. |
remove-unique |
Remove a uniqueness key (give the same fields it was added with). |
restore |
Restore a soft-deleted schema (and the records cascade-deleted with it). |
restore-field |
Restore a removed field, with the values records still hold for it. |
show |
Inspect a schema's fields (including inherited). |
unique |
List a schema's uniqueness keys. |
update |
Update a schema's name, label, description, or record name template. |
update-field |
Update a field's name, label, required flag, or restrictions. |
civex schema add-field
Add a field to a schema.
The field name is a slug because workflow steps reference it by name
(e.g. civex.get_field's field:). Use --label for the human-readable
version shown in the UI and in civex schema show.
Restriction examples:
--type integer --min 0 --max 100
--type string --choices "left,right,bilateral"
--type string --max-length 255
--type file --accept ".csv,.txt" --max-size 10485760
--type float --unit m --min 0
--type date --precision month
--type geo --geometry-types Point --bbox "-12,48,4,62"
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
SCHEMA_NAME |
str |
yes | Schema to add the field to |
FIELD_NAME |
str |
yes | Field name — the machine key used by workflows and CSV headers (lowercase, underscores, e.g. recording_date) |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--label, -l |
str |
Human-facing display name, free text (e.g. 'Recording Date') | |
--type, -t |
str |
Field type: integer | float | string | boolean | date | datetime | geo | file | file_list | reference (required) | |
--required, --optional |
flag | --optional |
Whether the field is required |
--references |
str |
Target schema (--type reference) | |
--min |
float |
Minimum value (integer/float) | |
--max |
float |
Maximum value (integer/float) | |
--choices |
str |
Comma-separated allowed values (string) | |
--max-length |
int |
Maximum character length (string) | |
--accept |
str |
Allowed extensions e.g. '.csv,.txt' (file/file_list) | |
--max-size |
int |
Maximum file size in bytes (file/file_list) | |
--unit |
str |
Unit every value is stored in, e.g. m or degC (float). Values are never converted after the fact. | |
--precision |
str |
Least precise date accepted: year | month | day (date) | |
--geometry-types |
str |
Comma-separated shapes allowed, e.g. Point,Polygon (geo) | |
--bbox |
str |
Allowed area as WEST,SOUTH,EAST,NORTH in degrees; west greater than east crosses the 180th meridian (geo) |
civex schema add-unique
Require a combination of fields to be unique.
No two records of the schema may then hold the same values in all of the given fields, within the same parent record (or the same collection, for a top-level record). A record with a blank in any of them is not constrained. Refused while existing records already share values.
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
NAME |
str |
yes | Schema name |
FIELDS... |
str |
yes | The fields of the key (the schema's own) |
civex schema create
Define a new schema.
The name is a slug because workflow YAML, CSV headers and display fields all reference it as text. Put spaces and capitals in --label instead — that is what the UI and CLI show, and it can be changed freely.
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
NAME |
str |
yes | Schema name — the machine key used by workflows and CSV headers (lowercase, underscores, e.g. acoustic_recording) |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--label, -l |
str |
Human-facing display name, free text (e.g. 'Acoustic Recording') | |
--description, -d |
str |
Schema description | |
--parent, -p |
str |
Inherit fields from this schema |
civex schema delete
Delete a schema (and the records typed by it) to Recently Deleted.
Reversible with civex schema restore within the retention window
(see civex trash list); civex schema purge deletes permanently.
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
NAME |
str |
yes | Schema name |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--yes, -y |
flag | false |
Skip confirmation prompt |
civex schema exports
Exports saved with a schema: which files, how they are laid out
Usage
civex schema lint
Report schema and field names that aren't valid slugs.
Names are validated when they're created or renamed, so anything listed
here predates that rule. Nothing is broken — these names still resolve —
but they read badly in workflow YAML and CSV headers. Rename with
civex schema update --rename / civex schema update-field --rename
and move the human-readable text to --label.
Usage
civex schema list
List all schemas.
Usage
civex schema purge
Permanently delete a schema that's already in Recently Deleted. Irreversible.
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
NAME |
str |
yes | Schema name |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--yes, -y |
flag | false |
Skip confirmation prompt |
civex schema remove-field
Remove a field from a schema.
Reversible: the field goes to Recently Deleted and every record keeps the
value it held for it. Bring it back with civex schema restore-field
(find its ID with civex trash list --kind field).
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
SCHEMA_NAME |
str |
yes | Schema containing the field |
FIELD_NAME |
str |
yes | Field to remove |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--yes, -y |
flag | false |
Skip confirmation prompt |
civex schema remove-unique
Remove a uniqueness key (give the same fields it was added with).
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
NAME |
str |
yes | Schema name |
FIELDS... |
str |
yes | The fields of the key (the schema's own) |
civex schema restore
Restore a soft-deleted schema (and the records cascade-deleted with it).
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
NAME |
str |
yes | Schema name |
civex schema restore-field
Restore a removed field, with the values records still hold for it.
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
SCHEMA_NAME |
str |
yes | Schema the field was removed from |
FIELD_ID |
str |
yes | ID of the removed field (see civex trash list --kind field) |
civex schema show
Inspect a schema's fields (including inherited).
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
NAME |
str |
yes | Schema name |
civex schema unique
List a schema's uniqueness keys.
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
NAME |
str |
yes | Schema name |
civex schema update
Update a schema's name, label, description, or record name template.
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
NAME |
str |
yes | Schema name |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--rename |
str |
New name (slug) for the schema | |
--label, -l |
str |
New display name for the schema; pass '' to clear it | |
--description, -d |
str |
New description for the schema | |
--display-template |
str |
Template that names the schema's records, e.g. '{site}-{taken_on:YYYY-MM}'. Fields go in braces; formats follow a colon. | |
--clear-display-template |
flag | false |
Remove the record name template (revert to auto) |
civex schema update-field
Update a field's name, label, required flag, or restrictions.
Usage
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
SCHEMA_NAME |
str |
yes | Schema containing the field |
FIELD_NAME |
str |
yes | Field name |
Options
| Option | Type | Default | Description |
|---|---|---|---|
--rename |
str |
New name (slug) for the field | |
--label, -l |
str |
New display name for the field; pass '' to clear it | |
--required, --optional |
flag | Set required/optional | |
--min |
float |
Minimum value (integer/float) | |
--max |
float |
Maximum value (integer/float) | |
--choices |
str |
Comma-separated allowed values (string) | |
--max-length |
int |
Maximum character length (string) | |
--accept |
str |
Allowed extensions e.g. '.csv,.txt' | |
--max-size |
int |
Maximum file size in bytes | |
--unit |
str |
Unit every value is stored in, e.g. m or degC (float). Values are never converted after the fact. | |
--precision |
str |
Least precise date accepted: year | month | day (date) | |
--geometry-types |
str |
Comma-separated shapes allowed, e.g. Point,Polygon (geo) | |
--bbox |
str |
Allowed area as WEST,SOUTH,EAST,NORTH in degrees; west greater than east crosses the 180th meridian (geo) | |
--clear-restrictions |
flag | false |
Remove all restrictions |