From 377e84cd9b5930acfe278729b27cd33a35700bbd Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 05:31:14 +0000 Subject: [PATCH 1/3] Lead with the ontology, and with "AI for Materials" as the wordmark Two changes that travel together, since both are about what a first-time visitor understands the site to be. The corpus is an ontology and never said so. It fixes what kinds of thing exist in digital materials science and how they relate, and the relations are declared rather than editorial: `extends` is subsumption (is a), `contains` is composition (has a), `variant` is disjunction (is one of), with controlled vocabularies constraining the leaves. The word appeared nowhere in the docs or on the map. It does now: - The map's empty detail panel leads with "The ontology, mapped" and explains that nodes are entity types and edges are declared relationships -- the panel is the first thing a visitor reads, so it does the defining. - `01-why-esse-exists` gains a section stating the claim and, importantly, its limit: this is not OWL/RDF with a reasoner, and the trade is deliberate -- expressed as JSON Schema, the ontology validates records directly instead of describing a world some other artifact must conform to. - A new `ontology-relations` generated fragment tabulates the three relations against their JSON Schema keywords with counts from the graph, so the prose calling them "the familiar ontological relations" cannot drift. - Glossary gains Ontology and Data standard under "The corpus". The wordmark becomes "AI for Materials" across all three surfaces, with "ESSE - data standards & ontology" as the descriptor. Worth recording that this was chosen over keeping ESSE primary: it maximises reach to the AI-for-materials audience, at the cost of immediate recognition for someone arriving from `npm i @mat3ra/esse`, which the descriptor is there to recover. The docs now carry an honest account of the AI connection -- declared types, units and relationships are what training pipelines and agents would otherwise have to infer -- rather than leaving the framing unsupported. The docs titlebar had no tagline slot at all; it gains one, hidden under 640px. Verified in a browser that the longer wordmark neither spills, overlaps its neighbours nor introduces horizontal scroll on any of the three surfaces at 1440/999/760/560px, with the map still rendering 564 nodes and no console errors. 34 tests pass, all internal links resolve. --- docs/01-why-esse-exists.md | 26 ++++++++++++++++++++++++ docs/10-glossary.md | 12 +++++++++++ docs/index.md | 19 ++++++++++++------ src/html/index.html | 6 +++--- src/html/map/index.html | 18 +++++++++++------ src/html/map/style.css | 6 ++++++ src/js/scripts/buildDocsPages.ts | 34 ++++++++++++++++++++++++++++++-- 7 files changed, 104 insertions(+), 17 deletions(-) diff --git a/docs/01-why-esse-exists.md b/docs/01-why-esse-exists.md index 29d71f2b5..03844726a 100644 --- a/docs/01-why-esse-exists.md +++ b/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: + + + +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 diff --git a/docs/10-glossary.md b/docs/10-glossary.md index 34e603d1d..1a5faa75b 100644 --- a/docs/10-glossary.md +++ b/docs/10-glossary.md @@ -11,6 +11,18 @@ the [Entity 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. diff --git a/docs/index.md b/docs/index.md index 22b328f83..acbad1e9d 100644 --- a/docs/index.md +++ b/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. +[Entity 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. diff --git a/src/html/index.html b/src/html/index.html index 8b3542d10..6cefedfe5 100644 --- a/src/html/index.html +++ b/src/html/index.html @@ -3,7 +3,7 @@ - ESSEntial Source of Schemas and Examples (ESSE) + Schema Explorer — AI for Materials @@ -11,13 +11,13 @@
- ESSE + AI for Materials - Essential Source of Schemas and Examples + ESSE · data standards & ontology
diff --git a/src/html/map/index.html b/src/html/map/index.html index 0b47081e5..6e5b99889 100644 --- a/src/html/map/index.html +++ b/src/html/map/index.html @@ -3,7 +3,8 @@ - ESSE Entity Map + Entity Map — AI for Materials + @@ -11,13 +12,13 @@
- ESSE + AI for Materials - every schema a place, every reference a road + ESSE · data standards & ontology
@@ -50,8 +51,8 @@

- Rings read outward as the build-up: primitives at the centre, root entities - around them, catalogues on the rim. + Rings read outward as the ontology builds up: primitives at the centre, root + entities around them, catalogues on the rim.

Families click to filter

@@ -80,8 +81,13 @@

Layer shapes

diff --git a/src/js/scripts/checkSiteLinks.ts b/src/js/scripts/checkSiteLinks.ts index a50162b91..861adf45c 100644 --- a/src/js/scripts/checkSiteLinks.ts +++ b/src/js/scripts/checkSiteLinks.ts @@ -2,7 +2,7 @@ * Verifies that every internal link in the assembled site resolves. * * The site is stitched together from four sources — resolved schemas, the concept docs, the - * explorer and the Entity Map — each of which links into the others. Nothing else checks that + * explorer and the ontology map — each of which links into the others. Nothing else checks that * those links land anywhere, and a stale href is invisible until someone clicks it. * * External URLs are not fetched; this is a build step, not a crawler. From 368d08f19c4241dcb080eccd61571344860742cf Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 21:10:07 +0000 Subject: [PATCH 3/3] Make the wordmark a complete phrase: "AI4Materials: data standards" "AI for Materials" alone read as a dangling fragment -- the name sat at the far left of the titlebar while its descriptor was stranded on the other side of the navigation, so the logo never resolved into a phrase. The name and its completion are now one unit. The suffix is muted and lighter so the name still carries the emphasis, and it drops below 700px where the navigation needs the room. The right-hand slot keeps `ESSE - materials science ontology`, which is where package-name recognition now lives. Closed-up with the numeral rather than "AI for Materials": AI4Science and ML4Sci have made that the idiom in this field, so it reads as a name rather than as textspeak. Verified in a browser on all three surfaces at 1440/900/700/560px: the logo renders in full, the suffix hides exactly at the 700px breakpoint, and nothing spills, overlaps or introduces horizontal scroll. 34 tests pass, all internal links resolve. --- src/html/index.html | 6 +++--- src/html/map/index.html | 6 +++--- src/html/map/style.css | 13 +++++++++++++ src/html/style.css | 13 +++++++++++++ src/js/scripts/buildDocsPages.ts | 9 ++++++--- 5 files changed, 38 insertions(+), 9 deletions(-) diff --git a/src/html/index.html b/src/html/index.html index ed1934dd0..e403aabdf 100644 --- a/src/html/index.html +++ b/src/html/index.html @@ -3,7 +3,7 @@ - Schema Explorer — AI for Materials + Schema Explorer — AI4Materials @@ -11,13 +11,13 @@
- AI for Materials + AI4Materials: data standards - ESSE · data standards & ontology + ESSE · materials science ontology
diff --git a/src/html/map/index.html b/src/html/map/index.html index 79cbf7d04..a0ba71ea1 100644 --- a/src/html/map/index.html +++ b/src/html/map/index.html @@ -3,7 +3,7 @@ - Ontology — AI for Materials + Ontology — AI4Materials @@ -12,13 +12,13 @@
- AI for Materials + AI4Materials: data standards - ESSE · data standards & ontology + ESSE · materials science ontology
diff --git a/src/html/map/style.css b/src/html/map/style.css index 65d317f9b..d0b5b87a8 100644 --- a/src/html/map/style.css +++ b/src/html/map/style.css @@ -56,6 +56,19 @@ body { color: var(--text-primary); font-weight: 500; } +/* The suffix completes the wordmark, so "AI4Materials" never reads as a + dangling fragment. Muted and lighter so the name still carries the emphasis; + dropped on narrow screens where the nav needs the room. */ +#titlebar .app-name-suffix { + color: var(--text-muted); + font-weight: 400; +} +@media (max-width: 700px) { + #titlebar .app-name-suffix { + display: none; + } +} + #titlebar-tagline { margin-left: 6px; } diff --git a/src/html/style.css b/src/html/style.css index 823f31a50..745f5eaed 100644 --- a/src/html/style.css +++ b/src/html/style.css @@ -46,6 +46,19 @@ body { color: var(--text-primary); font-weight: 600; } +/* The suffix completes the wordmark, so "AI4Materials" never reads as a + dangling fragment. Muted and lighter so the name still carries the emphasis; + dropped on narrow screens where the nav needs the room. */ +#titlebar .app-name-suffix { + color: var(--text-muted); + font-weight: 400; +} +@media (max-width: 700px) { + #titlebar .app-name-suffix { + display: none; + } +} + #titlebar-tagline { margin-left: auto; } diff --git a/src/js/scripts/buildDocsPages.ts b/src/js/scripts/buildDocsPages.ts index 8eecf1ab8..54a9fbff7 100644 --- a/src/js/scripts/buildDocsPages.ts +++ b/src/js/scripts/buildDocsPages.ts @@ -288,19 +288,19 @@ function renderPage(page: DocsPage, pages: DocsPage[], html: string): string { - ${escapeHtml(page.title)} — AI for Materials + ${escapeHtml(page.title)} — AI4Materials
- AI for Materials + AI4Materials: data standards - ESSE · data standards & ontology + ESSE · materials science ontology