Implement support for library schemas

.eslintrc.json

@@ -19,6 +19,16 @@
     "no-console": ["error", { "allow": ["warn"] }],
     "linebreak-style": ["error", "unix"],
     "guard-for-in": "error",
-    "max-len": "off"
+    "max-len": "off",
+    "no-var": "error",
+    "prefer-const": "error",
+    "array-callback-return": "error",
+    "no-constant-binary-expression": "error",
+    "no-constructor-return": "error",
+    "no-self-compare": "error",
+    "no-template-curly-in-string": "error",
+    "no-unmodified-loop-condition": "error",
+    "no-unreachable": "error",
+    "prefer-arrow-callback": ["error", { "allowUnboundThis": false }]
   }
 }

README.md

@@ -8,14 +8,15 @@ The HED annotation strategy is very general and a standardized vocabulary in the
 [HED schema](https://github.com/hed-standard/hed-specification) enables
 annotation of events in an understandable, machine-actionable format.
 
-Additional [library schemas](https://github.com/hed-standard/hed-schema-library) 
+Additional [library schemas](https://github.com/hed-standard/hed-schema-library)
 with specialized vocabularies needed for particular subfields are under development.
 
 HED validation occurs at several levels.
 Syntactic validation checks that HED strings comply with the required syntax,
 but not whether tags comply with the additional requirements of a HED schema.
 
 Semantic validation verifies validity at many levels:
+
 1. **Tag-level validation** checks that tags are in the schema
    and have correct units and value type.
 2. **String-level validation** performs additional checks for correctness.
@@ -78,8 +79,9 @@ const dataset = new hedValidator.validator.BidsDataset(eventData, sidecarData)
   }
 }
 ```
+
 The `schemaDefinition` object follows a similar format as the BIDS `HEDVersion` object,
 but with local `path` values pre-parsed to use the fully qualified path name.
 
-The primary objects needed for HED validation can be found in 
+The primary objects needed for HED validation can be found in
 [validator/bids/types.js](https://github.com/hed-standard/hed-javascript/blob/master/validator/bids/types.js).

common/issues/data.js

@@ -1,15 +1,21 @@
 const { stringTemplate } = require('../../utils/string')
 
 const issueData = {
+  // Syntax issues
   parentheses: {
     hedCode: 'HED_PARENTHESES_MISMATCH',
     level: 'error',
     message: stringTemplate`Number of opening and closing parentheses are unequal. ${'opening'} opening parentheses. ${'closing'} closing parentheses.`,
   },
-  invalidTag: {
-    hedCode: 'HED_TAG_INVALID',
+  unopenedParentheses: {
+    hedCode: 'HED_PARENTHESES_MISMATCH',
     level: 'error',
-    message: stringTemplate`Invalid tag - "${'tag'}"`,
+    message: stringTemplate`Closing parenthesis at index ${'index'} of string "${'string'}" does not have a corresponding opening parenthesis.`,
+  },
+  unclosedParentheses: {
+    hedCode: 'HED_PARENTHESES_MISMATCH',
+    level: 'error',
+    message: stringTemplate`Opening parenthesis at index ${'index'} of string "${'string'}" does not have a corresponding closing parenthesis.`,
   },
   extraDelimiter: {
     hedCode: 'HED_TAG_EMPTY',
@@ -26,16 +32,27 @@ const issueData = {
     level: 'error',
     message: stringTemplate`Duplicate tag at indices (${0}, ${1}) - "${'tag'}"`,
   },
+  invalidCharacter: {
+    hedCode: 'HED_CHARACTER_INVALID',
+    level: 'error',
+    message: stringTemplate`Invalid character "${'character'}" at index ${'index'} of string "${'string'}"`,
+  },
+  // Common semantic validation issues
+  invalidTag: {
+    hedCode: 'HED_TAG_INVALID',
+    level: 'error',
+    message: stringTemplate`Invalid tag - "${'tag'}"`,
+  },
+  extraCommaOrInvalid: {
+    hedCode: 'HED_TAG_INVALID',
+    level: 'error',
+    message: stringTemplate`Either "${'previousTag'}" contains a comma when it should not or "${'tag'}" is not a valid tag`,
+  },
   multipleUniqueTags: {
     hedCode: 'HED_TAG_NOT_UNIQUE',
     level: 'error',
     message: stringTemplate`Multiple unique tags with prefix - "${'tag'}"`,
   },
-  tooManyTildes: {
-    hedCode: 'HED_TILDES_UNSUPPORTED',
-    level: 'error',
-    message: stringTemplate`Too many tildes - group "${'tagGroup'}"`,
-  },
   childRequired: {
     hedCode: 'HED_TAG_REQUIRES_CHILD',
     level: 'error',
@@ -56,75 +73,51 @@ const issueData = {
     level: 'error',
     message: stringTemplate`Invalid unit - "${'tag'}" - valid units are "${'unitClassUnits'}"`,
   },
-  extraCommaOrInvalid: {
-    hedCode: 'HED_TAG_INVALID',
-    level: 'error',
-    message: stringTemplate`Either "${'previousTag'}" contains a comma when it should not or "${'tag'}" is not a valid tag`,
-  },
-  invalidCharacter: {
-    hedCode: 'HED_CHARACTER_INVALID',
+  invalidValue: {
+    hedCode: 'HED_VALUE_INVALID',
     level: 'error',
-    message: stringTemplate`Invalid character "${'character'}" at index ${'index'} of string "${'string'}"`,
-  },
-  extension: {
-    hedCode: 'HED_TAG_EXTENDED',
-    level: 'warning',
-    message: stringTemplate`Tag extension found - "${'tag'}"`,
+    message: stringTemplate`Invalid placeholder value for tag "${'tag'}"`,
   },
   invalidPlaceholder: {
     hedCode: 'HED_PLACEHOLDER_INVALID',
     level: 'error',
     message: stringTemplate`Invalid placeholder - "${'tag'}"`,
   },
-  invalidPlaceholderInDefinition: {
-    hedCode: 'HED_PLACEHOLDER_INVALID',
-    level: 'error',
-    message: stringTemplate`Invalid placeholder in definition - "${'definition'}"`,
-  },
   missingPlaceholder: {
     hedCode: 'HED_PLACEHOLDER_INVALID',
     level: 'error',
     message: stringTemplate`HED value string "${'string'}" is missing a required placeholder.`,
   },
-  invalidValue: {
-    hedCode: 'HED_VALUE_INVALID',
-    level: 'error',
-    message: stringTemplate`Invalid placeholder value for tag "${'tag'}"`,
-  },
-  invalidParentNode: {
-    hedCode: 'HED_VALUE_IS_NODE',
-    level: 'error',
-    message: stringTemplate`"${'tag'}" appears as "${'parentTag'}" and cannot be used as an extension. Indices (${0}, ${1}).`,
-  },
-  emptyTagFound: {
-    hedCode: 'HED_NODE_NAME_EMPTY',
-    level: 'error',
-    message: stringTemplate`Empty tag cannot be converted.`,
+  extension: {
+    hedCode: 'HED_TAG_EXTENDED',
+    level: 'warning',
+    message: stringTemplate`Tag extension found - "${'tag'}"`,
   },
-  duplicateTagsInSchema: {
-    hedCode: 'HED_GENERIC_ERROR',
+  // HED 3-specific validation issues
+  invalidPlaceholderInDefinition: {
+    hedCode: 'HED_PLACEHOLDER_INVALID',
     level: 'error',
-    message: stringTemplate`Source HED schema is invalid as it contains duplicate tags.`,
+    message: stringTemplate`Invalid placeholder in definition - "${'definition'}"`,
   },
-  illegalDefinitionGroupTag: {
+  nestedDefinition: {
     hedCode: 'HED_DEFINITION_INVALID',
     level: 'error',
-    message: stringTemplate`Illegal tag "${'tag'}" in tag group for definition "${'definition'}"`,
+    message: stringTemplate`Illegal nested definition in tag group for definition "${'definition'}"`,
   },
-  nestedDefinition: {
+  duplicateDefinition: {
     hedCode: 'HED_DEFINITION_INVALID',
     level: 'error',
-    message: stringTemplate`Illegal nested definition in tag group for definition "${'definition'}"`,
+    message: stringTemplate`Definition "${'definition'}" is declared multiple times. This instance's tag group is "${'tagGroup'}"`,
   },
   multipleTagGroupsInDefinition: {
     hedCode: 'HED_DEFINITION_INVALID',
     level: 'error',
     message: stringTemplate`Multiple inner tag groups found in definition "${'definition'}"`,
   },
-  duplicateDefinition: {
+  illegalDefinitionGroupTag: {
     hedCode: 'HED_DEFINITION_INVALID',
     level: 'error',
-    message: stringTemplate`Definition "${'definition'}" is declared multiple times. This instance's tag group is "${'tagGroup'}"`,
+    message: stringTemplate`Illegal tag "${'tag'}" in tag group for definition "${'definition'}"`,
   },
   invalidTopLevelTagGroupTag: {
     hedCode: 'HED_TAG_GROUP_ERROR',
@@ -141,20 +134,78 @@ const issueData = {
     level: 'error',
     message: stringTemplate`Tag "${'tag'}" is only allowed inside of a tag group.`,
   },
-  requestedSchemaLoadFailed: {
+  // Tag conversion issues
+  invalidParentNode: {
+    hedCode: 'HED_VALUE_IS_NODE',
+    level: 'error',
+    message: stringTemplate`"${'tag'}" appears as "${'parentTag'}" and cannot be used as an extension. Indices (${0}, ${1}).`,
+  },
+  emptyTagFound: {
+    hedCode: 'HED_NODE_NAME_EMPTY',
+    level: 'error',
+    message: stringTemplate`Empty tag cannot be converted.`,
+  },
+  duplicateTagsInSchema: {
+    hedCode: 'HED_GENERIC_ERROR',
+    level: 'error',
+    message: stringTemplate`Source HED schema is invalid as it contains duplicate tags.`,
+  },
+  // Schema issues
+  invalidSchemaNickname: {
+    hedCode: 'HED_SCHEMA_LOAD_FAILED',
+    level: 'error',
+    message: stringTemplate`The prefix nickname "${'nickname'}" in specification "${'spec'}" is duplicated or invalid.`,
+  },
+  invalidSchemaSpecification: {
+    hedCode: 'HED_SCHEMA_LOAD_FAILED',
+    level: 'error',
+    message: stringTemplate`The supplied schema specification is invalid. Specification: ${'spec'}`,
+  },
+  requestedSchemaLoadFailedFallbackUsed: {
     hedCode: 'HED_SCHEMA_LOAD_FAILED',
     level: 'warning',
-    message: stringTemplate`The requested schema "${'schemaDefinition'}" failed to load. The error given was "${'error'}". The fallback schema bundled with this validator will be used instead.`,
+    message: stringTemplate`The requested schema failed to load. The fallback schema bundled with this validator will be used instead. Specification: ${'spec'}`,
+  },
+  requestedSchemaLoadFailedNoFallbackUsed: {
+    hedCode: 'HED_SCHEMA_LOAD_FAILED',
+    level: 'error',
+    message: stringTemplate`The requested schema failed to load. The validator did not attempt to load a fallback schema. Specification: ${'spec'}`,
   },
   fallbackSchemaLoadFailed: {
     hedCode: 'HED_SCHEMA_LOAD_FAILED',
     level: 'error',
-    message: stringTemplate`The fallback schema bundled with this validator failed to load. The error given was "${'error'}". No HED validation was performed.`,
+    message: stringTemplate`The fallback schema bundled with this validator failed to load. No HED validation was performed.`,
+  },
+  bundledSchemaLoadFailed: {
+    hedCode: 'HED_SCHEMA_LOAD_FAILED',
+    level: 'error',
+    message: stringTemplate`Could not load HED schema for spec "${'spec'}" from bundled copy - "${'error'}".`,
+  },
+  localSchemaLoadFailed: {
+    hedCode: 'HED_SCHEMA_LOAD_FAILED',
+    level: 'error',
+    message: stringTemplate`Could not load HED schema from path "${'path'}" - "${'error'}".`,
+  },
+  remoteSchemaLoadFailed: {
+    hedCode: 'HED_SCHEMA_LOAD_FAILED',
+    level: 'error',
+    message: stringTemplate`Could not load HED schema "${'spec'}" from remote repository - "${'error'}".`,
+  },
+  unmatchedBaseSchema: {
+    hedCode: 'HED_LIBRARY_UNMATCHED',
+    level: 'error',
+    message: stringTemplate`Tag "${'tag'}" is declared to use a base schema in the dataset's schema listing, but no such schema was defined.`,
+  },
+  unmatchedLibrarySchema: {
+    hedCode: 'HED_LIBRARY_UNMATCHED',
+    level: 'error',
+    message: stringTemplate`Tag "${'tag'}" is declared to use a library schema nicknamed "${'library'}" in the dataset's schema listing, but no such schema was found.`,
   },
+  // Generic errors
   genericError: {
     hedCode: 'HED_GENERIC_ERROR',
     level: 'error',
-    message: stringTemplate`Unknown HED error "${'internalCode'}".`,
+    message: stringTemplate`Unknown HED error "${'internalCode'}" - parameters: "${'parameters'}".`,
   },
 }
 

common/issues/issues.js

@@ -21,6 +21,7 @@ class Issue {
      * Also the internal error code.
      *
      * TODO: This is kept for backward compatibility until the next major version bump.
+     * @deprecated
      * @type {string}
      */
     this.code = internalCode
@@ -46,20 +47,23 @@ class Issue {
  * Generate a new issue object.
  *
  * @param {string} internalCode The internal error code.
- * @param {object<string, (string|number[])>} parameters The error string parameters.
+ * @param {Object<string, (string|number[])>} parameters The error string parameters.
  * @return {Issue} An object representing the issue.
  */
 const generateIssue = function (internalCode, parameters) {
   const issueCodeData = issueData[internalCode] || issueData.genericError
   const { hedCode, level, message } = issueCodeData
   const bounds = parameters.bounds || []
-  parameters.internalCode = internalCode
+  if (issueCodeData === issueData.genericError) {
+    parameters.internalCode = internalCode
+    parameters.parameters = 'Issue parameters: ' + JSON.stringify(parameters)
+  }
   const parsedMessage = message(...bounds, parameters)
 
   return new Issue(internalCode, hedCode, level, parsedMessage)
 }
 
 module.exports = {
-  generateIssue: generateIssue,
-  Issue: Issue,
+  generateIssue,
+  Issue,
 }

common/schema/config.js

@@ -1,4 +1,15 @@
+/** Path to the fallback HED schema. */
+
+const localSchemaList = new Map([
+  ['HED8.0.0', require('../../data/HED8.0.0.xml')],
+  ['HED8.1.0', require('../../data/HED8.1.0.xml')],
+  ['HED_testlib_1.0.2', require('../../data/HED_testlib_1.0.2.xml')],
+])
+
+// TODO: Delete in 4.0.0.
+const fallbackFilePath = 'data/HED8.0.0.xml'
+
 module.exports = {
-  /** Path to the fallback HED schema. */
-  fallbackFilePath: 'data/HED8.0.0.xml',
+  fallbackFilePath,
+  localSchemaList,
 }

common/schema/index.js

@@ -3,8 +3,8 @@ const loadSchema = require('./loader')
 const { Schema, Schemas } = require('./types')
 
 module.exports = {
-  loadSchema: loadSchema,
-  Schema: Schema,
-  Schemas: Schemas,
-  config: config,
+  loadSchema,
+  Schema,
+  Schemas,
+  config,
 }