Very first initial use of LinkML!

.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

.pre-commit-config.yaml

@@ -65,7 +65,7 @@ repos:
           - --fuzzy-match-generates-todo
           - --use-current-year
       - id: insert-license
-        files: \.(bash|bazel|textproto|yaml)$
+        files: \.(bash|bazel|textproto|ttl|yaml)$
         exclude: ^docs/use|test/
         args:
           - --comment-style

.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/core.md

@@ -46,7 +46,7 @@ or something like [Amazon Ion](https://amazon-ion.github.io/ion-docs/) or [other
 
 ## Schemas
 
-Enola currently uses [RDFS](../models/example.org/class.md) and (TBD) [Proto 3](https://protobuf.dev/programming-guides/proto3/) as its
-Schema language. It is conceptually open to supporting other kinds of schemas in the future; perhaps e.g.
+Enola (currently) uses [LinkML](https://linkml.io) with [RDFS](../models/example.org/class.md) and (TBD) [Proto 3](https://protobuf.dev/programming-guides/proto3/) as its
+Schema languages. It is conceptually open to supporting other kinds of schemas in the future; perhaps e.g.
 [JSON Schema](https://github.com/enola-dev/enola/issues/313), or [Cap’n Proto](https://capnproto.org/language.html), or [TypeScript](https://www.typescriptlang.org/docs/handbook/2/objects.html) (à la [Typson](https://github.com/lbovet/typson)), or [XML Schema](https://en.wikipedia.org/wiki/XML_Schema_(W3C)) (XSD), or [YANG](https://en.wikipedia.org/wiki/YANG) or [FHIR](https://www.hl7.org/fhir/) or [Varlink](https://varlink.org/Interface-Definition) or [Web IDL](https://webidl.spec.whatwg.org) or
 [ASN.1](https://en.m.wikipedia.org/wiki/ASN.1) or [GNU poke](https://www.gnu.org/software/poke/).

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>

docs/use/get/index.md

@@ -35,7 +35,7 @@ $ ./enola get --load "file:models/**.ttl" enola:/
 
 ## Get 🐢
 
-Get something from a loaded 🐢 Turtle resource, e.g. from the [enola.dev/properties.ttl](../../models/enola.dev/properties.ttl) model:
+Get something from a loaded 🐢 Turtle resource, e.g. from the [enola.dev/enola.ttl](../../models/enola.dev/enola.ttl) model:
 
 ```bash cd ../.././..
 $ ./enola get --load file:models/enola.dev/properties.ttl https://enola.dev/emoji | head --lines=3

java/dev/enola/cli/EnolaCLITest.java

@@ -38,6 +38,8 @@
 
 public class EnolaCLITest {
 
+    private static final String MODEL = "classpath:enola.dev/enola.ttl";
+
     private static CLI cli;
 
     private static CLI cli(String... args) {
@@ -94,14 +96,7 @@ public void docGenEntity() throws IOException {
     public void docGenEmojiThing() throws IOException {
         Path dir = Files.createTempDirectory("EnolaTest");
 
-        var exec =
-                cli(
-                        "-vvv",
-                        "docgen",
-                        "--load",
-                        "classpath:enola.dev/properties.ttl",
-                        "--output",
-                        dir.toUri().toString());
+        var exec = cli("-vvv", "docgen", "--load", MODEL, "--output", dir.toUri().toString());
 
         assertThat(exec).err().isEmpty();
         assertThat(exec).hasExitCode(0).out().isEmpty();
@@ -217,48 +212,30 @@ public void getBinaryEntity() throws IOException {
 
     @Test
     public void getLoadedThing() {
-        var exec =
-                cli(
-                        "-vvv",
-                        "get",
-                        "--load",
-                        "classpath:enola.dev/properties.ttl",
-                        "https://enola.dev/emoji");
+        var exec = cli("-vvv", "get", "--load", MODEL, "https://enola.dev/emoji");
         assertThat(exec).err().isEmpty();
         assertThat(exec).hasExitCode(0);
     }
 
     @Test
     public void getNonExistentThing() {
-        var exec =
-                cli(
-                        "-vvv",
-                        "get",
-                        "--load",
-                        "classpath:enola.dev/properties.ttl",
-                        "https://docs.enola.dev/non-existent");
+        var exec = cli("-vvv", "get", "--load", MODEL, "https://docs.enola.dev/non-existent");
         assertThat(exec).err().isEqualTo("https://docs.enola.dev/non-existent has nothing!\n");
         assertThat(exec).out().isEmpty();
         assertThat(exec).hasExitCode(0);
     }
 
     @Test
     public void getNonExistentTemplateIRIThing() {
-        var exec =
-                cli(
-                        "-vvv",
-                        "get",
-                        "--load",
-                        "classpath:enola.dev/properties.ttl",
-                        "https://docs.enola.dev/non-existent/{ID}");
+        var exec = cli("-vvv", "get", "--load", MODEL, "https://docs.enola.dev/non-existent/{ID}");
         assertThat(exec).err().isEqualTo("https://docs.enola.dev/non-existent/{ID} has nothing!\n");
         assertThat(exec).out().isEmpty();
         assertThat(exec).hasExitCode(0);
     }
 
     @Test
     public void getList() {
-        var exec = cli("-vvv", "get", "--load", "classpath:enola.dev/properties.ttl", "enola:/");
+        var exec = cli("-vvv", "get", "--load", MODEL, "enola:/");
         assertThat(exec).err().isEmpty();
         assertThat(exec).hasExitCode(0).out().contains("https://enola.dev/emoji");
     }

java/dev/enola/common/convert/ObjectConverter.java

@@ -23,7 +23,7 @@
 
 public class ObjectConverter<X, Y> implements ObjectClassConverter {
 
-    // See also similar ObjectToStringWithToStringBiConverter
+    // See also ObjectToStringWithToStringBiConverter, which is similar, but the "opposite"
 
     private final Class<Y> to;
     private final Class<X> from;

java/dev/enola/common/convert/ObjectToStringWithToStringBiConverter.java

@@ -28,11 +28,11 @@
 /**
  * An ObjectToStringBiConverter which uses {@link Object#toString()} for {@link
  * ObjectToStringBiConverter#convertTo(Object)}, and which also checks the type to convert from.
- *
- * <p>See also {@link ObjectConverter}, which is kind of similar to this. (TODO Unify them?)
  */
 public class ObjectToStringWithToStringBiConverter<T> implements ObjectToStringBiConverter<T> {
 
+    // See also ObjectConverter, which is similar to this, but the "opposite" (can't unify them)
+
     private final Class<T> from;
 
     @SuppressWarnings("Immutable")

java/dev/enola/thing/message/ProtoThingIntoJavaThingBuilderConverter.java

@@ -57,6 +57,9 @@ public boolean convertInto(ThingOrBuilder from, Builder into)
         for (var entry : from.getFieldsMap().entrySet()) {
             var iri = entry.getKey();
             var value = entry.getValue();
+            if (Value.KindCase.KIND_NOT_SET.equals(value.getKindCase()))
+                throw new IllegalArgumentException(iri);
+
             if (dev.enola.thing.proto.Value.KindCase.LITERAL.equals(value.getKindCase())) {
                 var datatypeValue = value.getLiteral().getValue();
                 var datatypeIRI = value.getLiteral().getDatatype();
@@ -76,6 +79,10 @@ private Object object(Value protoThingValue) {
         switch (protoThingValue.getKindCase()) {
             case STRING:
                 return protoThingValue.getString();
+            case LITERAL:
+                // TODO Rework things to this can use Thing.set(value, datatype) instead Literal
+                var literal = protoThingValue.getLiteral();
+                return new Literal(literal.getValue(), literal.getDatatype());
             case LINK:
                 return new Link(protoThingValue.getLink());
             case LANG_STRING:
@@ -100,12 +107,14 @@ private Object object(Value protoThingValue) {
                     for (var entry : protoStruct.getFieldsMap().entrySet()) {
                         var iri = entry.getKey();
                         var value = entry.getValue();
+                        if (Value.KindCase.KIND_NOT_SET.equals(value.getKindCase()))
+                            throw new IllegalArgumentException(iri);
                         mapBuilder.put(iri, object(value));
                     }
                     return mapBuilder.build();
                 }
             default:
-                throw new IllegalArgumentException(protoThingValue.getKindCase().name());
+                throw new IllegalArgumentException(protoThingValue.toString());
         }
     }
 }

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,27 @@
 
 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 -X owl -X shacl -d .built/linkml/
+# TODO Re-enable OWL after fixing https://github.com/enola-dev/enola/issues/759
+# 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.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.ttl → models/enola.dev.ttl

@@ -1,3 +1,19 @@
+# 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.
+
 # This is Things metadata *ABOUT* https://enola.dev,
 # as in, The Org, The Software, and such.
 # This is *different* from Enola models!

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/properties.ttl → models/enola.dev/enola.ttl

@@ -1,3 +1,19 @@
+# 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.
+
 @prefix enola:  <https://enola.dev/>.
 @prefix enolay: <https://enola.dev/yaml/>.
 @prefix enolaj: <https://enola.dev/java/>.