Merge pull request #28 from w3c/Improve-generated-context

Improve generated context and other improvements

Author: iherman

README.md

@@ -24,9 +24,8 @@ Each block sequence consists of blocks with the following keys:`id`, `property`,
   - 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.
 
-
 - 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).
+  - `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.
 
   - `prefix`: definition of a prefixes, and corresponding URLs, for each external vocabulary in use, defined by the `id` and `value` keys, respectively. 
 
@@ -64,7 +63,6 @@ External terms, while they appear in the HTML document generated by the tool, do
 
 The prefix part of the curie _must_ be defined through the `prefix` top level block.
 
-
 ## Installation and use
 
 The script is in TypeScript (version 5.0.2 and beyond) running on top of [`node.js`](https://nodejs.org) (version 21 and beyond). It can also run with [`deno`](http://deno.land) (version 2.1 and beyond).
@@ -82,15 +80,35 @@ npm install yml2vocab
 
 #### Running on a command line
 
+##### NPM/Node.js
+
 The npm installation installs the `node_modules/.bin/yml2vocab` script. The script can be used as:
 
 ```
 yml2vocab [-v vocab_file_name] [-t template_file_name] [-c]
 ```
 
-Running this script generates the `vocab_file_name.ttl`, `vocab_file_name.jsonld`, and `vocab_file_name.html` files for the Turtle, JSON-LD, and HTML+RDFa versions, respectively. The script relies on the `vocab_file_name.yml` file for the vocabulary specification in YAML and a `template_file_name` file for a template file. The defaults are `vocabulary` and `template.html`, respectively.
+##### Deno
+
+If `deno` is installed globally, one can also run the script directly (without any further installation) by
+
+```
+deno run --allow-read --allow-write --allow-env /a/b/c/main_.ts [-v vocab_file_name] [-t template_file_name] [-c]
+```
+
+in the top level. To make it simpler, a binary, compiled version of the program can be generated by
 
-If the `-c` flag is also set, the additional `vocab_file_name_context.jsonld` is also generated, containing a simple `@context` structure that can be used as a separate `@context` file or embedded in a JSON file. Note that this is a "minimal" JSON-LD file, which does not necessarily use all the sophistication that JSON-LD [defines](https://www.w3.org/TR/json-ld11/#the-context) for `@context`; these may have to be added manually.
+```
+deno compile --allow-read --allow-write --allow-env main.ts
+```
+
+which results in an executable file, called `yml2vocab`, that can be stored anywhere in the user's `$PATH`.
+
+#### Command line argument
+
+The script generates the `vocab_file_name.ttl`, `vocab_file_name.jsonld`, and `vocab_file_name.html` files for the Turtle, JSON-LD, and HTML+RDFa versions, respectively. The script relies on the `vocab_file_name.yml` file for the vocabulary specification in YAML and a `template_file_name` file for a template file. The defaults are `vocabulary` and `template.html`, respectively.
+
+If the `-c` flag is also set, the additional `vocab_file_name.context.jsonld` is also generated, containing a JSON-LD file that can be used as a separate `@context` reference in a JSON-LD file. Note that this JSON-LD file does not necessarily use all the sophistication that JSON-LD [defines](https://www.w3.org/TR/json-ld11/#the-context) for `@context`; these may have to be added manually.
 
 #### Running from a Javascript/TypeScript program
 
@@ -128,26 +146,7 @@ There is no need to install any extra typing, it is included in the package. The
 
 ### Cloning the repository
 
-The [repository](https://github.com/yml2vocab) may also be cloned. For a complete installation:
-
-1. If necessary, install [`node.js`](https://nodejs.org/) on your local machine. Installation of `node.js` should automatically install the [`npm`](https://www.npmjs.com) package manager.
-2. Clone the repository (i.e., https://github.com/w3c/yml2vocab/) to your local machine.
-3. In the directory of the repository clone, run `npm install` on the command line. This installs all the necessary packages in the `node_modules` subdirectory.
-4. Create a directory for the vocabulary definition; this should include
-   1. A `vocabulary.yml` file. You can start with the YAML file in the `example` directory of the repository, and change the cells for your vocabulary.
-   2. A `template.html` file. You can start with the HTML file in the `example` directory of the repository, and adapt/change it as you wish.
-5. Run the `main.ts` file in the directory vocabulary definition. This generates the `vocabulary.ttl`, `vocabulary.jsonld`, and `vocabulary.html` files for, respectively, the Turtle, JSON-LD, and HTML representations.
-
-   "Running" may be done in three different ways:
-
-   1. Run, via `node`, the file `dist/main.js` of the repository
-   2. Run, via `node_modules/.bin/ts-node`, the file `main.ts` of the repository
-   3. Run, via `deno run`, the file `main.ts` or the repository
-      4. Alternatively, an executable file can be generated via `deno task compile` in the repository, which can then be put to the user's `$PATH`.
-
-   Alternative (2) or (3) is preferred
-
-   The script also accepts a single argument to be used instead of `vocabulary` to name the various files (see above).
+The [repository](https://github.com/yml2vocab) may also be cloned. 
 
 #### Content of the directory
 
@@ -169,6 +168,6 @@ The following files and directories are generated/modified by either the script
 
 ## Acknowledgement
 
-The original idea, structure, and script (in Ruby) was created by Gregg Kellogg for v1 of the Credentials Vocabulary and with a vocabulary definition using CSV. The CSV definitions have been changed to YAML, and the script itself has been re-written in TypeScript (and developed further since).
+The original idea, structure, and script (in Ruby) was created by Gregg Kellogg for v1 of the Credentials Vocabulary and with a vocabulary definition using CSV. The CSV definitions have been changed to YAML, and the script itself has been re-written in TypeScript, and developed further since.
 
 Many features are the result of further discussions with Many Sporny and Benjamin Young.

deno.json

@@ -1,5 +1,5 @@
 {
-    "version": "1.5.0",
+    "version": "1.5.4",
     "description": "Generation of vocabulary files starting by YAML",
     "homepage": "https://github.com/w3c/yml2vocab",
     "nodeModulesDir": "none",
@@ -15,6 +15,7 @@
         "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_ident": "cd local/tests/identification;  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",

index.ts

@@ -131,7 +131,7 @@ export async function generateVocabularyFiles(yaml_file_name: string, template_f
             fs.writeFile(`${basename}.html`, conversion.getHTML(template)),
         ];
         if (context) {
-            fs_writes.push(fs.writeFile(`${basename}_context.jsonld`, conversion.getContext()))
+            fs_writes.push(fs.writeFile(`${basename}.context.jsonld`, conversion.getContext()))
         }
         const write_errors = (await Promise.allSettled(fs_writes))
             .filter((result): boolean => result.status === "rejected")

lib/context.ts

@@ -5,11 +5,11 @@
  * @packageDocumentation
  */
 
-import { Vocab, global, RDFProperty } from './common';
+import { Vocab, global, RDFProperty, RDFTerm } from './common';
 
 // Just to get an extra help from TS if I mistype something...
 interface Context {
-    [index: string]: string|Context|boolean;
+    [index: string]: string|Context|boolean|null;
 }
 
 // These are the context statements appearing in all 
@@ -20,6 +20,20 @@ const preamble: Context = {
     "type": "@type",
 };
 
+// Minor utility: return the full URL for a prefix
+function prefix_url(prefix: string | undefined, vocab: Vocab): string {
+    if (!prefix) {
+        // This never happens per the program logic, but we keep TS happy...
+        return global.vocab_url;
+    }
+    for (const pr of vocab.prefixes) {
+        if (pr.prefix === prefix) {
+            return pr.url;
+        }
+    }
+    return global.vocab_url;
+}
+
 /**
  * Generate the minimal JSON-LD context for the vocabulary.
  *
@@ -30,27 +44,43 @@ export function toContext(vocab: Vocab): string {
     // Generation of a unit for properties
     const propertyContext = (property: RDFProperty, forClass = true): Context|string => {
         // the real id of the property...
-        const url = `${global.vocab_url}${property.id}`;
+        const baseUrl = prefix_url(property.prefix, vocab);
+        const url = `${baseUrl}${property.id}`;
         const output: Context = {
             "@id" : url
         }
-        if (forClass || property.type.includes("owl:ObjectProperty")) {
+        if (forClass && property.type.includes("owl:ObjectProperty")) {
             output["@type"] = "@id";
         }
         // Try to catch the datatype settings; these can be used
         // to set these in the context as well
         if (property.range) {
             for (const range of property.range) {
                 if (range.startsWith("xsd:")) {
-                    output["@type"] = range.replace('xsd:', 'http://www.w3.org/2001/XMLSchema#');
+                    output["@type"] = range.replace("xsd:", "http://www.w3.org/2001/XMLSchema#");
+                    break;
+                } else if (range === "rdf:JSON") {
+                    output["@type"] = "@json";
+                    break;
+                } else if (["rdf:HTML", "rdf:XMLLiteral", "rdf:PlainLiteral", "rdf:langString"].includes(range)) {
+                    output["@type"] = range.replace("rdf:", "http://www.w3.org/1999/02/22-rdf-syntax-ns#");
                     break;
                 } else if (range === "rdf:List") {
                     output["@container"] = "@list";
+                    break;
+                } else if (property.type.includes("owl:DatatypeProperty")) {
+                    // This is the case when the property refers to an explicitly defined, non-standard datatype
+                    const [range_prefix, range_reference] = range.split(":");
+                    const range_url = prefix_url(range_prefix, vocab)
+                    output["@type"] = range_url + range_reference;
+                    break;
                 }
+
             } 
         }
         if (property.dataset) {
             output["@container"] = "@graph";
+            output["@type"]      = "@id";
         }
 
         // if only the URL is set, it makes the context simpler to use its direct value,

lib/convert.ts

@@ -256,7 +256,7 @@ function finalizeRawEntry(raw: RawVocabEntry): RawVocabEntry {
         comment     : (raw.comment) ? cleanComment(raw.comment) : "",
         see_also    : toSeeAlso(raw.see_also),
         example     : toExample(raw.example),
-        dataset     : (raw.dataset === undefined) ? false : raw.dataset,
+        dataset     : raw.dataset ?? false,
         context     : toArrayContexts(raw.context)
     }
 }
@@ -377,14 +377,15 @@ export function getData(vocab_source: string): Vocab {
                 return terms.length === 1 ? range : terms[1];
             });
             if (pure_refs.length !== 0 && pure_refs.indexOf(raw.id) !== -1) {
-                (pure_refs.length === 1 ? single_ref : multi_ref).push(property.id);
+                const id_to_store = (global.vocab_prefix !== property.prefix) ? `${property.prefix}:${property.id}` : property.id;
+                (pure_refs.length === 1 ? single_ref : multi_ref).push(id_to_store);
                 return true;
             }
         }
         return false;
     }
 
-    // Handling external terms, that are characterized by the fact that they are identified as a CURIE in
+    // Handling external terms. These are characterized by the fact that they are identified as a CURIE in
     // the YAML file. The prefix and the term must be separated.
     // To make the handling of all this uniform, the core term also get the (default) prefix stored in their
     // structure.
@@ -483,7 +484,10 @@ export function getData(vocab_source: string): Vocab {
     ];
 
     // Get the properties. Note the special treatment for deprecated properties, as well as 
-    // the extra owl types added depending on the range
+    // the extra owl types added depending on the range.
+    //
+    // Note that the function sets the object property or datatype property types in the obvious cases.
+    // These extra types are also added when handling a class or a datatype, looking up the references.
     const properties: RDFProperty[] = (vocab.property !== undefined) ?
         vocab.property.map((raw: RawVocabEntry): RDFProperty => {
             const {prefix, id, external} = check_id(raw);
@@ -555,7 +559,12 @@ export function getData(vocab_source: string): Vocab {
 
             // Get all domain/range cross-references
             for (const property of properties) {
-                crossref(raw, property, property.range, range_of, includes_range_of);
+                const is_obj_property = crossref(raw, property, property.range, range_of, includes_range_of);
+                // the relevant property should be marked as an object property!
+                if (is_obj_property) {
+                    // a bit convoluted, but trying to avoid repeating the extra entry
+                    property.type = [...((new Set(property.type)).add('owl:ObjectProperty'))];
+                }
                 crossref(raw, property, property.domain, domain_of, included_in_domain_of);
             }
 
@@ -573,7 +582,7 @@ export function getData(vocab_source: string): Vocab {
                 subClassOf : raw.upper_value,
                 see_also   : raw.see_also,
                 example    : raw.example,
-                context       : final_contexts(raw, `${prefix}:${id}`),
+                context    : final_contexts(raw, `${prefix}:${id}`),
                 range_of, domain_of, included_in_domain_of, includes_range_of
             }
         }) : [];