diff --git a/README.md b/README.md index 1fba3c9f6..dd61922cd 100644 --- a/README.md +++ b/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. diff --git a/docs/01-why-esse-exists.md b/docs/01-why-esse-exists.md index 29d71f2b5..4bc7babf4 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 @@ -86,4 +112,4 @@ The corpus at a glance, and how densely it is cross-referenced: 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. diff --git a/docs/02-schema-layering.md b/docs/02-schema-layering.md index b587a7a21..d5987709f 100644 --- a/docs/02-schema-layering.md +++ b/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: 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? diff --git a/docs/03-entity-anatomy.md b/docs/03-entity-anatomy.md index c67dcc97c..466c14f9d 100644 --- a/docs/03-entity-anatomy.md +++ b/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 diff --git a/docs/05-behavioural-mixins.md b/docs/05-behavioural-mixins.md index 200897c22..0d6a9da66 100644 --- a/docs/05-behavioural-mixins.md +++ b/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. diff --git a/docs/06-conventions.md b/docs/06-conventions.md index fd525f08e..5e1640979 100644 --- a/docs/06-conventions.md +++ b/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 | | --- | --- | | `/#` | schema explorer deep link | -| `/map/#/entity/<$id>` | Entity Map: fly to a schema and open its panel | -| `/map/#/view/,,` | Entity Map viewport | +| `/map/#/entity/<$id>` | Ontology map: fly to a schema and open its panel | +| `/map/#/view/,,` | Ontology map viewport | | `/graph.json` | the entity graph asset, described by `src/js/scripts/entity_graph.schema.json` | | `/docs/.html` | these pages | diff --git a/docs/07-the-pipeline.md b/docs/07-the-pipeline.md index 8205bcb76..c497703a4 100644 --- a/docs/07-the-pipeline.md +++ b/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. diff --git a/docs/08-consuming-esse.md b/docs/08-consuming-esse.md index f254f2f50..11c0bb6e4 100644 --- a/docs/08-consuming-esse.md +++ b/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 diff --git a/docs/10-glossary.md b/docs/10-glossary.md index 34e603d1d..bde5f7526 100644 --- a/docs/10-glossary.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index 22b328f83..927900905 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. +[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. @@ -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. diff --git a/src/html/app.js b/src/html/app.js index f114b2ec3..bcca562cf 100644 --- a/src/html/app.js +++ b/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"); diff --git a/src/html/index.html b/src/html/index.html index 8b3542d10..e403aabdf 100644 --- a/src/html/index.html +++ b/src/html/index.html @@ -3,7 +3,7 @@ - ESSEntial Source of Schemas and Examples (ESSE) + Schema Explorer — AI4Materials @@ -11,13 +11,13 @@
- ESSE + AI4Materials: data standards - Essential Source of Schemas and Examples + ESSE · materials science ontology
@@ -46,7 +46,7 @@

Essential Source of Schemas and Examples

Select a schema from the explorer on the left, or start typing to search.

New here? Start with the concept documentation, - or see how it all connects on the Entity Map. + or see how it all connects on the ontology map.

diff --git a/src/html/map/index.html b/src/html/map/index.html index 0b47081e5..a0ba71ea1 100644 --- a/src/html/map/index.html +++ b/src/html/map/index.html @@ -3,7 +3,8 @@ - ESSE Entity Map + Ontology — AI4Materials + @@ -11,13 +12,13 @@
- ESSE + AI4Materials: data standards - every schema a place, every reference a road + ESSE · materials science 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