# moddle

> A library for importing meta-model based file formats into JS

Latest version **8.2.1** (published 2026-07-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install moddle
pnpm add moddle
yarn add moddle
bun add moddle
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 8.2.1 |
| Published | 2026-07-27 |
| First published | 2014-03-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 1 |
| Unpacked size | 215.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 111 |
| Author | Nico Rehwaldt |
| Maintainers | bpmn-io-admin, nikku, barmac, philippfromme, maxtru, skaiir-camunda, vsgoulart, barinali, ev-camunda, jarekdanielak, alekseymanetov |
| Keywords | model, meta-model, xml, xsd, import, export |

## Links

- npm: https://www.npmjs.com/package/moddle
- Repository: https://github.com/bpmn-io/moddle
- Homepage: https://github.com/bpmn-io/moddle#readme
- Issues: https://github.com/bpmn-io/moddle/issues
- npm.io page: https://npm.io/package/moddle

## Dependencies (1)

- [min-dash](https://npm.io/package/min-dash.md) ^5.1.0

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 8.2.1 (latest) — 2026-07-27
- 7.0.0-exp.3 (next) — 2023-02-24
- 8.2.0 — 2026-07-15
- 8.1.0 — 2026-02-13
- 8.0.0 — 2026-01-15
- 7.2.0 — 2024-12-20
- 7.1.0 — 2024-12-19
- 7.0.0 — 2024-03-05
- 6.2.3 — 2023-05-04
- 6.2.2 — 2023-05-04
- 6.2.1 — 2023-02-24
- 7.0.0-exp.2 — 2023-02-23
- 7.0.0-exp.1 — 2022-12-21
- 6.2.0 — 2022-12-21
- 6.1.0 — 2022-12-20
- … 32 more at https://npm.io/package/moddle/versions

## README

# moddle

[![CI](https://github.com/bpmn-io/moddle/workflows/CI/badge.svg)](https://github.com/bpmn-io/moddle/actions?query=workflow%3ACI)

A utility library for working with meta-model based data structures.


## What is it good for?

[moddle](https://github.com/bpmn-io/moddle) offers you a concise way to define [meta models](https://en.wikipedia.org/wiki/Metamodeling) in JavaScript. You can use these models to consume documents, create model elements, and perform model validation.


### Define a schema

You start by creating a [moddle schema](./docs/descriptor.md). It is a [JSON](http://json.org/) file which describes types, their properties, and relationships:

```json
{
  "$schema": "https://unpkg.com/moddle/resources/schema/moddle.json",
  "name": "Cars",
  "uri": "http://cars",
  "prefix": "c",
  "types": [
    {
      "name": "Base",
      "properties": [
        { "name": "id", "type": "String", "isAttr": true }
      ]
    },
    {
      "name": "Root",
      "superClass": [ "Base" ],
      "properties": [
        { "name": "cars", "type": "Car", "isMany": true }
      ]
    },
    {
      "name": "Car",
      "superClass": [ "Base" ],
      "properties": [
        { "name": "name", "type": "String", "isAttr": true, "default": "No Name" },
        { "name": "power", "type": "Integer", "isAttr": true },
        { "name": "similar", "type": "Car", "isMany": true, "isReference": true },
        { "name": "trunk", "type": "Element", "isMany": true }
      ]
    }
  ]
}
```

You may attach the provided [JSON schema](./resources/schema/moddle.json) to get your moddle descriptor validated by code editor.


### Instantiate moddle

You can instantiate a moddle instance with a set of defined schemas:

```javascript
import { Moddle } from 'moddle';

var cars = new Moddle([ carsJSON ]);
```


### Create objects

Use a [moddle](https://github.com/bpmn-io/moddle) instance to create objects of your defined types:

```javascript
var taiga = cars.create('c:Car', { name: 'Taiga' });

console.log(taiga);
// { $type: 'c:Car', name: 'Taiga' };


var cheapCar = cars.create('c:Car');

console.log(cheapCar.name);
// "No Name"


// really?
cheapCar.get('similar').push(taiga);
```


### Introspect things

Then again, given the knowledge [moddle](https://github.com/bpmn-io/moddle) has, you can perform deep introspection:

```javascript
var carDescriptor = cheapCar.$descriptor;

console.log(carDescriptor.properties);
// [ { name: 'id', type: 'String', ... }, { name: 'name', type: 'String', ...} ... ]
```


### Access extensions

moddle is friendly towards extensions and keeps unknown _any_ properties around:

```javascript
taiga.set('specialProperty', 'not known to moddle');

console.log(taiga.get('specialProperty'));
// 'not known to moddle'
```

It also allows you to create _any_ elements for namespaces that you did not explicitly define:

```javascript
var screwdriver = cars.createAny('tools:Screwdriver', 'http://tools', {
  make: 'ScrewIt!'
});

car.trunk.push(screwdriver);
```


### There is more

Have a look at our [test coverage](https://github.com/bpmn-io/moddle/blob/master/test/spec) to learn about everything that is currently supported.


## Resources

* [Issues](https://github.com/bpmn-io/moddle/issues)
* [Examples](https://github.com/bpmn-io/moddle/tree/master/test/fixtures/model)
* [Documentation](https://github.com/bpmn-io/moddle/tree/master/docs)


## Related

* [moddle-xml](https://github.com/bpmn-io/moddle-xml): read xml documents based on moddle descriptors


## License

MIT

---
_Source: https://npm.io/package/moddle · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._