Documentation

ESSE — the Essential Source of Schemas and Examples — is an ontology for digital materials science, written as JSON Schema. It fixes what kinds of thing exist in the domain — materials, models, methods, properties, workflows, jobs — and how they relate, then ships worked examples of each. Because the ontology is expressed as JSON Schema rather than OWL, it validates real records directly instead of describing a world something else must conform to.

That combination is what makes it useful as a data standard for machine learning and for agents: the entity types, their fields, their units and their relationships are all declared, checkable, and stable under a $id, so nothing has to be inferred from examples.

The schema explorer shows you any single schema, and browses the corpus three ways — by file, by category, or by directory. The ontology map shows you the ontology whole — every entity type and every relationship between them. These pages explain why the schemas are shaped the way they are, which is the part neither of the other two can tell you.

Where to start

If you are new, read the first four pages in order — they are the argument, and the rest are reference:

1. Why ESSE exists — schemas as the shared source of truth, and what the three papers behind this repository contribute.
2. Schema layering — the build-up from primitives to entities, and why the layers are separate.
3. Entity anatomy — the root entities, how they compose, and the material variant family.
4. Categorization — CateCom tiers for models and methods, M-CODE composition for materials, and the *_category versus *_directory split that names half the repository.

Then, as you need them:

5. Behavioural mixins — how allOf stacks platform behaviour onto domain payloads.
6. Conventions — $ids, includes, generative keys, formatting, and the URL contracts.
7. The pipeline — how JSON sources become packages, types and this site, and what the two runtimes do and do not guarantee.
8. Consuming ESSE — using the schemas from Python and JavaScript.
9. Contributing a schema — a worked example, end to end.
10. Glossary — the vocabulary, in one place.

Conventions in these pages

Every claim about the corpus — counts, relationships, coverage — is generated from the schema sources at build time rather than typed by hand, so these pages cannot quietly fall out of step with the schemas they describe. Schema names link to their place on the ontology map.