Updated the descriptions of partnered schemas

hed-standard · May 30, 2023 · 8a41abf · 8a41abf
1 parent c1e5a5f
commit 8a41abf
Show file tree

Hide file tree

Showing 4 changed files with 80 additions and 29 deletions.
diff --git a/docs/source/07_Library_schemas.md b/docs/source/07_Library_schemas.md
@@ -90,7 +90,7 @@ which may be useful for debugging, but is usually not explicitly created.
 
 The following table summarizes the different partnered library schema formats
 and their uses. File names and link examples are specifically for the SCORE
-library. For other libraries, substitue the library name for the word *score*.
+library. For other libraries, substitute the library name for the word *score*.
 
 | Format | Merged<br/>status | Canonical filename | Handling |
 | ------ | ------------- | ------------------ | -------- |
@@ -108,15 +108,39 @@ There are four significant differences between merged and unmerged MediaWiki for
 unit modifiers, value classes, schema attributes, and schema properties)
 that it explicitly extends.
 <br/>&nbsp;<br/>
-3. Nodes with the `rooted` property must be top-level tags in the schema
-in the unmerged schema. In the merged schema, the subtrees under these `rooted` 
-nodes are placed directly under the respective nodes of the same name
-in the standard schema.
+3. In the unmerged schema, nodes with the `rooted=XXX` schema attribute must be top-level tags,
+and `XXX` must correspond to a node in the standard schema. In the merged schema, nodes with the `rooted=XXX` schema attribute are placed directly
+under the standard schema node `XXX`.
 <br/>&nbsp;<br/>
 4. Nodes in the unmerged version cannot have the `inLibrary` attribute.
 In contrast, nodes from the library schema are given the `inLibrary`
 attribute during the merging process.
 
+The following excerpt from an unmerged library schema in MediaWiki format shows a library schema node (`Data-mode`) rooted to `Statistical-value` in the
+standard schema. 
+
+````{admonition} Example of a rooted node in an unmerged schema in MediaWiki format.
+```html
+                      . . .
+'''Data-mode''' <nowiki>{rooted=Statistical-value}[A value that occurs most often in data.]</nowiki>   
+* <nowiki># {takesValue, valueClass=numericClass}</nowiki> 
+                      . . .
+```
+````
+Notice that the indentation asterisks (*) indicate that the node's children are at the first level.
+In the merged schema, these are adjusted accordingly as shown in the following:
+
+````{admonition} When merged with the standard schema, the indentation levels are adjusted.
+```html 
+                      . . .
+*** Statistical-value <nowiki>{extensionAllowed}[A value based on or employing the principles of statistics.]</nowiki>
+**** Data-mode''' <nowiki>{inLibrary}[A value that occurs most often in data.]</nowiki>   
+***** <nowiki># {takesValue, valueClass=numericClass, inLibrary}</nowiki> 
+                      . . .
+```
+````
+
+
 Similar differences occur between the merged and unmerged XML formats, 
 but only the merged XML format is useful.
 
@@ -161,7 +185,7 @@ HED standard schema 8.2.0:
 | `withStandard` | Header attribute | <ul><li>Indicates that this is a partnered library schema.</li><li>Its value is the version of its standard schema partner.</li></ul> |
 | `unmerged` | Header attribute | <ul><li>Indicates that this schema contains only library information.</li><li>Its value is either "true" or "false.</li><li>If "false", the attribute should be omitted.</li></ul> |
 | `inLibrary` | Element attribute | <ul><li>Indicates that this element is in the library schema.</li><li>Its value is the library name in lowercase.</li><li>The  attribute appears only in merged schemas.</li></ul> |
-| `rooted` | Node attribute | <ul><li>Indicates that this node is equivalent to a node in its<br/>partnered standard schema.</li><li>A node with this name must exist in both the library and its partnered library schema.</li><li>A node with the `rooted` attribute must be<br/>a top-level node in the unmerged schema.</li><li>A rooted node in the unmerged schema must not<br/> have a description or other attributes,<br/>since these are inherited from the standard schema.</li></ul> |
+| `rooted=XXX` | Node attribute | <ul><li>Indicates that this node is to appear directly under<br/> standard schema node `XXX` in the merged schema.</li><li>A node with the `rooted` attribute must be<br/>a top-level node in the unmerged schema.</li></ul> |
 | `reserved` | Node attribute | <ul><li>Indicates that this node has special meaning or function.</li><li>**Can only appear in standard schemas.**</li></ul>. |
 
 

diff --git a/docs/source/Appendix_A.md b/docs/source/Appendix_A.md
@@ -231,14 +231,20 @@ Only the schema attributes listed in the following table can be handled by curre
   - Specifies a character used in values of this class.
 * - `conversionFactor` 
   - unit, unitModifier
-  - Multiplicative factor to multiply by to convert to default units. <br/>
-    (Added in version 8.1.0.)
+  - Multiplicative factor to multiply by to convert to default <br/>
+    units. (Added in version 8.1.0.)
 * - `defaultUnits`*
   - unitClass
   - Specifies units to use if placeholder value has no units.   
+* - `deprecatedFrom`*
+  - element
+  - This element is deprecated. The value of the attribute <br/>is the latest schema version in which the element<br/>appeared before it was deprecated..   
 * - `extensionAllowed`
   - node
   - A tag can have unlimited levels of child nodes added.
+* - `inLibrary`
+  - element
+  - This schema element is from the named library schema,<br/>not the standard schema. (Added/removed by tools.)
 * - `recommended`
   - node
   - Event-level HED strings should include this tag.
@@ -251,6 +257,12 @@ Only the schema attributes listed in the following table can be handled by curre
 * - `required`
   - node      
   - Event-level HED string must include this tag.
+* - `reserved`
+  - node      
+  - This tag has special meaning and requires <br/>special handling by tools.
+* - `rooted`*
+  - node      
+  - A top-level library schema node should appear<br/>under this standard schema node when merged.  
 * - `SIUnit`
   - unit   
   - This unit represents an SI unit and can be modified.
@@ -299,7 +311,7 @@ However, the following group designations are allowed as values for this attribu
 
 If placeholder (`#`) has a `unitClass`, but the replacement value for the placeholder
 does not have units, tools may assume the value has `defaultUnits` if the unit class has them.
-For example, the `timeUnits` has the attribute `defaultUnits=s` in HED versions >=8.0.0.
+For example, the `timeUnits` has the attribute `defaultUnits=s` in HED versions.
 Tools may assume that tag `Duration/3` is  equivalent to `Duration/3 s` because `Duration` has
 `defaultUnits` of `s`.
 
@@ -314,7 +326,7 @@ In addition to the attributes listed above, some schema attributes have been dep
 and are no longer supported in HED, although they are still present in earlier versions of 
 the schema. The following table lists these.
 
-`````{list-table} Schema attributes deprecated for versions >=8.0.0 (* indicates attribute has a value).
+`````{list-table} Schema attributes deprecated for versions &ge; 8.0.0 (* indicates attribute has a value).
 :widths: 20 15 45
 :header-rows: 1
 
@@ -448,8 +460,7 @@ keyword `HED` followed by a blank-separated list of name-value pairs.
      - Description
    * - library
      - optional
-     - Name of library used in XML file names.  
-     
+     - Name of library used in XML file names.
        The value should only have lowercase alphabetic characters.
    * - version
      - required
@@ -460,7 +471,13 @@ keyword `HED` followed by a blank-separated list of name-value pairs.
    * - xsi
      - optional
      - xsi:noNamespaceSchemaLocation points to an XSD file.
-
+   * - withStandard
+     - optional
+     - The version of the standard schema partner if this is a partnered library schema.
+   * - unmerged
+     - optional
+     - If true, this is an unmerged partnered library schema.
+       If omitted, assumed false.      
 ````
 
 The following example gives a sample *header-line* for standard schema version 8.0.0 in `.mediawiki` format.
@@ -774,6 +791,17 @@ directory of the [**hed-schemas**](https://github.com/hed-standard/hedschemas) G
 Unknown header-line attributes are translated as attributes of the `HED` root node of the 
 `.xml` version, but a warning is issued when the `.mediawiki` file is validated.
 
+The `library` and `version` values are used to form the official xml file name `HED_testlib_1.0.2.xml`.
+
+Library schemas may also be partnered as is `HED_testlib_2.0.0.xml`.
+
+````{admonition} **Example:** Partnered library schema testlib version 2.0.0 in .xml format.
+```xml
+<HED library="testlib" version="2.0.0" withStandard="8.2.0">
+```
+````
+
+
 ### A.3.3. The prologue and epilogue
 
 The `<prologue>...</prologue>` and `<epilogue>...</epilogue>` elements 

diff --git a/docs/source/Appendix_B.md b/docs/source/Appendix_B.md
@@ -120,18 +120,17 @@ different placeholder substitutions are considered to be different.
 **a.**  An `Onset` or `Offset` tag does not appear in a tag group.  
 **b.**  An `Onset` or `Offset` tag appears in a nested tag group (not a top-level tag group).   
 **c.**  An `Onset` or `Offset` tag is not grouped with exactly one `Def` tag or `Def-expand` group.   
-**d.** An `Onset` group has more than one additional tag group.   
+**d.** An `Onset` or an `Inset` tag group contains more than one additional tag group.   
 **e.** An `Offset` appears with one or more tags or additional tag groups.   
 **f.**  An `Offset` tag appears before an `Onset` tag associated with the same definition.     
 **g.**  An `Offset` tag associated with a given definition appears after a previous `Offset` tag.
 without the appearance of an intervening `Onset` of the same name.   
-**h.**  An `Onset` tag group with has tags besides the anchor `Def` tag or `Def-expand` group
+**h.**  An `Onset` or an `Inset` tag group with has tags besides the anchor `Def` tag or `Def-expand` group
 that are not in a tag group.  
-**i.** An `Onset`, `Inset` or  `Offset` with a given `Def` tag or `Def-expand` group anchor
+**i.** An `Onset` or  `Offset` with a given `Def` tag or `Def-expand` group anchor
 appears in an event marker with the same time as with another `Onset`, `Inset`, or `Offset`
 that uses the same anchor.  
-**j.** An `Inset` tag is not grouped with a `Def` or `Def-expand` of an ongoing `Onset`.  
-**k.** An `Inset` group has more than a single tag group in addition to its defining `Def` or `Def-expand`.  
+**j.** An `Inset` tag is not grouped with a `Def` tag or a `Def-expand` group corresponding to an ongoing `Onset`.
 
 **Note:** if the `Onset` tag group's definition is in expanded form, 
 the `Def-expand` will be an additional internal tag group.

diff --git a/tests/json_tests/ONSET_OFFSET_INSET_ERROR.json b/tests/json_tests/ONSET_OFFSET_INSET_ERROR.json
@@ -1,7 +1,7 @@
 [
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "onset-offset-error-not-tag-group",
+        "name": "onset-offset-inset-error-not-tag-group",
         "description": "An Onset or Offset tag does not appear in a tag group.",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],
@@ -98,7 +98,7 @@
     },
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "onset-offset-error-nested-group",
+        "name": "onset-offset-inset-error-nested-group",
         "description": "An Onset or Offset tag appears in a nested tag group (not a top-level tag group).",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],
@@ -185,7 +185,7 @@
     },
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "onset-offset-error-wrong-number-of-defs",
+        "name": "onset-offset-inset-error-wrong-number-of-defs",
         "description": "An Onset or Offset tag is not grouped with exactly one Def-expand tag group or a Def tag.",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],
@@ -277,7 +277,7 @@
     },
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "onset-error-onset-has-more-groups",
+        "name": "onset-offset-inset-error-onset-has-more-groups",
         "description": "An Onset group has more than one additional tag group.",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],
@@ -373,7 +373,7 @@
     },
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "onset-offset-error-offset-has-groups",
+        "name": "onset-offset-inset-error-offset-has-groups",
         "description": "An Offset appears with one or more tags or additional tag groups.",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],
@@ -485,7 +485,7 @@
     },
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "onset-offset-error-mismatch",
+        "name": "onset-offset-inset-error-mismatch",
         "description": "An Offset tag associated with a given definition appears after a previous Offset tag without the appearance of an intervening Onset of the same name.",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],
@@ -563,7 +563,7 @@
     },
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "onset-offset-error-extra tags",
+        "name": "onset-offset-inset-error-extra tags",
         "description": "An Onset tag group with has tags besides the anchor Def or Def-expand that are not in a tag group.",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],
@@ -652,7 +652,7 @@
     },
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "onset-offset-error-duplicated-onset-or-offset",
+        "name": "onset-offset-inset-error-duplicated-onset-or-offset",
         "description": "An Onset or an Offset with a given Def or Def-expand anchor appears in the same event marker with another Onset or Offset that uses the same anchor.",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],
@@ -749,7 +749,7 @@
     },
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "inset-outside-its-event",
+        "name": "onset-offset-inset-error-inset-outside-its-event",
         "description": "An Inset tag is not grouped with a Def or Def-expand of an ongoing Onset.",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],
@@ -770,7 +770,7 @@
                 "fails": [
                     [
                         ["onset", "duration", "HED"],
-                        [ 4.5, 0, "(Def/MyColor, Offset)"],
+                        [ 4.5, 0, "(Inset, (Red))"],
                         [ 6.5, 0, "Red, (Def/MyColor, Offset)"],
                         [ 5.5, 0, "(Def/MyColor, Offset)"]
                     ]
@@ -830,7 +830,7 @@
     },
     {
         "error_code": "ONSET_OFFSET_INSET_ERROR",
-        "name": "inset-group-has-extras",
+        "name": "onset-offset-inset-error-inset-group-has-extras",
         "description": "An Inset group has tags or groups in addition to its defining Def or Def-expand.",
         "schema": "8.2.0",
         "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],