v0.1.0 to v0.1.0

---

name: shacl-forms

description: "Derive a DASH-compatible, renderer-agnostic form description from SHACL shapes with the opt-in sparq-forms crate: (data graph, shapes graph, focus node, view|edit mode) -> serde-JSON FormDescription — applicable-shape switcher, property-group/field layout (sh:name/sh:description/sh:order/sh:group, sh:inversePath incoming references, sh:deactivated, implicit read-only Other group), DASH widget auto-selection via the documented 0-100 scoring registry (TextField/TextArea/BooleanSelect/Date+DateTimePicker/EnumSelect/InstancesSelect/URIEditor/RichText/SubClass/DetailsEditor and the viewers) with dash:editor/dash:viewer overrides, required/multi cardinality typing, dash:hidden/dash:readOnly/sh:defaultValue presentation flags, per-field constraints and opt-in live SHACL validation hints, and nested sh:node sub-forms. Use when an agent or GUI needs a shape-directed data-entry/edit/view form for a focus node (headless: no GUI deps, builds for wasm32)."

license: MIT

metadata:

version: "0.1.0"

homepage: https://github.com/jeswr/sparq

---

# sparq-forms — SHACL/DASH form derivation

`sparq-forms` is an **opt-in** crate (depending on it is the opt-in; nothing in

the default workspace pulls it) that turns SHACL shapes into a **headless form

model**: a pure function from (data graph, shapes graph, focus node, options)

to a serde-JSON `FormDescription` a renderer (Tauri workbench, web via wasm, an

MCP agent tool) can draw without knowing any SHACL.

```rust

use sparq_core::Graph;

use sparq_forms::{derive_form, FormOptions, Mode};

use oxrdf::{NamedNode, Term};

let shapes = Graph::load_str(SHAPES_TTL, "turtle")?; // sh:NodeShape + sh:property …

let data = Graph::load_str(DATA_TTL, "turtle")?;

let focus = Term::from(NamedNode::new("http://example.org/alice")?);

let form = derive_form(&data, &shapes, &focus, &FormOptions::default()); // edit mode

let json = serde_json::to_string_pretty(&form)?; // ship to any renderer

```

After a renderer edits the `values` of editable fields, build the corresponding

SPARQL 1.1 Update without depending on the query engine:

```rust

use sparq_forms::{to_sparql_update, FormDiff};

let diff = FormDiff::between(&before, &after);

let update = to_sparql_update(&before, &after);

if !update.is_empty() {

// Send `update` to a SPARQL endpoint or apply it with sparq-engine.

}

```

The descriptions must name the same focus node. Only values on editable bare

forward-predicate paths (`<p>`) participate; read-only/off-shape, inverse,

computed, and complex property-path fields are excluded. A no-change or

mismatched-focus input returns an empty update string.

What the description carries (all serde `Serialize + Deserialize`):

- **`shapes`** — the applicable-shape switcher: `sh:targetNode`,

`sh:targetClass`/implicit class targets (focus `rdf:type` with

`rdfs:subClassOf` closure in the data graph), `dash:applicableToClass`,

- **`groups[].fields[]`** — one field per property shape: SPARQL-path text

(`^<p>` for `sh:inversePath` incoming references), label/description

(`sh:name`/`sh:description`, `rdfs:label`/`rdfs:comment` fallbacks),

fractional `sh:order`, `sh:group` → `sh:PropertyGroup` sections,

`sh:deactivated` suppressed, plus an implicit trailing **"Other properties"**

group holding off-shape data triples **read-only**.

- **`widget`** — DASH widget auto-selection from the documented scoring table

(`sparq_forms::widgets` rustdoc; deviations from stock DASH are marked

*(sparq)* there): explicit `dash:editor`/`dash:viewer` win, ties break

deterministically, runner-ups land in `*_alternatives`. `Mode::View`

resolves viewers only.

- **`required` / `multi`** — `sh:minCount >= 1` / `sh:maxCount != 1` (the

add/remove affordance signal).

- **`constraints`** — per-field counts/datatypes/classes/nodeKind/`sh:in`/

pattern/length/range/`sh:or` for renderer-side guidance.

- **`hidden` / `editable` / `default_value`** — `dash:hidden true` flags a

field the renderer should omit (it still derives, with values and

constraints), `dash:readOnly true` forces `editable: false` even in edit

mode, and `sh:defaultValue` is carried verbatim as the seed term a renderer

pre-fills when a field has no values. All additive: omitted from the JSON

when the property shape does not declare them.

- **`validation`** — with `derive_form_validated(data, shapes, model, focus,

opts, registry)`, SHACL results for the focus node are attached to the

matching declared, editable field by property path. Each `ValidationHint`

carries the source-component IRI, selected shape message (or generated

fallback), optional offending value, and severity. Plain `derive_form` and

`derive_form_with_model` leave this vector empty.

- **`values[].nested`** — `sh:node` values recurse into nested sub-forms

(`dash:DetailsEditor`), `max_depth`-limited and cycle-safe.

Amortise shape parsing across focus nodes with `derive_form_with_model`

(`ShapesModel::parse` once + a `WidgetRegistry` — extend it with

`register_editor`/`register_viewer` for custom widgets), and get just the

switcher with `applicable_shapes`. Blank-node labels in the output are

renamed deterministically (`b0`, `b1`, …) — do not treat them as graph handles.

Scope: derivation, opt-in live validation hints, plus pure edit-to-UPDATE

building. An MCP agent can call the derivation as the `describe_form` tool

(sparq-mcp feature `shacl`, `FormDescription` JSON verbatim — see

[`agent-tools`](../agent-tools/SKILL.md)). [FABLE-5] sq-lsp7k.1.6. Applying the

request, validate-before-commit guards, draft graphs, DASH suggestions,

`dash:propertyRole`, and the GUI renderer are follow-on beads

(sq-lsp7k.1.2/.1.4/.1.5); `sparq-shacl` (see

[`shacl-validation`](../shacl-validation/SKILL.md)) already validates the same

graphs.

with documented (sparq) auto-selection extensions where DASH is manual-only —

InstancesSelect on sh:class, SubClass on dash:rootClass, Details on sh:node.

shapes are not evaluated (F5). (4) rdf:langString base direction untouched.)_