Intentional Arrangement SKOS

Build a real SKOS taxonomy in your browser. It validates as you type, exports to seven formats, and sticks to the standards a cataloguer would check it against. No account, no server — a static page you open and use.

Try it: https://jesstalisman-ia.github.io/intentional-arrangement-skos/ Or download the app/ folder (three static files, no build step) and open index.html from your desktop.

Informed building, not blind building. Augmentation, not automation.

Curious why it’s built this way? → Why it works this way — the thinking behind running in the browser, the license, SKOS-XL, collections, and sharing.

📍 Roadmap · 💬 Discussions (questions & ideas) · 💡 Request a feature or report a bug

---

What’s in the repo

| api/ | A small REST API (Flask + rdflib + pySHACL) to validate a vocabulary and convert between RDF serializations. |

| mcp-server/ | An MCP server exposing the same engine as tools, so an assistant like Claude can validate/convert/profile a vocabulary. |

| connectors/ | Bridges that pull external vocabularies into the editor as SKOS. First one: SharePoint Term Store → SKOS (Microsoft Graph or an offline export). Example/reference software — see its README’s disclaimer before any live use. |

| deploy/ | Optional Apache Jena Fuseki server for the app’s “Publish to server” feature — a Dockerfile that builds Fuseki 5.6.0 from the official distribution (base image pinned by digest, tarball by SHA-512). Not required; review deploy/README.md and harden before deploying. |

| docs/ | Documentation hub: install, using the editor, workspace, spreadsheet import, SKOS reference, hosting Fuseki, and the API/MCP guides. |

Where’s Jena/Fuseki? Fuseki is a separate Java server; deploy/ builds it from the official Apache distribution (Jena 5.6.0, pinned by digest + checksum) for the optional “Publish to server” feature, with a hardening checklist. The app itself never needs it — it runs fully client-side.

What the app does

• Editor. Concepts get URIs, one preferred label per language, alternate and hidden labels, an optional rdfs:label alternate name and rdfs:comment, and the run of SKOS notes: definition, scope, change, history, editorial, example. The hierarchy is real poly-hierarchy — a concept can sit under two parents. Adding a skos:related link is reciprocal, the way SKOS defines it (owl:SymmetricProperty) — it applies both ways and shows in the graph. Click a linked concept in any relationship picker to jump straight to it in the tree. Identifiers are readable slugs or opaque RFC 9562 UUIDv7 — time-ordered, canonical dashed lowercase (8-4-4-4-12), your call. Language tags are BCP 47: pick one from a code · Name dropdown or type any valid tag (nl-BE, zh-Hant), and the editor normalises letter case (NL-be → nl-BE) without changing the language. Retire a concept instead of deleting it: mark it owl:deprecated, point at its successor with dcterms:isReplacedBy, and it keeps its URI and its place in the scheme.

• ISO 25964 thesaurus relations (opt-in). Turn on ISO 25964 mode to get the specialised hierarchy alongside plain skos:broader: iso-thes:broaderGeneric (is-a), broaderPartitive (part-of), and broaderInstantial (instance-of), with their narrower inverses. All three assert their skos:broader super-property — as the iso-thes ontology declares — so plain-SKOS tools always read the hierarchy.

• Sources — documents & agents. A Sources tab for reusable foaf:Document records (dcterms:title, foaf:page, rdfs:comment) that concepts cite with dcterms:source, and prov:Agent records — prov:Person / prov:Organization / prov:SoftwareAgent with foaf:name/foaf:homepage — that you can credit as the scheme’s creator, contributor, or publisher. Laid out like Build: a tree of Documents and Agents on the left, an editor on the right; renaming a record keeps its place in the export.

• Crosswalk (thesaurus building). Align taxonomies from your workspace with the five SKOS mapping relations. Auto-match proposes links from identical/near labels; confirm or draw your own in a visual side-by-side view. Three exports, each in Turtle, RDF/XML, or JSON-LD: the crosswalk alone (mapping triples), the federated thesaurus (the current pair + mappings), or the whole federation — every taxonomy networked by mappings, in one file (available from the Crosswalk tab and from a dedicated card in the Export tab; step-by-step instructions in Using the editor). Mappings also ride along in normal exports.

• Display & filter. Show the concept tree by label (with a language picker when the vocabulary is multilingual), qualified name, or full IRI, in document order or A–Z / Z–A. The filter box highlights matches (and matches by whatever form you’re showing). Both apply to the relationship pickers as well.

• Collections. Group concepts into a skos:Collection, or an ordered skos:OrderedCollection that keeps member order. Collections sit beside the broader/narrower tree instead of inside it, and they nest — a second tree with concepts at the leaves. Inside a collection, its concept members arrange by their own broader/narrower, and a filter box highlights members. An OrderedCollection keeps its skos:memberList sequence. Nodes collapse and expand (a green ● marks each collection, an ordered badge marks ordered ones).

• SKOS-XL. Turn on SKOS-XL for a taxonomy and every label becomes a skosxl:Label resource with its own URI and optional dcterms:source provenance. The Export dialog has a SKOS-XL toggle so every download carries the skosxl:Label resources (dumbed-down to plain skos: labels too) across Turtle, RDF/XML, and JSON-LD.

• Business view. A reading layout for the people who aren’t taxonomists: breadcrumb, definition, synonyms, narrower terms. Copy a read-only share link and the taxonomy rides inside the link itself. Nothing gets uploaded.

• Validate (qSKOS + the SKOS integrity conditions). Quality checks run right in the edit loop — missing or duplicate preferred labels, label disjointness per exact literal (S13), class disjointness (S9, S37), mapping clashes (S46), related/broader conflicts, cyclic hierarchy, orphans, unmarked top concepts, undocumented concepts, non-canonical language tags, and lifecycle hygiene (a deprecated top concept, a dangling successor) — most with a one-click fix. ⬇ Report (Markdown) downloads the findings as a checkbox work list.

• Import / export. Out to Turtle, RDF/XML, JSON-LD, RDF/JSON, CSV, Excel .xlsx, and Markdown, plus a Change log: the recorded edit history as a Keep-a-Changelog CHANGELOG.md (Added / Changed / Deprecated / Removed, and the deprecated concepts with their successors). In from any of those RDF syntaxes — Turtle, RDF/XML, JSON-LD, RDF/JSON — or a spreadsheet; the import reads the file’s own default language (its dcterms:language, else the dominant label language) so new edits aren’t mistagged, and you can still override per import, row, or cell. Excel is zipped and unzipped in the browser, no library and no upload. When a file has no SKOS concepts, the tool says why instead of failing silently.

• Visualize. A force-directed picture of the scheme, synced to the editor — and not just concepts: toggles add the concept scheme as a hub (click it for its Dublin Core metadata), sources and agents (dcterms:source citations, creator/contributor/publisher attributions), and crosswalk mappings, with concepts mapped from other taxonomies in your workspace drawn as labelled external bubbles. The federation you build in Crosswalk is visible as one network.

• Scheme metadata. Dublin Core for the concept scheme. dcterms:created/issued/modified fill themselves in, dcterms:modified updates on every change, and dcterms:language is written out and read back on import.

• Scale. A 9,000-concept thesaurus imports, draws its tree, validates, and navigates in milliseconds; tree, selection, and validation are linear in the number of concepts, so a large vocabulary behaves like a small one.

• Publish to a server (optional). Connect an Apache Jena Fuseki dataset to store a taxonomy and share a short link that loads it back. See hosting Fuseki.

Your workspace

Several taxonomies at once, each autosaved to your browser with a ✓ Saved tick. An optional per-browser passcode locks the workspace (salted SHA-256 in local storage — a convenience lock, not encryption; nothing leaves the machine). A welcome screen opens an existing taxonomy or starts a fresh one. New projects begin with guided Dublin Core setup where only the title is required. Open, rename, duplicate, and delete from the Projects button. Full walkthrough: docs/workspace.md.

Three ways to use it

New here? Start with the Getting-started runbook — the fastest way in, what runs locally, and how the tool behaves hosted vs. as a local file. Install & setup goes deeper on running it locally and deploying your own copy.

1. In your browser

Open app/index.html, or serve it:

cd app && python3 -m http.server 8080     # http://localhost:8080

It’s also live on GitHub Pages.

Canonical local URL: http://localhost:8080 — the sibling tools keep their own: IA Studio on :8081, the RDF Wiki workspace server on :8070, Ontology Studio on :8083.

2. As a REST API

cd api && pip install -r requirements.txt && python server.py     # http://127.0.0.1:8000
# validate a vocabulary
curl -X POST --data-binary @vocab.ttl -H 'Content-Type: text/turtle' http://127.0.0.1:8000/validate
# convert Turtle -> JSON-LD
curl -X POST --data-binary @vocab.ttl -H 'Content-Type: text/turtle' 'http://127.0.0.1:8000/convert?to=json-ld'

See api/README.md.

3. As an MCP server

cd mcp-server && pip install -r requirements.txt && python skos_mcp.py

Register it with an MCP client (Claude Desktop / Claude Code):

{ "mcpServers": { "skos": { "command": "python", "args": ["/abs/path/mcp-server/skos_mcp.py"] } } }

Tools: validate_skos, convert_skos, skos_profile. See mcp-server/README.md.

Build it yourself

This repo is meant to be read and rebuilt, not just run. The essays in docs/ show the how: assembling a SKOS “skill” from your own example files plus Z39.19, ISO 25964, and the W3C spec; modeling from what you have; the editor’s capture-and-render choices; the business view; qSKOS; and the spreadsheet round-trip. Why it works this way covers the why.

Standards

• W3C SKOS — the RDF vocabulary for concept schemes.
• ANSI/NISO Z39.19-2005 — controlled-vocabulary construction (term form, USE/UF, BT/NT/RT, scope notes).
• ISO 25964-1/-2 — thesauri and interoperability; the iso-thes generic/partitive/instantial relations are available in ISO 25964 mode.
• DCMI / Dublin Core — concept-scheme metadata, dcterms:source, and attribution.
• FOAF (foaf:Document, foaf:page, foaf:name) and PROV-O (prov:Person/Organization/SoftwareAgent) — documents and agents in the Sources tab.
• Validation shapes: api/skos-shapes.ttl (SHACL).

Hosting

The app is live on GitHub Pages (repo Settings → Pages → Source: GitHub Actions). Because it’s three static files with no build step, you can host a copy anywhere (serve the app/ folder):

• GitHub Pages — free: fork, then Settings → Pages → Source: GitHub Actions. Lands at https://.github.io/intentional-arrangement-skos/.
• Netlify / Cloudflare Pages — free, with a custom domain. netlify.toml points the publish directory at app/, so it imports in one click; then add a domain and a CNAME record at your registrar.

All data stays in the visitor’s browser, so hosting shares the tool and never anyone’s vocabularies.

Security & dependencies

Dependencies and the Docker base image are kept current automatically: Renovate raises version-update PRs (weekly) and automerges eclipse-temurin base-image digest bumps at any time so a rebuilt base picks up OS patches on its own; Dependabot raises security-advisory PRs immediately; and a daily security-audit workflow is the backstop that catches any pin, digest, or SRI drift the bots miss. See SECURITY-AUDIT.md for the full policy and SECURITY.md to report a vulnerability.

Roadmap & feedback

ROADMAP.md tracks what’s shipped, in progress, and planned. Ideas and bug reports shape that list — several recent releases came straight from the community.

• What’s new → release notes in the repo, mirrored to Discussions → Announcements

• Ask a question / share an idea → Discussions — Q&A, Ideas, Show and tell

• Request a feature → feature request

• Report a bug → bug report

• Prefer email? → [email protected]

Rule of thumb: Discussions for how-to questions and half-formed ideas, Issues for concrete bugs and feature requests. Browse existing issues first — a 👍 on one that fits helps it rise.

Semantic Lair — the RDF Wiki, heading to beta

Semantic Lair is the RDF wiki downstream of this editor: upload a taxonomy or a whole federation export (Taxonomies → Upload from the SKOS editor) and tag documents against it. A beta is in preparation. To be considered for it, email [email protected] with the subject “Semantic Lair beta”. The SKOS editor stays free and full-featured either way.

Cloud workspace — paid tier in the works

The editor you’re using stays free and full-featured. We’re gauging interest in a low-cost paid tier that adds the platform around it: cloud storage and sync (your vocabularies follow you to any machine), a private graph database per account (isolated, versioned, append-only history), an AI taxonomy copilot (propose-and-accept drafting with provenance, bring-your-own Anthropic key), federated projects (a crosswalk pair as one editable multi-namespace project), and a guided workflow. Standard RDF in and out everywhere — leaving is always one export away.

Join the waitlist: email [email protected] with subject “Cloud workspace waitlist” — waitlist members get the first beta invites, free during beta.

License

Intentional Arrangement SKOS Editor © 2026 Contextually LLC (d/b/a Ontology Pipeline), under a size-based source-available license (see LICENSE and NOTICE):

• Organizations with fewer than 75 total employees may use, modify, and redistribute it for free under the Apache License 2.0, as modified by the Size-Based Licensing Notice.
• Organizations with 75 or more total employees must obtain a written enterprise license from the Licensor ([email protected]) before any use.

This is a source-available license, not an OSI-approved open-source license. It covers the editor and its example taxonomy. Taxonomies you create with the tool are your own — the license doesn’t touch your work product.