SOF-8025: lead with the ontology, and with "AI for Materials" as the wordmark

README.md

@@ -12,7 +12,7 @@ The latest variants of schemas and examples are available at [schemas.mat3ra.com
 
 - **[Documentation](https://schemas.mat3ra.com/docs/)** — 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](https://schemas.mat3ra.com/)** — a file browser over every resolved schema and example.
-- **[Entity Map](https://schemas.mat3ra.com/map/)** — an interactive map of all schemas and the references between them, 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.
+- **[Ontology](https://schemas.mat3ra.com/map/)** — 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](https://schemas.mat3ra.com/graph.json) and doubles as a lint over the corpus.
 
@@ -160,7 +160,7 @@ The following outlines the development process workflow:
 2. Edit code and commit changes.
 3. Pre commit is used to regenerate the modules.
 4. Push the changes to GitHub.
-5. GH workflow is used to generate the fully resolved file (without "$ref"s and "$allOf" etc.) and examples, render the documentation and the Entity Map, and publish them to [schemas.mat3ra.com](http://schemas.mat3ra.com/). The site is assembled in a gitignored `site/` staging directory; internal links are checked before it deploys.
+5. 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](http://schemas.mat3ra.com/). The site is assembled in a gitignored `site/` staging directory; internal links are checked before it deploys.
 6. Publish the new version of the package to PyPI and npm.
 
 The [pre-commit](.husky/pre-commit) is using both JS and PY runtime(s) to regenerate the schemas and examples.

docs/01-why-esse-exists.md

@@ -16,6 +16,32 @@ another.
 ESSE is one answer to that. It defines the entities of the domain as data, in JSON Schema, once,
 and treats those definitions as the authoritative description that everything else derives from.
 
+## An ontology, written as JSON Schema
+
+It is worth naming what this corpus actually is. An ontology, in the working sense, is a formal
+and explicit specification of a shared conceptualization: it fixes *what kinds of thing exist* in
+a domain and *how they relate*. ESSE does exactly that, and the relationships are not editorial —
+they are declared in the schemas and mechanically extractable:
+
+<!-- generated:ontology-relations -->
+
+Those three relation kinds are the familiar ontological ones. `extends` is subsumption: a
+`material` **is a** named, defaultable in-memory entity. `contains` is composition: a `model`
+**has a** `method`. `variant` is disjunction: a property holder's `data` **is one of** the
+property types. On top of them sit controlled vocabularies — `definitions/units`, the tier
+enumerations — that constrain what the leaves may say.
+
+What ESSE deliberately is *not* is an OWL/RDF ontology with a description-logic reasoner behind
+it. There are no inferred axioms and nothing computes a subsumption closure at runtime. The trade
+is intentional: because the ontology is expressed in JSON Schema, it *validates real records
+directly* with an off-the-shelf validator, rather than describing a world that some other artifact
+is then trusted to conform to. The conceptual model and the wire format are the same file.
+
+That is also what makes the corpus useful to machine learning and to agents. A model trained on,
+or an agent navigating, this data does not have to infer the schema from examples: the entity
+types, their fields, their units and their relationships are all declared, checkable, and stable
+under a `$id`.
+
 ## Schemas first, not code first
 
 The tempting alternative is to define entities in code — a `Material` class in Python, another in
@@ -86,4 +112,4 @@ The corpus at a glance, and how densely it is cross-referenced:
 <!-- generated:corpus-totals -->
 
 Those references are not incidental. They are what makes the collection a system rather than a
-folder of files, and they are what the [Entity Map](../map/index.html) draws.
+folder of files, and they are what the [ontology map](../map/index.html) draws.

docs/02-schema-layering.md

@@ -11,7 +11,7 @@ layers beneath it. This is the single most useful thing to understand about the
 you know which layer a schema belongs to, you know roughly what it may contain, what may depend on
 it, and where to add something new.
 
-The [Entity Map](../map/index.html) draws these layers literally — primitives sit at the centre and
+The [ontology map](../map/index.html) draws these layers literally — primitives sit at the centre and
 each ring outward is a layer further up the build-up.
 
 ## The layers
@@ -93,7 +93,7 @@ predicts:
 <!-- generated:hub-table -->
 
 A schema high in this table is one you should be careful changing: a great deal depends on it.
-The Entity Map draws these larger than their neighbours for the same reason.
+The ontology map draws these larger than their neighbours for the same reason.
 
 ## Why keep the layers separate at all?
 

docs/03-entity-anatomy.md

@@ -98,12 +98,12 @@ states, charge density), `structural`, `elemental` and `workflow` (convergence m
 They are tied together by `property/holder`, which is the widest schema in the corpus: its `data`
 field is a union over every property type, on top of one mixin and one provenance reference. That
 one file is why "what property types exist?" has a single answer, and it is the clearest
-illustration of the union idiom in ESSE. On the [Entity Map](../map/index.html) it is the node
+illustration of the union idiom in ESSE. On the [ontology map](../map/index.html) it is the node
 with by far the largest fan-out.
 
 `manifest/properties.yaml` is the registry that sits alongside: it maps a property name to its
 schema id, its default units, and flags for whether it is a computed *result* or a runtime
-*monitor*. The Entity Map shows those flags as badges on property nodes.
+*monitor*. The ontology map shows those flags as badges on property nodes.
 
 ## How it fits together
 

docs/05-behavioural-mixins.md

@@ -96,5 +96,5 @@ imposes; both apply. This matters for two reasons:
 - The published, resolved schemas have their `allOf` branches **merged** by the build (see
   [The pipeline](the-pipeline.html)). That is a convenience for consumers, but it means the
   published copy no longer shows you which mixin a field came from. The source is authoritative
-  for provenance — which is exactly why the [Entity Map](../map/index.html) is built from the
+  for provenance — which is exactly why the [ontology map](../map/index.html) is built from the
   sources rather than the published output.

docs/06-conventions.md

@@ -49,7 +49,7 @@ Beyond standard `$ref`, ESSE supports an `include()` mechanism (implemented in
 cases where `$ref` cannot express the composition, and it is resolved before validation — no
 consumer of the published schemas ever sees an `include()`.
 
-Prefer `$ref`. It is standard, it is visible on the Entity Map, and it survives into the resolved
+Prefer `$ref`. It is standard, it is visible on the ontology map, and it survives into the resolved
 output as structure rather than as a copy.
 
 ## Generative keys
@@ -80,8 +80,8 @@ are stable, and change only additively:
 | URL | Meaning |
 | --- | --- |
 | `/#<published path>` | schema explorer deep link |
-| `/map/#/entity/<$id>` | Entity Map: fly to a schema and open its panel |
-| `/map/#/view/<x>,<y>,<zoom>` | Entity Map viewport |
+| `/map/#/entity/<$id>` | Ontology map: fly to a schema and open its panel |
+| `/map/#/view/<x>,<y>,<zoom>` | Ontology map viewport |
 | `/graph.json` | the entity graph asset, described by `src/js/scripts/entity_graph.schema.json` |
 | `/docs/<slug>.html` | these pages |
 

docs/07-the-pipeline.md

@@ -33,7 +33,7 @@ schema/ + example/            JSON sources — the authority
 
 The site is assembled in a `site/` staging directory by the `deploy-docs` job — resolved schemas
 and examples, `schemas.json`, `graph.json`, these documentation pages, the schema explorer and the
-Entity Map — and published to GitHub Pages, which `schemas.mat3ra.com` fronts.
+Ontology map — and published to GitHub Pages, which `schemas.mat3ra.com` fronts.
 
 ## Resolution, and what it destroys
 
@@ -47,7 +47,7 @@ This is a genuine convenience — the published `material.json` shows you every
 in one document. But it is lossy in a specific way: **after merging, you can no longer see which
 mixin a field came from, or that there was a mixin at all.**
 
-That is why the Entity Map and the schema lint read `schema/`, never `dist/js/schema/`. The
+That is why the ontology map and the schema lint read `schema/`, never `dist/js/schema/`. The
 relationships they exist to describe are precisely what resolution removes. If you write a tool
 that cares about structure rather than content, read the sources.
 

docs/08-consuming-esse.md

@@ -146,7 +146,7 @@ import type { MaterialSchema } from "@mat3ra/esse/dist/js/types";
 | construct entities in application code | the generated pydantic model or TS type |
 | build a form or UI from a schema | `getSchemaById`, plus `getPatchedSchemaById` to specialize |
 | find schemas by pattern | `matchSchema` |
-| understand how schemas relate | `graph.json`, or the [Entity Map](../map/index.html) |
+| understand how schemas relate | `graph.json`, or the [ontology map](../map/index.html) |
 
 ## Downstream packages
 

docs/10-glossary.md

@@ -7,10 +7,22 @@ summary: The vocabulary of the repository, with pointers to where each idea is e
 # Glossary
 
 Terms as this repository uses them. Where a term names a schema, the name links to its place on
-the [Entity Map](../map/index.html).
+the [ontology map](../map/index.html).
 
 ## The corpus
 
+**Ontology** — a formal, explicit specification of a shared conceptualization: what kinds of thing
+exist in a domain, and how they relate. ESSE is one, expressed as JSON Schema rather than OWL/RDF.
+The three relationship kinds are the familiar ontological ones — `extends` is subsumption (*is a*),
+`contains` is composition (*has a*), `variant` is disjunction (*is one of*) — and controlled
+vocabularies such as [`definitions/units`](../map/#/entity/definitions%2Funits) constrain the
+leaves. There is no description-logic reasoner; the trade is that the ontology validates records
+directly. [Why ESSE exists](why-esse-exists.html).
+
+**Data standard** — the same corpus seen from the consumer's side: a fixed, versioned, publicly
+addressable set of definitions that independent tools can agree on, so records written by one are
+readable by another without translation glue.
+
 **Schema** — a JSON Schema (draft-07) file under `schema/`, declaring a `$id` derived from its
 path. The authoritative definition of one entity or fragment.
 
@@ -130,7 +142,7 @@ externally-consumed formats. Growth is reported by the lint as a warning.
 
 **Schema explorer** — [the file browser](../index.html) over resolved schemas and examples.
 
-**Entity Map** — [the map](../map/index.html) of all schemas and their references, laid out by
+**Ontology map** — [the map](../map/index.html) of all schemas and their references, laid out by
 architectural layer.
 
 **Concept documentation** — these pages.

docs/index.md

@@ -4,15 +4,22 @@ order: 0
 summary: How ESSE is put together and why — the concepts behind the schemas.
 ---
 
-# ESSE documentation
+# Documentation
 
-ESSE is the **E**ssential **S**ource of **S**chemas and **E**xamples: data-format definitions for
-the entities of digital materials science — materials, models, methods, properties, workflows,
-jobs — together with worked examples of each.
+ESSE — the **E**ssential **S**ource of **S**chemas and **E**xamples — 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](../index.html) shows you any single schema. The
-[Entity Map](../map/index.html) shows you how they all relate. These pages explain *why* the
-schemas are shaped the way they are, which is the part neither of the other two can tell you.
+[ontology map](../map/index.html) 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.
 
 <!-- generated:corpus-totals -->
 
@@ -47,4 +54,4 @@ Then, as you need them:
 
 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 Entity Map.
+with the schemas they describe. Schema names link to their place on the ontology map.

src/html/app.js

@@ -258,7 +258,7 @@ function openFile(path) {
     // Status
     document.getElementById("status-path").textContent = path;
 
-    // Entity Map link. A schema's $id is its published path with underscores turned back
+    // Ontology map link. A schema's $id is its published path with underscores turned back
     // into dashes — exact, because no $id contains an underscore. Examples have no node
     // of their own, so the link points at the schema they illustrate.
     const viewOnMap = document.getElementById("view-on-map");

src/html/index.html

@@ -3,21 +3,21 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>ESSEntial Source of Schemas and Examples (ESSE)</title>
+    <title>Schema Explorer — AI4Materials</title>
     <!-- URL-encoded svg favicon with theme-aware styles -->
     <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20version%3D%221.1%22%20xmlns%3Axlink%3D%22http%3A%2F%2Fwww.w3.org%2F1999%2Fxlink%22%20xmlns%3Asvgjs%3D%22http%3A%2F%2Fsvgjs.com%2Fsvgjs%22%20width%3D%22512%22%20height%3D%22512%22%3E%3Cstyle%3E%40media%20%28prefers-color-scheme%3Alight%29%7B.theme-color%7Bfill%3A%23000000%7D%7D%40media%20%28prefers-color-scheme%3Adark%29%7B.theme-color%7Bfill%3A%23FFFFFF%7D%7D%3C%2Fstyle%3E%3Csvg%20width%3D%22512%22%20height%3D%22512%22%20viewBox%3D%220%200%20512%20512%22%20fill%3D%22none%22%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%3E%3Ccircle%20class%3D%22theme-color%22%20cx%3D%22256%22%20cy%3D%22256%22%20r%3D%2280%22%20transform%3D%22rotate%28-180%20256%20256%29%22%3E%3C%2Fcircle%3E%3Cpath%20class%3D%22theme-color%22%20d%3D%22M334%20100.056C334%2050.8718%20373.847%2011%20423%2011C472.153%2011%20512%2050.8718%20512%20100.056C512%20130.306%20480.115%20171.982%20480.115%20171.982C480.115%20171.982%20427.327%20236.133%20427.327%20256.326C427.327%20276.516%20456.851%20312.743%20480.115%20341.285C497.341%20362.431%20512%20383.184%20512%20411.944C512%20461.128%20472.153%20501%20423%20501C373.847%20501%20334%20461.128%20334%20411.944C334%20384.78%20349.322%20361.543%20365.887%20341.285C389.152%20312.74%20418.674%20276.516%20418.674%20256.326C418.674%20236.289%20366.784%20171.982%20366.784%20171.982C366.784%20171.982%20334%20131.672%20334%20100.056Z%22%20fill%3D%22%23000000%22%3E%3C%2Fpath%3E%3Cpath%20class%3D%22theme-color%22%20d%3D%22M0%20100.056C0%2050.8718%2039.8467%2011%2089%2011C138.153%2011%20178%2050.8718%20178%20100.056C178%20130.306%20146.115%20171.982%20146.115%20171.982C146.115%20171.982%2093.3276%20236.133%2093.3276%20256.326C93.3276%20276.516%20122.851%20312.743%20146.115%20341.285C163.341%20362.431%20178%20383.184%20178%20411.944C178%20461.128%20138.153%20501%2089%20501C39.8467%20501%200%20461.128%200%20411.944C0%20384.78%2015.3226%20361.543%2031.8867%20341.285C55.1519%20312.74%2084.6738%20276.516%2084.6738%20256.326C84.6738%20236.289%2032.7845%20171.982%2032.7845%20171.982C32.7845%20171.982%200%20131.672%200%20100.056Z%22%20fill%3D%22%23000000%22%3E%3C%2Fpath%3E%3C%2Fsvg%3E%3C%2Fsvg%3E" />
     <link rel="stylesheet" href="style.css">
 </head>
 <body>
 
 <div id="titlebar">
-    <span class="app-name">ESSE</span>
+    <span class="app-name">AI4Materials<span class="app-name-suffix">: data standards</span></span>
     <nav id="surfaces">
         <a href="docs/index.html">Docs</a>
         <a href="index.html" class="current">Explorer</a>
-        <a href="map/index.html">Map</a>
+        <a href="map/index.html">Ontology</a>
     </nav>
-    <span id="titlebar-tagline">Essential Source of Schemas and Examples</span>
+    <span id="titlebar-tagline">ESSE &middot; materials science ontology</span>
 </div>
 
 <div id="workspace">
@@ -46,7 +46,7 @@ <h2>Essential Source of Schemas and Examples</h2>
                 <p>Select a schema from the explorer on the left, or start typing to search.</p>
                 <p class="welcome-links">
                     New here? Start with the <a href="docs/index.html">concept documentation</a>,
-                    or see how it all connects on the <a href="map/index.html">Entity Map</a>.
+                    or see how it all connects on the <a href="map/index.html">ontology map</a>.
                 </p>
             </div>
             <div id="monaco-editor"></div>