LinkML-Scala

LinkML is an open framework that simplifies authoring, validating, and sharing data. You write your data model once in a simple YAML format. LinkML then generates code, schemas, and validation rules for multiple programming languages and data formats (e.g., JSON Schema, CSV, RDF/SHACL...).

LinkML-Scala is a robust, cross-platform implementation of LinkML. It works in the JVM, in your browser or Node.js, and even compiles to native binaries. We have a command-line interface (CLI), a library for programmatic access, and a GitHub Action.

Why LinkML-Scala?

🚀 It's really fast!

LinkML-Scala was built to work great with large schemas. In our benchmarks it's 22.9–38.5x faster than the Python implementation:

📊 See the benchmarks.

🌐 Works in the browser, Node.js, and in the JVM

LinkML-Scala compiles to pure JavaScript (zero dependencies, no Wasm), so you can use it in your browser or Node.js environment. Try it out in our online playground, or get it from npm.

For Java, Scala, Kotlin and other JVM languages, LinkML-Scala is available on Maven Central.

⚡ Natively compiled binaries for Linux, macOS, and Windows

linkml-scala is a self-contained binary that runs natively on Linux, macOS, and Windows. You don't need Python, Java, or anything else installed.

It starts up immediately and runs fast, even on extra-large LinkML models. See the installation instructions.

It's also possible to compile LinkML-Scala to a native shared library for use in Rust, C, C++, and other languages. Let us know if you would like to see this feature!

🛡️ Consistent, reliable, and with great error reporting

LinkML-Scala will tell you exactly what is wrong with your model, and where:

The validator can also return a machine-readable JSON report (schema), useful for UIs and scripts.

We engineered it to be as consistent as possible, so you are much less likely to run into "fun surprises" when using it with different generators. We test each generator across the same extensive suite of LinkML models.

In some cases, LinkML-Scala diverges from the Python implementation, or is missing some features. You can find the list of implementation differences here.

CLI tool installation

Method 1: Install script (recommended for Unix/macOS)

If you are on Linux (x86-64, ARM64), macOS (x86-64, ARM64), or using WSL on Windows, the easiest way to grab the latest release is via our installation script:

. <(curl -sSfL https://raw.githubusercontent.com/NeverBlink-OSS/linkml-scala/refs/heads/main/cli/install.sh)
linkml-scala

Read the script before running it: install.sh.

Method 2: Using mise (cross-platform)

You can install linkml-scala on any platform (including Windows) using the mise environment manager:

mise use 'ubi:NeverBlink-OSS/linkml-scala'
linkml-scala

Or pin a specific version (recommended for reproducible setups, e.g. in a project's mise.toml):

mise use 'ubi:NeverBlink-OSS/linkml-scala@v0.12.0'
linkml-scala

Method 3: Manual download

If you prefer a manual setup, head over to Releases and download the pre-compiled binary for your specific OS and architecture.

For macOS and Linux: Rename the downloaded file, make it executable, and run it:

mv linkml-scala-<os>-<arch> linkml-scala
chmod +x linkml-scala
./linkml-scala

For Windows: Simply rename the downloaded executable, and run it:

ren linkml-scala-windows-x86_64.exe linkml-scala.exe
linkml-scala.exe

Releases ship a SHA256SUMS manifest and a signed build provenance attestation, so you can confirm a download came from our release workflow. See how to verify it.

CLI – getting started

LinkML schema validation

The validate command (also available as lint) inspects your LinkML schemas for structural and logical issues:

linkml-scala validate <input-file> ...

The CLI outputs issues directly to your terminal, categorized into three severity levels:

• Fatal: critical blockers (unknown references, invalid range types, used undefined default range)
• Errors: structural violations (multiple keys or ID slots, multiple tree roots, ID collisions)
• Warnings: non-critical issues (invalid slot usage, undefined default range, missing tree root)

All generators require that there are no fatal issues in the schema. The process will report these and exit immediately, as generation cannot proceed.

Generators

Generate a standard JSON Schema from your model:

linkml-scala generate json-schema <input-file>

Generate SHACL (Shapes Constraint Language) graphs for RDF validation:

linkml-scala generate shacl --to <output-path> <input-file>

There's more! Run linkml-scala --help to see the full list of supported generators. You can also run linkml-scala generate shacl --help to see the options for any specific generator.

LinkML schema derivation and pruning

Generate a LinkML model that:

• Has all imports resolved
• Has all class slots materialized into attributes (opt out by passing --skip-derivation)
• Has all unused elements removed (controlled by --pruning-mode)

./linkml-scala generate linkml --to <output-path> <input-file>

JavaScript / TypeScript library

The generator is also published to npm as @neverblink/linkml – a single self-contained ES module (with TypeScript declarations) compiled from Scala via Scala.js, with no runtime dependencies.

npm install @neverblink/linkml

import { LinkML } from "@neverblink/linkml";

// Parse once into a reusable SchemaView handle. The second argument is an
// import map (filename -> YAML) for `imports:`; pass {} when there are none.
const view = LinkML.loadFromString(mySchemaYaml, {});
const jsonSchema = LinkML.jsonSchema(view);

Load a schema with loadFromString (from YAML text) or loadFromPath (from a path in the import map, immune to cyclic imports involving the root), then run jsonSchema, shacl, rdfs, linkml, scala, tableSchema, or lint against the returned handle. See generator/npm/README.md for details.

JVM library

All modules are published to Maven Central under the eu.neverblink.linkml group ID. Best way to get started is to either browse the Javadoc or read the CLI's source code.

GitHub Action (CI)

We have a pre-packaged GitHub Action that can do schema validation and generation in your CI pipelines. See NeverBlink-OSS/linkml-scala-action for more details.

Agent skill (Claude Code, Codex, …)

We ship an agent skill that teaches coding agents to author, validate, review and release LinkML schemas with LinkML-Scala. See .agents/README.md for what it covers.

It drives the CLI, so install that first (see CLI tool installation). Version 0.12.0 or newer is required.

Claude Code – install it as a plugin:

/plugin marketplace add NeverBlink-OSS/linkml-scala
/plugin install linkml@linkml-scala

Codex – add this repository as a plugin marketplace, then install linkml from /plugins:

codex plugin marketplace add NeverBlink-OSS/linkml-scala

If you added the marketplace before, refresh it first with codex plugin marketplace upgrade linkml-scala.

Cursor, OpenCode, and any other agent – these load Agent Skills directly from the vendor-neutral ~/.agents/skills/ directory:

git clone --depth=1 https://github.com/NeverBlink-OSS/linkml-scala /tmp/linkml-scala
mkdir -p ~/.agents/skills
cp -r /tmp/linkml-scala/.agents/skills/linkml ~/.agents/skills/

Contributing

This project is governed by our Code of Conduct, adapted from the Mozilla Community Participation Guidelines.

See CONTRIBUTING.md for build instructions, common mill tasks, and how to contribute.

Have a question, an idea, or just want to say hi? Join our Discord – we're happy to help.

License and maintainers

LinkML-Scala is licensed under the Apache License 2.0. See the LICENSE file for details.

This project is being developed and maintained by NeverBlink. For any inquiries, please reach out to us via email.

---

This work has been supported by the HEDGE-IoT project grant number 101136216 funded by the European Commission as part of the Horizon Europe Framework Programme. However, views and opinions expressed are those of the authors only and do not necessarily reflect those of the European Union or the European Climate, Infrastructure and Environment Executive Agency. Neither the European Union nor the granting authority can be held responsible for them.