feat (modl): Very first initial use of LinkML! (see enola-dev#757)

Author: vorburger

.gitignore

@@ -38,9 +38,6 @@ node_modules/
 # Be
 .be/
 
-# JSON Schemas are generated by tools/protoc during build
-*.schema.json
-
 # Maven
 java/.mvn/wrapper/maven-wrapper.jar
 java/target
@@ -53,3 +50,6 @@ java/dev/enola/protobuf/
 java/dev/enola/thing/proto/
 
 tools/version/VERSION
+
+# LinkML
+.built

.vscode/settings.json

@@ -105,6 +105,10 @@
   "yaml.schemas": {
     // https://squidfunk.github.io/mkdocs-material/creating-your-site/#configuration
     "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yaml",
+
+    // TODO https://github.com/linkml/linkml/issues/2179
+    "https://raw.githubusercontent.com/linkml/linkml-model/main/linkml_model/jsonschema/meta.schema.json": "*.linkml.yaml",
+
     // Keep this in sync with check-jsonschema in .pre-commit-config.yaml
     "docs/models/enola/schemas/Thing.schema.json": "*.thing.yaml"
   },

docs/concepts/other.md

@@ -91,12 +91,16 @@ Enola 🕵🏾‍♀️  may in the future have some [Personal Knowledge Managem
 
 ### Visualization
 
-Enola 🕵🏾‍♀️ visualizes the relationships of its _Entities_ using:
+Enola 🕵🏾‍♀️ visualizes (TBD) the relationships of its _Entities_ using:
 
 * [yEd](https://www.yworks.com) (yFiles) #commercial #sdk #freemium
 * [Graphviz](https://graphviz.org) #available
 * [Gephi](https://gephi.org), with [Gephi Lite](https://gephi.org/gephi-lite/) which uses [SigmaJS](https://www.sigmajs.org) on [Graphology](https://graphology.github.io) for JS #[FOSDEM](https://github.com/vorburger/vorburger.ch-Notes/blob/develop/conferences/FOSDEM-2024.md) #planned #ToDo
 * [D3js.org](https://d3js.org) also has [Graphs](https://observablehq.com/@d3/force-directed-graph-component?collection=@d3/charts) (and [d3rdf](https://github.com/Rathachai/d3rdf))
+* [vis.js](https://visjs.org)
+* [Mermaid](https://mermaid.js.org)
+* [PlantUML](https://plantuml.com)
+* [yuml](https://yuml.me)
 
 Other _"Graph Explorer"_ kind of UIs that we have heard about include:
 

docs/index.md

@@ -49,5 +49,5 @@ of environments by modeling concepts from private environments and writing bespo
 Holmes_ 🕵🏾‍♀️ detective movie with his daughter, and this is an SRE detective's tool!</sub>
 
 <script type="application/ld+json">
-{% include "models/enola.jsonld" %}
+{% include "models/enola.dev.jsonld" %}
 </script>

models/.linkmllint.yaml

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2024 The Enola <https://enola.dev> Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# https://linkml.io/linkml/schemas/linter.html
+extends: recommended
+
+rules:
+  # TODO https://github.com/linkml/prefixmaps/issues/73
+  canonical_prefixes:
+    level: disabled
+
+  no_empty_title:
+    # name becomes title, if no title; that's fine
+    level: disabled

models/build.bash

@@ -17,18 +17,26 @@
 
 set -euox pipefail
 
-# TODO Replace this Bash script with a Bazel BUILD
+rm -rf docs/models/ .built/linkml/
 
-# NOTE: DO *NOT* do "rm -rf docs/models/" here, because that would wipe out
-# the docs/models/enola/schemas/*.schema.json generated by tools/protoc/protoc.bash
+tools/protoc/protoc.bash
 
 find models/ -type d -exec mkdir -p docs/{} \;
 find models/ -type f -exec ln -f {} docs/{} \;
 rm docs/models/{BUILD,build.bash}
 
+# https://linkml.io
+mkdir -p .built/linkml/
+find docs/models/ -name "*.linkml.yaml" -print0 | xargs -n 1 -0 linkml-lint --validate --config models/.linkmllint.yaml
+find docs/models/ -name "*.linkml.yaml" -print0 | xargs -n 1 -0 gen-project -X prefixmap -d .built/linkml/
+# TODO Drop all *.linkml.* e.g. to rename file.linkml.context.jsonld to just file.linkml.context.jsonld
+# TODO --no-mergeimports? https://linkml.io/linkml/schemas/imports.html#making-merged-files-for-distribution ?
+# TODO https://linkml.io/linkml/generators/linkml.html ?
+mv .built/linkml docs/models/
+
 ./enola -vvv docgen --load=file:"docs/models/**.{ttl,owl,rdf}" --output=file://"$PWD"/docs/models/
 
 # TODO Support GLOBs in rosetta like in docgen? (Low priority, because DocGen will gen. embedded JSON-LD anyway.)
-./enola -v rosetta --in=file:models/enola.dev.ttl --out=file:docs/models/enola.jsonld
+./enola -v rosetta --in=file:models/enola.dev.ttl --out=file:docs/models/enola.dev.jsonld
 
 # TODO RDF* --load=file:"models/**.ttl[s?]"

models/enola.dev/enola.linkml.yaml

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2024 The Enola <https://enola.dev> Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+id: https://enola.dev/ontology
+name: Enola
+created_by: https://www.vorburger.ch
+license: ASL
+prefixes:
+  enola: https://enola.dev/
+  linkml: https://w3id.org/linkml/
+  # TODO schema: https://schema.org/
+imports:
+  - linkml:types
+default_range: string
+default_prefix: enola
+
+# TODO Shouldn't (can't) [all] slot_uri be automatically inferred?!
+
+types:
+  GKG:
+    description:
+      ID in Google's Public Knowledge Graph (formerly AKA Freebase), see e.g.
+      https://developers.google.com/knowledge-graph/; starts without slash, but with 'm' or 'g' following by a slash and
+      lower case characters, numbers and underscores.
+    uri: https://enola.dev/GKG
+    base: string
+    examples:
+      - value: g/11bwcf511s
+        description: Alphabet Inc.
+        object: https://g.co/kg/g/11bwcf511s
+
+slots:
+  url:
+    description:
+      URL of this Thing (to be typed into a web browser, for a human to look at HTML). Not to be confused with each
+      Thing's IRI Identity!
+    # TODO range: GKG # TODO Replace *WRONG* local DataType GKG from initial testing with schema:url, once that works...
+
+  wikipedia:
+    description: Wikipedia EN page ID (not URL), e.g. 'Wikipedia' (for https://en.wikipedia.org/wiki/Wikipedia)
+    slot_uri: https://enola.dev/wikipedia
+    pattern: "^[a-zA-Z0-9_]+$"
+    # TODO How-to? schema:image <https://upload.wikimedia.org/wikipedia/commons/8/80/Wikipedia-logo-v2.svg>
+    # TODO How-to? schema:url "https://en.wikipedia.org/wiki/{VALUE}"^^enola:IRITemplate
+    #              for https://docs.enola.dev/models/example.org/templates/
+
+classes:
+  Software:
+    description:
+      Parent (abstract) Class for 'soft ware', i.e. 'virtual computer stuff' - you can think of but cannot physically
+      touch this.
+    # TODO enola:wikipedia "Software". # https://en.wikipedia.org/wiki/Software
+
+  SoftwareWithURL:
+    subclass_of: Software
+    description:
+      Parent (abstract) Class for a piece of [[Software]] which has a URL that you can type into a web browser to look
+      at (the UI of) it.
+    slots:
+      - url

models/enola.dev/files.linkml.yaml

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2024 The Enola <https://enola.dev> Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+id: https://enola.dev/Files
+name: Files
+created_by: https://www.vorburger.ch
+license: ASL
+prefixes:
+  enola: https://enola.dev/
+  linkml: https://w3id.org/linkml/
+  xsd: http://www.w3.org/2001/XMLSchema#
+imports:
+  - enola.linkml
+  - linkml:types
+
+slots:
+  # TODO Are names adjusted in generation? https://linkml.io/linkml/schemas/linter.html#standard-naming
+  parent_folder:
+    description: Parent Folder which this File or Folder is in.
+    # TODO subproperty_of: parent
+    range: Folder
+
+classes:
+  File:
+    description: File holds [[Data]], identified by a [[Path]] on a [[Filesystem]], with a [[MediaType]].
+    subclass_of: SoftwareWithURL
+    slots:
+      - parent_folder
+    attributes:
+      size:
+        description: Number of bytes of data.
+        range: integer # TODO xsd:unsignedLong
+    examples:
+      - value: https://enola.dev/file/localhost/tmp/example.txt
+    # TODO enola:iriTemplate "https://enola.dev/file/{FILESYSTEM}/{PATH}";
+    # TODO enola:filesystem "fs:{FILESYSTEM}"^^enola:IRITemplate;
+    # TODO enola:wikipedia "Computer_file"; # https://en.wikipedia.org/wiki/Computer_file
+    # TODO enola:emoji "🗎".
+
+  Folder:
+    description: Folder is a [[Container]] of other Folders and [[File]]s.
+    subclass_of: SoftwareWithURL
+    slots:
+      - parent_folder
+    # TODO enola:wikipedia "Directory_(computing)"; # https://en.wikipedia.org/wiki/Directory_(computing)
+    # TODO enola:emoji "📁".

models/enola.dev/files.ttl

@@ -25,6 +25,7 @@ enola:fileOntology a owl:Ontology;
   rdfs:label "An Ontology by Enola.dev about Files on Computers.".
 
 enola:File a rdfs:Class;
+  rdfs:comment "File holds [[Data]], identified by a [[Path]] on a [[Filesystem]], with a [[MediaType]].";
   rdfs:isDefinedBy enola:fileOntology;
   rdfs:subClassOf enola:SoftwareWithURL;
   enola:example <https://enola.dev/file/localhost/tmp/example.txt>;
@@ -36,6 +37,7 @@ enola:File a rdfs:Class;
   enola:emoji "🗎".
 
 enola:Folder a rdfs:Class;
+  rdfs:comment "Folder is a [[Container]] of other Folders and [[File]]s";
   rdfs:subClassOf enola:SoftwareWithURL;
   enola:wikipedia "Directory_(computing)"; # https://en.wikipedia.org/wiki/Directory_(computing)
   enola:emoji "📁".
@@ -61,8 +63,9 @@ enola:path a rdf:Property;
   rdfs:domain enola:File.
 
 enola:size a rdf:Property;
- rdfs:range xsd:unsignedLong; # TODO Use a Datatype which permits KiB/MB etc. (from UoM?)
- rdfs:domain enola:File.
+  rdfs:comment "Number of bytes of data.";
+  rdfs:range xsd:unsignedLong; # TODO Use a Datatype which permits KiB/MB etc. (from UoM?)
+  rdfs:domain enola:File.
 
 enola:MediaType a rdfs:Datatype;
   rdfs:comment "Internet Media Type, also known as a MIME Type or Content Type.";

tools/test-ci/test.bash

@@ -22,14 +22,13 @@ set -euox pipefail
 # shellcheck source=/dev/null
 source tools/asdf/install.bash
 
-rm -rf docs/models/
-
-# TODO Run all this only when model inputs change
-tools/protoc/protoc.bash
+# Installs all Python packages already (some of which models/build needs)
+source tools/pre-commit/install.bash
 
 # This writes into docs/models/ (which is on .gitignore), not site/ (which mkdocs cleans when it starts; à la rm -rf site/)
 models/build.bash
 
+# Run ./test.bash after models/build.bash, because this also runs pre-commit, which validates stuff using the generated JSON Schemas
 ./test.bash
 
 # No files (which are not on .gitigore) should have been modified!