ESSE

Essential Source of Schemas and Examples (ESSE) contains data format definitions (schemas) and examples for common entities used in digital materials science (see refs. ¹, ² below).

Although the schemas are used to facilitate the operations of mat3ra.com, they are designed to be generic and can be used in other applications. The open-source packages developed by Mat3ra.com use the schemas available in this repository.

The latest variants of schemas and examples are available at schemas.mat3ra.com, which has three surfaces:

Documentation — how ESSE is put together and why: the schema layering, entity anatomy, categorization, conventions and the build pipeline. Start here if you are new.
Explorer — a file browser over every resolved schema and example.
Ontology — an interactive map of the ontology: every entity type and every relationship the schemas declare between them (extends, contains, variant), laid out by architectural layer — primitives at the centre, root entities around them, catalogues on the rim. Search for a schema, fly to it, and follow what it extends, contains and is used by.

The map is built from graph.json, an extracted reference graph that is also published at schemas.mat3ra.com/graph.json and doubles as a lint over the corpus.

ESSE has a dual-nature as both a Python and a Node.js package.

1. Installation

1.1. Python

ESSE is compatible with Python 3.8+.

1.1.1. PyPI

pip install mat3ra-esse

1.1.2. Repository

virtualenv .venv
source .venv/bin/activate
pip install -e PATH_TO_ESSE_REPOSITORY

1.2. Node

1.2.1. NPM

npm install @mat3ra/esse

2. Usage

ESSE contains separate but equivalent interfaces for Python and Javascript. The package provides ESSE class that can be initialized and used as below.

2.1. Usage in Python

from mat3ra.esse import ESSE

helper = ESSE()
schema = helper.get_schema_by_id("material")

# standalone schema validation and cleaning
from mat3ra.esse import validate_and_clean

data = {"a": "x", "b": 1, "c": "drop"}
schema = {
    "type": "object",
    "properties": {
        "a": {"type": "string"},
        "b": {"type": "integer"}
    }
}

validate_and_clean(data, schema)
print(data) # {"a": "x", "b": 1}

# alternative: schema-aware cleaning via generated pydantic models
# also see how it is used in ade: https://github.com/mat3ra/ade/blob/main/src/py/mat3ra/ade/application.py
from pydantic import ConfigDict
from mat3ra.esse.models.software.application import ApplicationSchemaBase


class Application(ApplicationSchemaBase):
    # drop keys the schema doesn't declare at construction time
    model_config = ConfigDict(extra="ignore")


config = {"name": "espresso", "version": "6.3", "buildConfig": {"moduleName": "6.3-gnu"}}
app = Application(**config)
print(app.model_dump(exclude_none=True)) # {"name": "espresso", "version": "6.3", ...}

2.2. Usage in Node/JS/TS

const { ESSE } = require("@mat3ra/esse/lib/js/esse");

const helper = new ESSE();
const schema = helper.getSchemaById("material");

# schema validation and cleaning
const { validateAndClean } = require("@mat3ra/esse/lib/js/esse");

const data = {"a": "x", "b": 1, "c": "drop"};
const schema = {
    "type": "object",
    "properties": {
        "a": {"type": "string"},
        "b": {"type": "integer"}
    }
}

const result = validateAndClean(data, schema);
console.log(result); // {"a": "x", "b": 1}

3. Directory Structure

ESSE contains 3 main directories, schema, example and src outlined below, plus docs (documentation sources) and plan (design documents).

3.1. Schema

The schema directory contains the schemas specifying the rules to structure data. A set of core schemas, outlined below, are defined to facilitate the schema modularity.

Primitive directory contains a set of custom primitives that extends default standard primitive types allowed by schema, such as String and Number. Primitives are solely defined by the default primitives and can not be re-constructed from each other.
Abstract directory contains unit-less schemas that are constructed from default and custom primitives.
Reusable directory contains the schemas that are widely used in other schemas to avoid duplication, constructed from the abstract and primitive schemas.
Reference directory contains the schemas defining the rules to structure the references to data sources.

3.2. Example

This directory contains the examples formed according to the schemas and implements the same directory structure as the schema directory.

3.3. src

This directory contains Python and Javascript interfaces implementing the functionality to access and validate schemas and examples.

3.4. docs

Markdown sources for the concept documentation, rendered to HTML at deploy time. Pages may embed generated fragments () that are expanded from the entity graph, so counts and relationship listings cannot drift from the schemas.

3.5. plan

Design documents, filed by status (upcoming/, review/, implemented/, context/) per the convention in mat3ra/agents. See plan/README.md.

4. Conventions

4.1. Generative vs Non-generative keys

Generative keys are the fields which allow for user input prior to calculation of the final property values. A flag is included in the schema comments on the fields in property schemas: isGenerative:true marks which fields to use as subschemas in the generation of a user input schema. On properties allowing user inputs, additional fields may be tagged, as in the file_content property

5. Development

The schemas and examples are stored as JSON assets. The JSON assets are used to generate JS/TS and PY modules that can be used to access the schemas and examples in the corresponding runtimes. The modules are generated using the build_schemas.py and build_schema.js scripts. The JS modules are generated during the transpilation step of the npm. The PY modules are generated during the development and distributed within the pip package.

The following outlines the development process workflow:

Setup: clone the repository and install the dependencies for both JS and PY (as explained below).
Edit code and commit changes.
Pre commit is used to regenerate the modules.
Push the changes to GitHub.
GH workflow is used to generate the fully resolved file (without "$ref"s and "$allOf" etc.) and examples, render the documentation and the ontology map, and publish them to schemas.mat3ra.com. The site is assembled in a gitignored site/ staging directory; internal links are checked before it deploys.
Publish the new version of the package to PyPI and npm.

The pre-commit is using both JS and PY runtime(s) to regenerate the schemas and examples.

NOTE: The PY and JS modules are built from the same JSON sources, but using different runtimes (scripts) and thus may still be different. Only for JS the fully resolved schemas (with merged "$allOf") are created. They are used for the docs website.

5.1. Development in Python

When developing in python the following should be taken into account:

The modules containing the schemas and examples are generated using the build-schemas.py script. There is a setup for it to be run automatically on every commit, but it is recommended to run it manually before committing to make sure that the changes are reflected in the modules. This can be done with pre-commit run --all-files. The pre-commit package can be installed with pip install pre-commit. To rebuild schemas manually, run (note -e in install):
```
python -m venv .venv
source .venv/bin/activate
pip install -e ".[tests]"
pip install pre-commit
pre-commit --install
git config --unset-all core.hooksPath
python build_schemas.py
```

Tests can be run using the following commands:

python -m venv .venv
source .venv/bin/activate
pip install ".[tests]"
python -m unittest discover --verbose --catch --start-directory tests/py/esse/

5.2. Development in Javascript/Typescript

See package.json for the list of available npm commands. The JS modules are generated using the build_schema.js script. There is a setup for it to be run automatically when the package is installed (see "transpile" directive). To rebuild schemas manually, run:

npm install
npm run transpile

5.3. General Dev Suggestions

This repository is an open-source work-in-progress and we welcome contributions. We suggest forking this repository and introducing the adjustments there, the changes in the fork can further be considered for merging into this repository as it is commonly done on GitHub (see ³ below).

Other suggestions:

Use unique IDs for schemas
Do not use circular references in the schemas, instead leave the type as object and add explanation to description.

The schema lint (npm run lint-entity-graph, also part of npm test) enforces both of the above along with $id conventions, JSON-pointer targets and manifest references. Contributing a schema walks through adding one end to end.

Release files for mat3ra-esse 2026.9.6.post1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mat3ra-esse 2026.9.6.post1
File	Size	Uploaded
mat3ra_esse-2026.9.6.post1.tar.gz	951.8 kB	Sep 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mat3ra-esse 2026.9.6.post1
File	Interpreter	ABI	Platform	Reset
mat3ra_esse-2026.9.6.post1-py3-none-any.whl 1.1 MB Sep 6, 2026	Python 3	none	any	Details

Total release size: 2.0 MB

Release files / mat3ra_esse-2026.9.6.post1.tar.gz

Download URL	mat3ra_esse-2026.9.6.post1.tar.gz
Size	951.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`a9b7b7a11a953a969a8f24bfee6696337c1a75aa9a84e67607cabd7d51932fc6`
BLAKE2b-256 checksum How to use checksums	`4d56ee3875a7662389acd1e2eaa30682476f1b1736f2dbaabf31f1641c407ae4`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/9.0.1 pkginfo/1.13 requests/2.34.2 requests-toolbelt/1.0.0 tqdm/4.70.0 CPython/3.10.13`

Release files / mat3ra_esse-2026.9.6.post1-py3-none-any.whl

Download URL	mat3ra_esse-2026.9.6.post1-py3-none-any.whl
Size	1.1 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`3f4c21af77f8b166f0f0705b413e2a4a3f1f4bc50288c2101739a06e06a2bdac`
BLAKE2b-256 checksum How to use checksums	`18819bd8e6db7930d0bc1ca1fafd5f50093189aaf46f24f5b3d718e42deae1c4`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/9.0.1 pkginfo/1.13 requests/2.34.2 requests-toolbelt/1.0.0 tqdm/4.70.0 CPython/3.10.13`