diff --git a/docs/concepts/what.md b/docs/concepts/what.md new file mode 100644 index 000000000..5accf7154 --- /dev/null +++ b/docs/concepts/what.md @@ -0,0 +1,39 @@ + + +# Things & Resources + +Enola's main concepts are _Things_ and _Resources._ + +## Things + +Let's talk about things. + +In Enola, everything is a _Thing!_ Things have _Properties_ which are identified by _Predicates_ and a _Datatype._ + +Things have an _[Identity](which.md)._ which lets us _link_ all Things. (At least most of them do; but there can also be "inner Things", which are "anonymous"). + +[Implementations Details](../dev/implementation.md) has more internal technical details about these things. + +## Resources + +_Resources_ are what Enola calls things which are just 010011s - without properties like Things. Resources are identified by an URL. + +An HTML page on a web server, or a JPEG photo image in a local file on your computer are both examples of a _Resource._ + +Some resources can be viewed as (converted to) Things. diff --git a/docs/concepts/which.md b/docs/concepts/which.md new file mode 100644 index 000000000..0839778ca --- /dev/null +++ b/docs/concepts/which.md @@ -0,0 +1,108 @@ + + +# Identifiers + + + +Humans [name :snowman: things](https://youtube.com/TODO) . +Because they are :brain: so smart, they usually know _what_ things they're talking about with these _names_ (often from _"context")._ + +Computers on the other hand are pretty stupid, and it helps them to have crystal clear unique names of what's what; so Enola uses the following. + +## URL + +An _"Uniform Resource Locator"_ ([[URL]]) is well-known e.g. as the [[Text]] which you can type into your [[web browsers]]'s address bar. Your browser "fetches" (gets) the [[enola:Resource]] which that URL _"points to"_ - and displays its content to you. Examples of this are: + +* the homepage of the Google Web Search Engine +* the web page showing the results of a Google search for "Enola.dev" +* the logo of the W3C + + + +NOTE: URL are actually a lot less great than one may think at first for really uniquely naming things. For example, and (note the trailing `/` slash) are "the same thing" in practice (that homepage) - as is (note the `www` prefix), or in some other cases something like `https://www.google.com/index.html`. + +URLs have _"schemas"_ - that's the string like `https` - anything before the `:` colon, really. The `https` e.g. means "get it via [[enola:net/HTTP]], and `mailto:` e.g. means "this is an [[enola:email/address]] that you can send an [[Email]] to". + + + +Enola supports URLs, of different schemes; here is how to see which: + +```bash +$ ./enola info schemes +http: HyperText Transfer Protocol; see https://enola.dev/net/http (also https:) +file: ... +... +``` + +Enola can "fetch" the content that an URL points to, like this: + +```bash +$ ./enola get http://vorburger.ch/hi +hello, world +``` + +Getting an URL can raise various errors: + +```bash +$ ./enola get http://bad.tld/hi +Error: Could not resolve bad.tld +``` + +BTW, fun fact: The _#fragment_ (e.g. in `https://server/path#fragment`) of a URL is not relevant for fetching an URL (only e.g. for scrolling to header in displaying); notice how it doesn't change anything here: + +```bash +$ ./enola get http://vorburger.ch/hi#there +hello, world +``` + +## IRI + +An _"Internationalized Resource Identifier"_ ([[IRI]) is something fairly different than an [[URL]]. + +This can, but don't necceessarily really have to, +which can be a bit confusing, at first. + +Sometimes can be fetched - but this is not a hard requirement of _Linked Data,_ and so sometimes you cannot. + +## URI + +An [[URI] ... + +## Identity + +TBD + +### ISBN + +TBD + +### Other + +TBD diff --git a/java/dev/enola/datatype/ProviderX.java b/java/dev/enola/datatype/ProviderX.java new file mode 100644 index 000000000..00a382acd --- /dev/null +++ b/java/dev/enola/datatype/ProviderX.java @@ -0,0 +1,39 @@ +/* + * SPDX-License-Identifier: Apache-2.0 + * + * Copyright 2024 The Enola 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. + */ +package dev.enola.datatype; + +import dev.enola.data.Provider; + +import org.jspecify.annotations.Nullable; + +interface ProviderX extends Provider { // NOT ProviderFromIRI + + @Nullable Object get(String name, String datatypeIRI); + + @Nullable X get(String name, Datatype datatype); + + @Nullable X get(String name, Class clazz); + + /** + * Because this has no explicit context, it may make an assumption about what you could have + * meant, e.g. for something URI like an implementation may assume IRI of Thing instead of URL + * of Resource ; it's thus generally better to use the other methods. + */ + @Override + @Nullable Object get(String name); +} diff --git a/java/dev/enola/thing/resource/ResourceToThingsConverter.java b/java/dev/enola/thing/resource/ResourceToThingsConverter.java new file mode 100644 index 000000000..06a268e9b --- /dev/null +++ b/java/dev/enola/thing/resource/ResourceToThingsConverter.java @@ -0,0 +1,29 @@ +/* + * SPDX-License-Identifier: Apache-2.0 + * + * Copyright 2024 The Enola 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. + */ +package dev.enola.thing.resource; + +import dev.enola.common.io.resource.Resource; +import dev.enola.thing.Thing; + +import java.util.stream.Stream; + +interface ResourceToThingsConverter { // TODO Converter> + // TODO Retrofit the thing the CLI does to --load RDF into this + + Stream convert(Resource resource); +} diff --git a/mkdocs.yaml b/mkdocs.yaml index ade64d437..8caae941e 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -52,6 +52,8 @@ nav: - Info: use/info/index.md - Models: models/index.md - Concepts: + - What? Things!: concept/what.md + - Which? Identifiers!: concept/which.md - Core: concepts/core.md - Architecture Diagrams: concepts/core-arch.md - Singularity: concepts/singularity.md diff --git a/models/enola.dev/emoji.ttl b/models/enola.dev/emoji.ttl new file mode 100644 index 000000000..2fa244e7e --- /dev/null +++ b/models/enola.dev/emoji.ttl @@ -0,0 +1,5 @@ +# TODO https://enola.dev/Emoji is a Datatype with has a RegExp that matches " :.*[a-z ]:" + +# TODO https://enola.dev/Emoji/{emoji} is a schema:Identifier subclass, where {emoji} is either ":?crystal ball:?" or ๐Ÿ”ฎ + +# TODO https://enola.dev/emoji is the (existing) property, which has range (?) #/Emoji. diff --git a/models/enola.dev/varia.ttl b/models/enola.dev/varia.ttl new file mode 100644 index 000000000..ab9fd1fba --- /dev/null +++ b/models/enola.dev/varia.ttl @@ -0,0 +1,56 @@ +@prefix schema: . +@prefix enola: . + +enola:Resource a rdfs:Class; + enola:identifiedBy schema:URL; + schema:description "Resource is the Thing describing what's available at an URL. This is different from a [[rdf:Resource]])."; + enola:java/type "dev.enola.thing.ResourceThing". + +enola:net/Protocol a rdfs:Class; + enola:wikibase TBD; # Infer enola:wikipedia? + +enola:net/http a enola:net/Protocol; + enola:term "HTTP"; + schema:name "HyperText Transfer Protocol"; + enola:rfc "TBD"; + enola:net/client , , ; + enola:wikibase TBD. + +enola:net/webbrowser a schema:Software; + enola:term "Browser", "Web Browser"; + schema:name "Web Browser"; + enola:net/protocol enola:HTTP. + +enola:firefox a schema:Software; + schema:kindof enola:browser. + +enola:chrome a schema:Software; + schema:kindof enola:browser. + +# TODO Double check that this matches how schema:URL is modeled +enola:IRI a schema:Class; + rdfs:subClassOf schema:Identity; + enola:identityOf schema:Thing. + +# TODO enola:URI, similar to enola:IRI + +# TODO Move the following elsewhere? + +enola:identityOf a rdfs:Property; + enola:inverseOf enola:identifiedBy. + +enola:ThingTemplate a rdfs:Class; + schema:description "Template of a Thing. When 'instantiated' (from variables), this 'infers' a (new) Thing.". + +enola:Matcher a rdfs:Class; + +enola:Term a rdfs:Datatype + rdf:subClassOf schema:identity; + enola:matcher [ + enola:regExp "\[\[( .+\)]\]"; + ], [ + enola:regExp "\[\[([a-zA-Z0-9]+:([a-zA-Z0-9]+)\]\]"; + ]. + +enola:term a rdf:Property; + rdf:range enola:Term. diff --git a/models/example.org/greetingN.ttl b/models/example.org/greetingN.ttl index 8e4db00e8..7dcae03df 100644 --- a/models/example.org/greetingN.ttl +++ b/models/example.org/greetingN.ttl @@ -4,5 +4,5 @@ :greeting a rdfs:Class; enola:iriTemplate "https://example.org/greet/{NUMBER}"; - :yo "http://example.org/hi/{NUMBER}"^^enola:IRITemplate; - enola:example . + enola:example ; + :yo "http://example.org/hi/{NUMBER}"^^enola:IRITemplate. diff --git a/models/schema.org/emojis.ttl b/models/schema.org/emojis.ttl index 0546cff89..7c19fa26b 100644 --- a/models/schema.org/emojis.ttl +++ b/models/schema.org/emojis.ttl @@ -1,6 +1,11 @@ @prefix schema: . @prefix enola: . +# TODO Rename this now from emojis.ttl to schema.org.ttl + +# TODO schema: enola:import "https://raw.githubusercontent.com/schemaorg/schemaorg/main/data/schema.ttl " +# Note Bene: We're using "quotes" not because it's an URL import needs to fetch, not an IRI link to a Thing! + schema:name enola:emoji "๐Ÿท๏ธ". schema:description enola:emoji "๐Ÿ“œ". schema:image enola:emoji "๐Ÿ–ผ๏ธ". @@ -8,3 +13,9 @@ schema:url enola:emoji "๐Ÿ”—". schema:identifier enola:emoji "๐Ÿ†”". schema:email enola:emoji "๐Ÿ“จ". schema:sameAs enola:emoji "๐Ÿชž". + +schema:Text enola:term "Text". + +schema:URL + enola:term "URL"; + enola:identityOf enola:Resource. diff --git a/models/youtube.ttl b/models/youtube.ttl new file mode 100644 index 000000000..f929e945b --- /dev/null +++ b/models/youtube.ttl @@ -0,0 +1,46 @@ +@prefix rdfs: . +@prefix schema: . +@prefix enola: . + + a + "https://youtube.com/". + +enola:youtube/VideoID a rdf:Datatype; + rdfs:subClassOf schema:Identity; # TODO TBC + enola:regExp "f9[A-Z0-9]+)". + +enola:youtube/videoID a rdfs:Property; + rdfs:range enola:youtube/VideoID; + +enola:youtube/Video a schema:CreativeWork; # Which (ultimately, indirectly) still IS-A rdfs:Class; is it, right?? + enola:identifiedBy enola:youtube/VideoID; + enola:matcher [ # a enola:Matcher; + enola:iriTemplate "htps://youtube.com/watch?v={YTVID}"; + enola:example ; # TODO Pick one of my old videos... + ], [ + enola:iriRegExp "youtube:(f9[A-Z0-9]+)"; + enola:example "youtube:f9m7...gY"; + ]; + enola:thingTemplate [ # a enola:ThingTemplate; + schema:id(entifier?) "enola:youtube/video/{YTVID}"; + enola:youtube/videoID "{YTVID}"^^; + + # TODO Settle if "enola:youtube/video/{YTVID}" is a valid IRI?! + # Is the Exception an Enola limitation? An RDF4j Namespace one? An IRI one? An RDF one? + # ? + ]. + +enola:youtube/Search a rdfs:Class; + enola:matcher [ + enola:iriRegExp "youtube:([A-Za-z 0-9]+)"; + enola:example "youtube:Linked Data"; + ]; + enola:thingTemplate [ # a enola:ThingTemplate; + schema:id(entifier?) "enola:youtube/search/{SEARCH}"; + schema:url "htps://youtube.com/search?q={SEARCH}"; # TODO TBC + ]. diff --git a/test/greeting.md b/test/greeting.md index 0491a65e7..4567fd7b4 100644 --- a/test/greeting.md +++ b/test/greeting.md @@ -4,5 +4,5 @@ * [`rdf:type`](https://docs.enola.dev/models/www.w3.org/1999/02/22-rdf-syntax-ns/type/): [`rdfs:Class`](https://docs.enola.dev/models/www.w3.org/2000/01/rdf-schema/Class/) * [`enola:iriTemplate`](https://docs.enola.dev/models/enola.dev/iriTemplate/): https://example.org/greet/{NUMBER} -* [`ex:yo`](https://example.org/yo): http://example.org/hi/{NUMBER} _[`enola:IRITemplate`](https://docs.enola.dev/models/enola.dev/IRITemplate/)_ * [`enola:example`](https://docs.enola.dev/models/enola.dev/example/): [`ex:greet/42`](greet/_NUMBER.md?NUMBER=42) +* [`ex:yo`](https://example.org/yo): http://example.org/hi/{NUMBER} _[`enola:IRITemplate`](https://docs.enola.dev/models/enola.dev/IRITemplate/)_