RDForms

RDForms (aka RDF Forms) is a JavaScript library that uses templates to describe how to edit, present and validate RDF. The library is intended to be used in web applications to ease the burden of developers to deal natively with RDF.

RDForms is designed to be adaptable to different UI libraries. Integrations ("flavors") are provided for:

• React (with Material UI)
• Bootstrap 4
• jQuery
• Vanilla — semantic HTML with no JavaScript library and no CSS framework (presentation only; see the "Vanilla presentation flavor" section below)

Deeper documentation for RDForms can be found at rdforms.org.

Templates

The templates that drives RDForms are expressed as JSON structures. Templates can be divided into profile-level and field-level templates. A typical scenario is that a template author combines a set of field-level templates into a bigger profile-level template to meet a specific need. Such a profile-level template could correspond to well known application profiles (for example a dataset according the W3C Recommendation DCAT2) or correspond to a specific class in an ontology defined for a specific purpose in a project. Field-level templates are often reused across profiles but may require tweaking in various ways, for instance changing a label, restricting cardinality, refining a constraint etc. For this purpose there is an extension mechanism that allows tweaks to be made without forcing the template author to fork the template by making a full copy.

Read more about the templates in the reference guide at the documentation site.

How to use RDForms

In addition to the RDForms library you need to load the RDF library rdfjson and then initialize an Editor, Presenter or Validator on a DOM node. Below is a high-level example, for more detailed information on how to prepare the parameters look at the examples.

<script type="text/javascript" src="https://unpkg.com/@entryscape/rdfjson@2.3.0/dist/rdfjson.js"></script>
<script type="text/javascript" src="https://unpkg.com/@entryscape/rdforms@10.0.0/dist/rdforms.react.js"></script>
<script type="module">
    // Make sure to provide the parameters graph, resource and template
    new Editor({ graph, resource, template }, 'node_id');
<script>

The exact versions above (2.3.0 and 10.0.0) may vary, please check for yourself the latest versions in package.json. Naturally you can also use the built version in the dist folder, see the next section.

Installing and building

Before you can install dependencies and build RDForms you need to make sure you have nodejs, npm and pnpm installed in your system. To install dependencies for RDForms:

pnpm install

To build RDForms:

pnpm build:all

Samples

A good way to see the capabilities of RDForms is to take a look at the samples (generated from the examples, see section below). To generate the samples just run:

pnpm build:samples

This will build the samples in the samples directory. You'd need a web server to serve the samples. We provide a simple one for your convenience:

pnpm serve:samples

Your browser should open automatically, otherwise access the samples at http://localhost:8080/.

Tests

Unit tests run on Jest and live next to the source as *.test.js files (model/template logic under src/model and src/template, the view flavors under src/view). Run them with:

pnpm test

or in watch mode:

pnpm test:watch

Jest is configured as two projects: a node project for the model/template logic and a jsdom project for the view layer (src/view/**), so the generated presentation HTML can be asserted against real DOM.

Smoke test (all flavors × examples)

pnpm test:smoke is a headless end-to-end check that guards against a flavor breaking one of the examples. It starts the all-flavors dev server in-process and, using Playwright, loads every flavor × example page and asserts that each renders into #node with no uncaught exceptions and no application console errors. It exits non-zero if any cell fails.

It needs the Playwright Chromium browser once:

pnpm exec playwright install chromium
pnpm test:smoke

The smoke test is local-only (not part of CI).

Development

You can develop the different UI libraries as well as the part of the generic code base by running the examples in the webpack-dev-server:

pnpm dev:react

or

pnpm dev:bootstrap

or

pnpm dev:jquery

or

pnpm dev:vanilla

To run all flavors from a single server — each example rendered by every flavor, with a top-level index at http://localhost:8080/ linking the whole flavor × example matrix — use:

pnpm dev:all

Because the flavors share a global rendering context (one flavor per page), each cell in the matrix loads exactly one flavor bundle under /<flavor>/example<n>/.

The vanilla example pages (under both dev:vanilla and dev:all) include a "Basic vanilla CSS" checkbox that links and toggles the opt-in stylesheet, so you can flip between the minimal styled output and the raw semantic HTML on browser default styles (e.g. to see the parentheses around a language-tagged value's language code, or the validation-state colors, appear and disappear).

Vanilla presentation flavor

dist/rdforms.vanilla.js is a presentation-only flavor that renders semantic HTML with no JavaScript library (React/jQuery) and no CSS framework (Bootstrap) — for better accessibility and easier integration into host platforms. It coexists with the other flavors (load exactly one per page).

• Groups → <dl class="rdforms-group">, labels → <dt>, values → <dd> (repeated values → repeated <dd>), nested groups → nested <dl>.
• Heading-styled groups → <section> + <h2>/<h3> (level tracks nesting depth, capped at <h6>); table-styled groups → a real <table> with <caption>, <thead>/<th scope="col"> and <tbody>; language literals carry lang (with the code also shown when showLanguage is on), dates and durations render as <time datetime>, and URIs/choices as <a href>.
• The flavor's own structural classes use the hyphenated rdforms-* namespace — a stable public integration surface, deliberately distinct from the other flavors' rdforms* camelCase classes so there is no overlap with Bootstrap. A few classes in the output are shared with the rest of the library rather than vanilla-specific: the validation-state markers (error/warning/deprecated), the base rdforms / compact utility classes, rdformsInvisibleGroup for noLabelInPresent groups, and — on the ValidationPresenter root — the rdformsPresenter rdformsValidator marker injected by the shared validation logic.

<script type="text/javascript" src="https://unpkg.com/@entryscape/rdforms/dist/rdforms.vanilla.js"></script>
<script type="module">
    new rdforms.VanillaPresenter({ graph, resource, template }, 'node_id');
</script>

The flavor also ships a ValidationPresenter (new rdforms.ValidationPresenter({ graph, resource, template }, 'node_id')) that renders the same semantic HTML with validation markers — an error/warning/deprecated class on the affected value and a <p class="rdforms-validation …"> message (role="alert" for errors, role="status" for warnings and deprecations).

Styling is opt-in

Unlike the other flavors (which inject their CSS/framework automatically), the vanilla bundle ships no styles — loading rdforms.vanilla.js emits plain semantic HTML that renders acceptably on the browser's default styles. For a minimal starting look, <link> the separately-shipped stylesheet, then override or replace it as needed:

<link rel="stylesheet" href="https://unpkg.com/@entryscape/rdforms/dist/rdforms.vanilla.css" />

It is intentionally minimal — mostly layout (margins, table borders) plus the validation-state colors (e.g. .rdforms-value.error { color: #b00020 }) and a rule that parenthesizes the language code of language-tagged values. It stays within the rdforms-* namespace where it can, so it won't leak into or clash with host styles (the validation-state selectors piggyback on the shared, unnamespaced error/warning/deprecated classes). During development you can flip it on and off with the "Basic vanilla CSS" checkbox on the vanilla example pages (see below).

Editors are out of scope for this flavor (presentation only).

Value truncation (the truncate / truncateLimit options) works differently here than in the other flavors. Where jquery/react/bootstrap truncate a single property's repeated values and hide the overflow with display:none, the vanilla flavor truncates by property row: truncateLimit counts <dt> rows, so a shown property keeps all of its <dd> values, and overflow rows are the trailing whole properties. Nothing is hidden with display:none and no JavaScript library is used — the overflow <dt>/<dd> nodes are simply held out of the DOM and re-inserted by a plain <button class="rdforms-show-more"> placed after the <dl> (never inside it). The button carries aria-expanded (announced on both expand and collapse), and on expand focus moves to the first revealed row so the newly shown content — which sits before the button in reading order — is where the user lands. Truncation is opt-in via the view-level truncate option or a truncate style, and suppressed by a noTruncate style. Because it operates on whole property rows rather than a single property's values, this flavor reads those styles from the group item — unlike jquery/react/bootstrap, which read them from each individual property — so place the truncate/noTruncate style on the group to enable or suppress row-level truncation here.

Tables are out of scope for row-level truncation: a table-styled child renders in full and does not count toward truncateLimit. Avoid pairing a table-styled property with row-level truncation in the same group — the table renders directly in the live <dl> while overflow rows are parked, so on expand the revealed rows are appended after the table rather than in template order.

Examples

The examples serve two purposes:

1. Showcase the capabilites of RDForms.
2. Provide good ground for development and testing.

Running the examples

The example sources live in the html/ directory — one folder per example (example1 … example8), each with an index.html and an init.js that builds the graph, template and view. There are two ways to run them:

• Dev server (live reload) — pnpm dev:<flavor> (react, bootstrap, jquery or vanilla) starts webpack-dev-server, opens your browser, and serves each example at http://localhost:8080/example<n>/. The flavor you launch decides which bundle the examples load, so it's the quickest way to try a template against a specific flavor.
• Built samples — pnpm build:samples then pnpm serve:samples writes static copies under samples/<flavor>/ (the editor-capable flavors only — bootstrap and react) and serves them at http://localhost:8080/<flavor>/example<n>/ (the links below use this layout).

Note: the editor examples (e.g. example1) need an editor-capable flavor (react or bootstrap); the jquery and vanilla flavors are presentation-only, so editor examples fall back to a read-only presenter under them.

The examples are outlined below:

example1 - Editor for one field

1. Loads the library and its CSS.
2. Creates a minimal RDF graph manually.
3. Creates a minimal RDForms template manually.
4. Creates the editor UI from the RDF graph, a given resource, a template and an HTML node.

Check example1/init.js for more.

example2 - Editor for large template loaded from file

Different from example1 in the sense that it loads the graph and template from separate files. Check example2/init.js for more.

example3 - Presenter

Same template and data as in example2, but now the presenter is used instead. Check example3/init.js for more.

example4 - Validation presenter

This examples shows how RDForms can be used as a form validator rather than just an editor or presenter. Take a look at the validation report inside the form presenter.

Check example4/init.js for more.

example5 - Building on default templates

This examples utilizes pre-made templates to render forms. It can serve as a very good start for extending them and creating your own custom forms.

Check example5/init.js for more.

example6 - RDF output from editor (Template is for Dataset according to DCAT-AP)

This example provides a ready output to check your form RDF output live.

Check example6/init.js for more.

example7 - RDForm editor with a registered chooser

This is a more advanced example providing some guidance on how to create your own choosers and register them to show on select fields in your forms. You can even have your data be fetched across the network.

Check example7/init.js for more.