structures(1) user manual | version 0.0.0 780edfb % R. S. Doiel % 2026-05-11
structures
structures [OPTIONS] COMMAND [ARGS]
structures is a tool for designing and curating schema models used by dataset/datasetd and related Caltech Library projects. Schemas are expressed as YAML files whose elements map to HTML5 form types, library identifier types (DOI, ORCID, ROR, ISBN, ARK, …), and structural types (list, object).
-help : display this help
-version : display version information
-license : display license information
new SCHEMA_FILE : Create a new schema and open it in the interactive editor. SCHEMA_FILE must not already exist.
edit SCHEMA_FILE : Open an existing schema in the interactive tree editor. Any issues found by the linter are shown before editing begins.
check SCHEMA_FILE : Lint a schema file and report issues. Exits with a non-zero status if any errors (not just warnings) are found.
types : List all registered element types.
serve [OPTIONS] : Start the Web UI form builder on localhost:8080 (override with -port). The service is stateless — schemas live in the browser and are exported as YAML downloads. Safe to run as a shared, proxied web service.
-help TOPIC : Display Markdown help for a type or topic. E.g. structures -help doi
The editor presents a breadcrumb showing your location in the element tree (e.g. "article > creators(list) > person_or_org(object)") and the elements at the current depth. Commands available at every level:
[a]dd add a new element at the current level [e]dit edit an existing element (name, type, label, required, primary id, generator, attributes) [r]emove remove an element [d]escend enter a list or object element to edit its sub-elements [v]iew display the full schema as YAML [c]heck run the linter and show any issues [q]uit exit (prompts to save if changes were made)
At the root level only:
[m]odel edit the schema id and description [s]ave write changes back to the schema file
When editing an element the following properties are available:
[n]ame rename the element id [t]ype pick from the type list (includes list and object) [l]abel set the human-readable label [r]equired toggle the required flag [p]rimary id toggle whether this element is the schema's primary key [g]enerator set a value generator (uuid, autoincrement, current_timestamp, created_timestamp) [a]ttributes add, edit, or remove arbitrary key=value attributes (HTML attributes, data-component references, etc.)
Structural : list, object
HTML5 : text, textarea, date, datetime-local, month, time, number, range, email, url, tel, color, password, checkbox, radio
Identifiers : orcid, isni, ror, uuid, doi, isbn, issn, arxiv, ean, pmid, pmcid, fundref, lcnaf, viaf, snac, ark, wikidata
Run 'structures types' for the full list.
Create a new schema for articles:
structures new article.yamlEdit an existing schema:
structures edit article.yamlLint a schema before deploying it to datasetd:
structures check article.yaml