External terms properly (#30)

* Restructure type definitions and their conversions

* Coding done, except for context generation

* testing artifacts

* Something is produced now...

* first round of test conclusive

* Testing on local vocabularies...

* Properly using curie everywhere

* Minor code improvements

* The transition works on all vocabularies.

* Added the "also known" feature

* Updated the changes.md file

* gitignore pluses

Author: iherman

.gitignore

@@ -1,5 +1,7 @@
 node_modules/
-local/
+local/*
+local/*/*
+local/local_run.sh
 example/*.ttl
 example/*.json
 example/*.jsonld

CHANGES.md

@@ -1,3 +1,17 @@
+## Version 1.6.0
+
+- A systematic re-write of the internals, triggered by the introduction of external terms. Previously, all cross-references (e.g., range, superclass, etc.) were done using the identifier of the terms. That led to lots of ugly code differentiating between terms defined in the vocab and curies appearing as, say, ranges. This situation was made worse by external terms.
+
+    This version uses RDFTerm interfaces (and its extensions for classed, properties, etc) overall. As it should from a modeling purposes: the array of ranges refer to an array of RDF Classes, superproperties to Properties, etc. This made the code cleaner and many of the ugly code disappeared.
+
+- A minor change for the JSON-LD Context generation. It does happen that the name used in the context file should be different than what the official label is. Eg., `keyAgreement` vs. `keyAgreementMethod`. This is ugly but sometimes necessary for backward compatibility reasons. A new key in yml, `knownAs`, may be used to set this alternative name. It is used exclusively in the context generation.
+
+## Version 1.5.0 - 1.5.6
+
+- Adding the "external" term feature. Terms that are not formally defined in the vocabulary, but added explicitly to make cross references more understandable and appear in the context file. Typical case are `schema.org` terms that are used all over the place.
+- The code has been made fully compatible with [deno](https://deno.land). With the presence of a `deno.json` file for handling imports, the same code can be used with node.js/npm and deno interchangeably.
+- The JSON-LD `@context` generation aspect has been significantly improved and debugged, to make it really usable by smaller projects.
+
 ## Version 1.4.8
 
 - Adding the possibility of explicitly setting a resource type via the (new) `type` property.
@@ -10,7 +24,6 @@
 
 - Label is now optional
 
-
 ## Version 1.4.5
 
 - Error in the namespace for `Property` (see https://github.com/w3c/yml2vocab/issues/16)

README.md

@@ -23,6 +23,7 @@ Each block sequence consists of blocks with the following keys:`id`, `property`,
   - The `deprecated` key refers to a boolean, signaling whether term is deprecated or not. Default is `false`. This property is a leftover from earlier version and is overwritten, if applicable, by the value of `status`.
   - The `context` key refers to list of URLs or two special keywords. It is used to add information on JSON-LD `@context` file(s) that "mention" the term; the list of URLs refer to the relevant `@context` file. If the value is `vocab`, and a global `@context` file is defined in the `vocab` block, that "default" `@context` is used. Finally, if the value of the property is `none`, there is no context file reference for the term. The default setting is `vocab` (i.e., unless it is otherwise specified, the default value is used for the term).
   - The `example` key refers to on or more blocks with `label` and `json` keys, providing a (JSON) example with a title. These examples are placed, in the HTML version, to the end of the section referring to a term (the examples are ignored in the Turtle and the JSON-LD versions). Care should be taken to use the `"|"` [block style indicator](https://yaml-multiline.info) in the YAML file for the examples.
+  - The `known_as` key refers to a string, that can be used, in rare occasions, as an alias to the term's label. It currently used when generating a JSON-LD context file, as the name of the property in the context file instead of the official label. This means that JSON-LD users, using that context file, must refer to this alternative name in their code (this may come in handy when the official name changes but the old name is kept for JSON users for backward compatibility reasons).
 
 - Top level blocks:
   - `vocab`: a block with the `id` and the `value` keys defining the prefix and the URL of the vocabulary, respectively. The `id` provides a prefix that can be used in the vocabulary descriptions, e.g., for cross-references. The additional, optional `context` key may provide a default context file reference (as a URI), used by all terms unless locally overwritten (see above). Note that the `context` key is required if the HTML template includes a context section.
@@ -43,7 +44,7 @@ Each block sequence consists of blocks with the following keys:`id`, `property`,
 
     Note that both the `domain` and the `range` keys can take an array of class references as values. For the former this means the resulting domain is the _union_ of the referred classes, whereas for the latter it is the _intersection_.
 
-    The `range` key may also use the (single) `IRI` (or `URL`) term instead of class references. This keyword denotes a property that has no explicit range, but whose objects are expected to be IRI references. The generated vocabulary annotates these properties as belonging to the `owl:ObjectProperty` class, which is the term reserved for properties whose objects are not supposed to be literals.
+    The `range` key may also use the (single) `IRI` (or `URL`) term instead of class references. This keyword denotes a property that has no explicit range, but whose objects are expected to be IRI references. The generated vocabulary annotates these properties as belonging to the `owl:ObjectProperty` class, which is the term reserved for properties whose objects are not supposed to be literals. A comment is also generated into the HTML description of the term.
 
     The `dataset` key can also be set to a boolean value. This key only influences the generated JSON-LD `@context`: if the value is `true`, the JSON-LD `@container` is set to the `@graph` value for the property, signalling that the value refers to a _dataset_ (or _graph_). See the [JSON-LD Specification](https://www.w3.org/TR/json-ld/#graph-containers) for further details.
 

deno.json

@@ -1,5 +1,5 @@
 {
-    "version": "1.5.4",
+    "version": "1.6.0",
     "description": "Generation of vocabulary files starting by YAML",
     "homepage": "https://github.com/w3c/yml2vocab",
     "nodeModulesDir": "none",
@@ -15,27 +15,24 @@
         "test_di": "cd test/di; deno run --allow-read --allow-write --allow-env ../../main.ts -c",
         "test_vcdm": "cd test/vcdm; deno run --allow-read --allow-write --allow-env ../../main.ts -c",
         "local_vcdm_nolink": "cd local/tests/vcdm;  deno run --allow-read --allow-write --allow-env ../../../main.ts -c",
+        "local_test": "cd local/tests;  deno run --allow-read --allow-write --allow-env ../../main.ts -v local/tests/test.yml -t local/tests/test_template.html -c",
         "local_ident": "cd local/tests/identification;  deno run --allow-read --allow-write --allow-env ../../../main.ts -c",
+        "local_did": "cd local/tests/did;  deno run --allow-read --allow-write --allow-env ../../../main.ts -c",
         "compile": "deno compile --allow-read --allow-write --allow-env main.ts"
     },
     "main": "index.ts",
     "author": "Ivan Herman <[email protected]> (https://www.w3.org/People/Ivan/)",
     "license": "W3C-20150513",
     "imports": {
-        "./common"           : "./common.ts",
-        "./context"          : "./context.ts",
-        "./convert"          : "./convert.ts",
-        "./html"             : "./html.ts",
-        "./jsonld"           : "./jsonld.ts",
-        "./schema"           : "./schema.ts",
-        "./turtle"           : "./turtle.ts",
         "./lib/common"       : "./lib/common.ts",
         "./lib/context"      : "./lib/context.ts",
         "./lib/convert"      : "./lib/convert.ts",
         "./lib/html"         : "./lib/html.ts",
         "./lib/jsonld"       : "./lib/jsonld.ts",
         "./lib/schema"       : "./lib/schema.ts",
         "./lib/turtle"       : "./lib/turtle.ts",
+        "./lib/factory"      : "./lib/factory.ts",
+        "./lib/minidom"      : "./lib/minidom.ts",
         "./index"            : "./index.ts",
         "yaml"               : "npm:yaml",
         "commander"          : "npm:commander",