make termType a required field for MRG entries

Signed-off-by: Rieks <RieksJ@users.noreply.github.com>
tno-terminology-design · Apr 27, 2024 · 7578f9f · 7578f9f
1 parent 41da5c3
commit 7578f9f
Show file tree

Hide file tree

Showing 5 changed files with 73 additions and 37 deletions.
diff --git a/docs/specs/files/32-mrg.md b/docs/specs/files/32-mrg.md
@@ -128,12 +128,13 @@ An [MRG entry](@) has a few fields that are always present, because they are eit
 | -------------- | :---------- |
 | `scopetag`     | [Scopetag](@) that identifies the [scope](@) from within which the contents of the [MRG entry](@) is obtained.[^2] This is either [scope](@) from within which the [MRG](@) has been generated, or the [scope](@) from which the [MRG entry](@) was imported. In the latter case, the [`scopes` section](#mrg-scopes) in the [MRG](@) MUST contain a mapping between the `scopetag` and its associated [scope directory](@). |
 | `vsntag`       | [Versiontag](@) that identifies the version of the [terminology](@) from which the contents of the [MRG entry](@) is obtained. If the contents of the [MRG entry](@) was constructed from a [curated text](@), its value equals the value of the `vsntag` field in the [`terminology`-section](#mrg-terminology) of the [MRG](@) that this [MRG entry](@) is a part of. As a result, `scopetag`:`versiontag` identifies the [terminology](@) from which this [MRG entry](@) has originated. |
-| `locator`      | path, relative to `scopedir`/`curatedir`/, where the [curated text](@) lives from which the contents of the [MRG entry](@) was constructed. The value of `scopedir` can be obtained from the `scopes` section of the [MRG](@), and that of `curatedir` can be obtained from the [SAF](@) that lives in this `scopedir`. |
-| `navurl`       | path, relative to the URL as specified in the `website` field in the [`scope` section](/docs/specs/files/saf#scope-section) of the [SAF](@) (that lives in the `scopedir` as specified in the `scopes` section of the [MRG](@)), where the rendered version of the [curated text](@) is located. Its value will be empty if it cannot be constructed, e.g., because the `[navpath](@)` field in the [SAF](@) is empty or otherwise incorrect. |
-| `termid`       | [Text](termid@) that unambiguously identifies the [semantic unit](@) within this [scope](@) that is documented by this [MRG entry](@). There MUST NOT be another [MRG entry](@) within the [MRG](@) that has a `termid` field with the same value. |
-| `term`         | text that is used to refer to the [semantic unit](@) that is documented by the corresponding [curated text](@). |
-| `formPhrases`  | an array of [regularized form phrases](@), of which one element has the same value as the `term` field. |
-| `headingids`   | a list of the [markdown headings](https://www.markdownguide.org/basic-syntax/#headings) and/or [heading ids](https://www.markdownguide.org/extended-syntax/#linking-to-heading-ids) that exist in the file that contains the [body](@) of the [curated text](@), and can serve as `trait` in a [TermRef](@). |
+| `locator`      | Path, relative to `scopedir`/`curatedir`/, where the [curated text](@) lives from which the contents of the [MRG entry](@) was constructed. The value of `scopedir` can be obtained from the `scopes` section of the [MRG](@), and that of `curatedir` can be obtained from the [SAF](@) that lives in this `scopedir`. |
+| `navurl`       | Path, relative to the URL as specified in the `website` field in the [`scope` section](/docs/specs/files/saf#scope-section) of the [SAF](@) (that lives in the `scopedir` as specified in the `scopes` section of the [MRG](@)), where the rendered version of the [curated text](@) is located. Its value will be empty if it cannot be constructed, e.g., because the `[navpath](@)` field in the [SAF](@) is empty or otherwise incorrect. |
+| `termid`       | [Text](termid@) that unambiguously identifies the [semantic unit](@) within this [scope](@) that is documented by this [MRG entry](@). Its value is "`<termType>`:`<term>`", where `<termType>` and `<term>` are the values of the corresponding fields in this [MRG entry](@). There MUST NOT be another [MRG entry](@) within the [MRG](@) that has a `termid` field with the same value. |
+| `termType`     | [(Regularized) Text](term-type@) that identifies the kind of [semantic unit](@) that this [curated text](@) describes. Typical values would be `concept`, `relation`, `pattern` (or `mental-model`), or `usecase`. |
+| `term`         | [(Regularized) Text](regularized-text@) that identifies a [semantic unit](@) within this [scope](@), and hence also the [curated text](@) that describes it, which includes its [definition](@). Its value is typically the value of the `glossaryTerm` field, where all characters are made lower-case, any text between parentheses is discarded, and any (sequences of) spaces (or other special characters) are replaced with a `-`character. |
+| `formPhrases`  | Array of [regularized form phrases](@), of which one element has the same value as the `term` field. |
+| `headingids`   | List of the [markdown headings](https://www.markdownguide.org/basic-syntax/#headings) and/or [heading ids](https://www.markdownguide.org/extended-syntax/#linking-to-heading-ids) that exist in the file that contains the [body](@) of the [curated text](@), and can serve as `trait` in a [TermRef](@). |
 
 ```mdx-code-block
 </APITable>
@@ -167,27 +168,26 @@ The following table documents the fields that are used within the context of [TE
 <APITable>
 ```
 
-| Name            | Req'd | Description |
-| --------------- | :---: | :---------- |
-| `scopetag`        | Y | [Scopetag](@) that identifies the [scope](@) from within which the contents of the [MRG entry](@) is [curated](@), and obtained. The [`scopes` section](#mrg-scopes) in the [MRG](@) SHOULD contain a mapping between the `scopetag` and its associated [scope directory](@).|
-| `vsntag`          | Y | [Versiontag](@) that identifies the version of the [terminology](@) from which the contents of the [MRG entry](@) is obtained. If the contents of the [MRG entry](@) was constructed from a [curated text](@), its value equals the value of the `vsntag` field in the [`terminology`-section](#mrg-terminology) of the [MRG](@) that this [MRG entry](@) is a part of. As a result, `scopetag`:`versiontag` identifies the [terminology](@) from which this [MRG entry](@) has originated. |
-| `locator`         | Y | path, relative to `scopedir`/`curatedir`/, where the [curated text](@) lives from which the contents of the [MRG entry](@) was constructed. The value of `scopedir` can be obtained from the `scopes` section of the [MRG](@), and that of `curatedir` can be obtained from the [SAF](@) that lives in this `scopedir`. |
-| `navurl`          | Y | path, relative to the URL as specified in the `website` field in the [`scope` section](/docs/specs/files/saf#scope-section) of the [SAF](@) (that lives in the `scopedir` as specified in the `scopes` section of the [MRG](@)), where the rendered version of the [curated text](@) is located. Its value will be empty if it cannot be constructed, e.g., because the `[navpath](@)` field in the [SAF](@) is empty or otherwise incorrect. |
-| `headingids`      | Y | a list of the [markdown headings](https://www.markdownguide.org/basic-syntax/#headings) and/or [heading ids](https://www.markdownguide.org/extended-syntax/#linking-to-heading-ids) that exist in the file that contains the [body](@) of the [curated text](@), and can serve as `trait` in a [TermRef](@). Details are provided in the [MRGT specifications](mrgt#headingids-construction@) |
-| `termid`          | Y | [Text](termid@) that unambiguously identifies the [semantic unit](@) within this [scope](@) that is documented by this [MRG entry](@). There MUST NOT be another [MRG entry](@) within the [MRG](@) that has a `termid` field with the same value. |
-| `term`            | Y | [Text](term-identifier@) that identifies a [semantic unit](@) within this [scope](@), and hence also the [curated text](@) that describes it, which includes its [definition](@). Its value is typically the value of the `glossaryTerm` field, where all characters are made lower-case, any text between parentheses is discarded, and any (sequences of) spaces (or other special characters) are replaced with a `-`character. |
-| `termType`        | n | [Text](term-type@) that identifies the kind of [semantic unit](@) that this [curated text](@) describes. Typical values would be `concept`, `relation`, `pattern` (or `mental-model`), or `usecase`. |
-| `bodyFile`        | n | Path, relative to the [scopedir](@), that contains the [body](@) of this [curated text](@). If not specified, the [body](@) in this file serves as the [body](@) of the [curated text](@). |
-| `glossaryTerm`    | n | Text that is used for the [term](@) in a human readable [glossary](@). For example, for a [term](@) called `member`, you may want to specify a glossaryTerm `member (of a [community](@))`. |
-| `glossaryText`    | n | Text that is used as the (raw) contents for the entry of this [term](@) in a human readable [glossary](@). This text MUST be expected to contain [TermRefs](@). |
-| `synonymOf`       | n | [Term identifier](@) that identifies the defined [term](@) of the [semantic unit](@) for which this is a [synonym](@). |
-| `grouptags`       | n | List of [grouptags](@), each of which signifies that the [(scoped) term](@) that this [curated text](@) documents, is part of the group of [terms](@) that it represents.<br/>Example: `[tev2, management]`. |
-| `formPhrases`     | n | List of [texts](form-phrase@) that are [used to convert](trrt#id@) the `show text` parts of [TermRefs](@) into `term`s, for the purpose of accommodating plural forms (for nouns) or conjugate forms (for verbs). For details, see [Form Phrases](@).[^3] |
+| Name         | Req'd | Description |
+| ------------ | :---: | :---------- |
+| `scopetag`     | Y | [Scopetag](@) that identifies the [scope](@) from within which the contents of the [MRG entry](@) is [curated](@), and obtained. The [`scopes` section](#mrg-scopes) in the [MRG](@) SHOULD contain a mapping between the `scopetag` and its associated [scope directory](@).|
+| `vsntag`       | Y | [Versiontag](@) that identifies the version of the [terminology](@) from which the contents of the [MRG entry](@) is obtained. If the contents of the [MRG entry](@) was constructed from a [curated text](@), its value equals the value of the `vsntag` field in the [`terminology`-section](#mrg-terminology) of the [MRG](@) that this [MRG entry](@) is a part of. As a result, `scopetag`:`versiontag` identifies the [terminology](@) from which this [MRG entry](@) has originated. |
+| `locator`      | Y | Path, relative to `scopedir`/`curatedir`/, where the [curated text](@) lives from which the contents of the [MRG entry](@) was constructed. The value of `scopedir` can be obtained from the `scopes` section of the [MRG](@), and that of `curatedir` can be obtained from the [SAF](@) that lives in this `scopedir`. |
+| `navurl`       | Y | Path, relative to the URL as specified in the `website` field in the [`scope` section](/docs/specs/files/saf#scope-section) of the [SAF](@) (that lives in the `scopedir` as specified in the `scopes` section of the [MRG](@)), where the rendered version of the [curated text](@) is located. Its value will be empty if it cannot be constructed, e.g., because the `[navpath](@)` field in the [SAF](@) is empty or otherwise incorrect. |
+| `termid`       | Y | [Text](termid@) that unambiguously identifies the [semantic unit](@) within this [scope](@) that is documented by this [MRG entry](@). Its value is "`<termType>`:`<term>`", where `<termType>` and `<term>` are the values of the corresponding fields in this [MRG entry](@). There MUST NOT be another [MRG entry](@) within the [MRG](@) that has a `termid` field with the same value. |
+| `termType`     | Y | [(Regularized) Text](term-type@) that identifies the kind of [semantic unit](@) that this [curated text](@) describes. Typical values would be `concept`, `relation`, `pattern` (or `mental-model`), or `usecase`. |
+| `term`         | Y | [(Regularized) Text](regularized-text@) that identifies a [semantic unit](@) within this [scope](@), and hence also the [curated text](@) that describes it, which includes its [definition](@). Its value is typically the value of the `glossaryTerm` field, where all characters are made lower-case, any text between parentheses is discarded, and any (sequences of) spaces (or other special characters) are replaced with a `-`character. |
+| `formPhrases`  | Y | Array of [regularized form phrases](@), of which one element has the same value as the `term` field. |
+| `headingids`   | Y | List of the [markdown headings](https://www.markdownguide.org/basic-syntax/#headings) and/or [heading ids](https://www.markdownguide.org/extended-syntax/#linking-to-heading-ids) that exist in the file that contains the [body](@) of the [curated text](@), and can serve as `trait` in a [TermRef](@). Details are provided in the [MRGT specifications](mrgt#headingids-construction@) |
+| `bodyFile`     | n | Path, relative to the [scopedir](@), that contains the [body](@) of this [curated text](@). If not specified, the [body](@) in this file serves as the [body](@) of the [curated text](@). |
+| `glossaryTerm` | n | Text that is used for the [term](@) in a human readable [glossary](@). For example, for a [term](@) called `member`, you may want to specify a glossaryTerm `member (of a [community](@))`. |
+| `glossaryAbbr` | n | Text that serves as an abbreviated for of the [term](@). It can be used, e.g., to create a [HRG](@) that effectively is a Table of Abbreviations. |
+| `glossaryText` | n | Text that is used as the (raw) contents for the entry of this [term](@) in a human readable [glossary](@). This text MUST be expected to contain [TermRefs](@). |
+| `glossaryNotes`| n | Array of texts that can serve as notes in a [HRG entry](@) that corresponds with this [MRG entry](@). |
+| `synonymOf`    | n | [Term identifier](@) that identifies the defined [term](@) of the [semantic unit](@) for which this is a [synonym](@). |
+| `grouptags`    | n | List of [grouptags](@), each of which signifies that the [(scoped) term](@) that this [curated text](@) documents, is part of the group of [terms](@) that it represents.<br/>Example: `[tev2, management]`. |
 
 ```mdx-code-block
 </APITable>
 ```
-
-[^3]: The `formPhrases` field in an [MRG Entry](@) is void of so-called [form phrase macros](@); it is simply a (possibly extensive) list of [form phrases](@).
-
 # Footnotes