Merge pull request #24 from w3c/Adding-context-information

Adding context information to vocabularies

CHANGES.md

@@ -1,3 +1,7 @@
+## Version 1.4.7
+
+- Adding information on `@context` files
+
 ## Version 1.4.6
 
 - Label is now optional

README.md

@@ -9,27 +9,28 @@ When running, the script relies on two files:
 
 ## Definition of the vocabulary in the YAML file
 
-The vocabulary is defined in a YAML file, which contains several block sequences with the following keys: `vocab`, `prefix`, `ontology`, `class`, `property`, and `individual`. Only the `vocab` and `ontology` blocks are _required_, all others are optional.
+The vocabulary is defined in a YAML file, which contains several block sequences with the following keys: `vocab`, `prefix`, `ontology`, `class`, `property`, `individual`, and `datatype`. Only the `vocab` and `ontology` blocks are _required_, all others are optional.
 
-Each block sequence consists of blocks with the following keys:`id`, `property`, `value`, `label`, `upper_value`, `domain`, `range`, `deprecated`, `comment`, `status`, `defined_by`, and `see_also`. The interpretation of these key/value pairs may depend on the top level block where they reside, but some have a common interpretation.
+Each block sequence consists of blocks with the following keys:`id`, `property`, `value`, `label`, `upper_value`, `domain`, `range`, `deprecated`, `comment`, `status`, `defined_by`, `context`, and `see_also`. The interpretation of these key/value pairs may depend on the top level block where they reside, but some have a common interpretation.
 
-- Common key/value pairs for the `class`, `property`, and `individual` blocks:
+- Common key/value pairs for the `class`, `property`, `datatype`, and `individual` blocks:
   - `label` refers to a short header label to the term. If missing, the capitalized value of `id` is used. 
   - `comment` refers to a longer description of the term, and can be used for blocks in the `class`, `property` and `individual` top-level blocks. It may include [HTML Flow content elements](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories). The comment will be encapsulated into an HTML `<div>` element and will then be displayed verbatim in the HTML version of the vocabulary, and as a literal of type `rdf:HTML` in the JSON-LD and Turtle versions. Note that the Markdown syntax for simple formatting, like the use of "`" for `<code.../>`, may also be used.
   - `defined_by` should be a URL, referring to the formal definition of the term.
   - `see_also` refers to one or more blocks with `label` and `url` keys, providing a human readable title and a URL, respectively, to an external document that can be referred to by the description of the term. (These are translated into an `rdfs:seeAlso` term in the vocabulary.)
   - The `status` key refers to a string that can be `stable`, `reserved`, or `deprecated`. The terms are divided, in the HTML output, into these three sections. `stable` is the default.
   - 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.
 
   For these blocks the `id` key, and either the `comment` or the `defined_by` keys, are _required_. All the others are optional.
 
 - Top level blocks:
-  - `vocab`: a block with the `prefix` and the `value` keys defining the prefix and the URL of the vocabulary, respectively. The prefix can be used in the vocabulary descriptions, e.g., for cross references.
+  - `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).
 
   - `prefix`: definition of a prefixes, and corresponding URLs, for each external external vocabulary in use, defined by the `id` and `value` keys, respectively. 
 
-    Some prefix/value pairs are defined by default, and it is not necessary to define them here. These are: `dc` (for `http://purl.org/dc/terms/`), `owl` (for `http://www.w3.org/2002/07/owl#`), `rdf` (for `http://www.w3.org/1999/02/22-rdf-syntax-ns#`), `rdfs` (for `http://www.w3.org/2000/01/rdf-schema#`), and `xsd` (for `http://www.w3.org/2001/XMLSchema#`).
+    Some id/value pairs are defined by default, and it is not necessary to define them here. These are: `dc` (for `http://purl.org/dc/terms/`), `owl` (for `http://www.w3.org/2002/07/owl#`), `rdf` (for `http://www.w3.org/1999/02/22-rdf-syntax-ns#`), `rdfs` (for `http://www.w3.org/2000/01/rdf-schema#`), `xsd` (for `http://www.w3.org/2001/XMLSchema#`), and `schema` (for `http://schema.org/`).
 
   - `ontology`: definition of "ontology properties", that is, statements made about the vocabulary itself. The (prefixed) property term is defined by the `property` key, and the value by the `value` key. If the value can be parsed as a URL, it is considered to be the URL of an external resource; otherwise, the value is considered to be (English) text.
 

dist/lib/common.js

@@ -60,18 +60,24 @@ class StatusCounter {
 }
 exports.StatusCounter = StatusCounter;
 /**
- * Placeholder for some global data.
+ * As it name says: some global data that are needed by most of the media type specific modules.
  */
 exports.global = {
     /** Vocabulary prefix for the vocabulary being handled */
     vocab_prefix: "",
     /** Vocabulary URL for the vocabulary being handled */
     vocab_url: "",
+    /** Default context URL for the vocabulary being handled */
+    vocab_context: "",
     /**
      * Counter for the terms with various status values.
      * Some serializers (eg HTML) may optimize/improve the final
      * output if one of the categories have no entries whatsoever.
      */
     status_counter: new StatusCounter(),
+    /**
+     * Inverted info for contexts: for each context the list of relevant terms are listed
+     */
+    context_mentions: {},
 };
 ;

dist/lib/convert.js

@@ -28,6 +28,40 @@ const isURL = (value) => {
         return false;
     }
 };
+/**
+ * Turn the label text into a non-camel case
+ *
+ * @param str
+ * @param separator
+ * @returns
+ */
+function localeUnCamelise(str, separator = ' ') {
+    const isLocaleUpperCase = (char) => {
+        return char[0] === char.toLocaleUpperCase();
+    };
+    if (str.length === 0) {
+        return str;
+    }
+    else {
+        // First character is ignored; it can be upper or lower case
+        const retval = [str.charAt(0)];
+        for (let i = 1; i < str.length; i++) {
+            const char = str.charAt(i);
+            if (isLocaleUpperCase(char)) {
+                // Got to the camel's hump
+                retval.push(separator);
+                retval.push(char.toLocaleLowerCase());
+            }
+            else {
+                retval.push(char);
+            }
+        }
+        // The first character must be capitalized:
+        retval[0] = retval[0].toLocaleUpperCase();
+        return retval.join('');
+    }
+}
+/********************************************************************************/
 /**
  * These prefixes are added no matter what; they are not vocabulary specific
  *
@@ -57,6 +91,14 @@ const defaultPrefixes = [
     {
         prefix: "vs",
         url: "http://www.w3.org/2003/06/sw-vocab-status/ns#"
+    },
+    {
+        prefix: "schema",
+        url: "http://schema.org/"
+    },
+    {
+        prefix: "jsonld",
+        url: "http://www.w3.org/ns/json-ld#"
     }
 ];
 /**
@@ -86,7 +128,22 @@ function finalizeRawEntry(raw) {
             return undefined;
         }
         else if (val.length === 0) {
-            return undefined;
+            return [];
+        }
+        else if (typeof val === "string") {
+            return [val];
+        }
+        else {
+            return val;
+        }
+    };
+    // Almost like to array, except that instead of undefined a real default value is returned
+    const toArrayContexts = (val) => {
+        if (val === undefined) {
+            return ["vocab"];
+        }
+        else if (val.length === 0) {
+            return ["vocab"];
         }
         else if (typeof val === "string") {
             return [val];
@@ -186,7 +243,8 @@ function finalizeRawEntry(raw) {
             return str;
         }
         else if (raw.id && raw.id.length > 0) {
-            return raw.id[0].toLocaleUpperCase() + raw.id.substring(1);
+            return localeUnCamelise(raw.id);
+            // return raw.id[0].toLocaleUpperCase() + raw.id.substring(1);
         }
         else {
             return "";
@@ -207,6 +265,7 @@ function finalizeRawEntry(raw) {
         see_also: toSeeAlso(raw.see_also),
         example: toExample(raw.example),
         dataset: (raw.dataset === undefined) ? false : raw.dataset,
+        context: toArrayContexts(raw.context)
     };
 }
 /**
@@ -259,6 +318,34 @@ function getData(vocab_source) {
         throw (new TypeError(`JSON Schema validation error`, { cause: error }));
     }
     const vocab = finalizeRawVocab(validation_results.vocab);
+    // Establish the final context reference(s), if any, for a term.
+    // As a side effect, the 'inverse' info, ie, the list of terms per context, is
+    // created in the global data structure
+    const final_contexts = (raw) => {
+        if (raw.context === undefined)
+            return [];
+        // replace the value of "vocab" by the global context, then
+        // get the possible "none" out of the way.
+        const contexts = raw.context.map((val) => {
+            if (val === "vocab") {
+                // The global context may not have been set...
+                return common_2.global.vocab_context !== undefined ? common_2.global.vocab_context : "none";
+            }
+            else {
+                return val;
+            }
+        }).filter((val) => val !== "none");
+        // Make sure that all entries are unique before returning it
+        const ctx_s = [...new Set(contexts)];
+        // 'Inverse' info: add the term reference to the global data
+        for (const ctx of ctx_s) {
+            if (ctx in common_2.global.context_mentions === false) {
+                common_2.global.context_mentions[ctx] = [];
+            }
+            common_2.global.context_mentions[ctx].push(raw.id);
+        }
+        return ctx_s;
+    };
     // Calculates cross references from properties to classes or datatypes; used
     // to make the cross references for the property ranges and domains
     // @param raw: raw entry for the class or datatype
@@ -293,6 +380,10 @@ function getData(vocab_source) {
             }
             common_2.global.vocab_prefix = raw.id;
             common_2.global.vocab_url = raw.value;
+            common_2.global.vocab_context = raw.context === undefined ? undefined : raw.context[0];
+            if (common_2.global.vocab_context) {
+                common_2.global.context_mentions[common_2.global.vocab_context] = [];
+            }
             return {
                 prefix: raw.id,
                 url: raw.value,
@@ -361,6 +452,7 @@ function getData(vocab_source) {
                 domain: raw.domain,
                 example: raw.example,
                 dataset: raw.dataset,
+                context: final_contexts(raw),
             };
         }) : [];
     // Get the classes. Note the special treatment for deprecated classes and the location of relevant domains and ranges
@@ -391,6 +483,7 @@ function getData(vocab_source) {
                 subClassOf: raw.upper_value,
                 see_also: raw.see_also,
                 example: raw.example,
+                context: final_contexts(raw),
                 range_of, domain_of, included_in_domain_of, includes_range_of
             };
         }) : [];
@@ -407,6 +500,7 @@ function getData(vocab_source) {
                 type: (raw.upper_value !== undefined) ? raw.upper_value : [],
                 see_also: raw.see_also,
                 example: raw.example,
+                context: final_contexts(raw),
             };
         }) : [];
     // Get the datatypes. 
@@ -433,6 +527,7 @@ function getData(vocab_source) {
                 type: (raw.upper_value !== undefined) ? raw.upper_value : [],
                 see_also: raw.see_also,
                 example: raw.example,
+                context: final_contexts(raw),
                 range_of, includes_range_of
             };
         }) : [];