From d2e11a668c72aed297e7e5acf3d200e9d2b2e464 Mon Sep 17 00:00:00 2001 From: Rieks Date: Fri, 1 Mar 2024 11:32:33 +0100 Subject: [PATCH] cleaning up terms that are sufficiently well-known Signed-off-by: Rieks --- docs/guides/10-preparation-git.md | 2 +- .../42-curator-terminology-construction.md | 10 ++-- docs/overview/00-tev2-common-understanding.md | 2 +- docs/saf.yaml | 9 +--- docs/specs/files/10-curated-text-file.md | 6 +-- docs/specs/files/12-saf.md | 8 +-- docs/specs/files/32-mrg.md | 26 ++++----- docs/specs/syntax/10-term-refs.md | 4 +- docs/specs/syntax/21-term-identifiers.md | 20 +++---- .../syntax/31-terminology-identifiers.md | 16 +++--- docs/specs/syntax/41-mrg-refs.md | 4 +- docs/specs/syntax/62-term-selection.md | 12 ++--- docs/specs/tools-envisaged/11-ict.md | 2 +- docs/specs/tools/12-trrt.md | 6 +-- docs/specs/tools/21-mrgt.md | 2 +- docs/specs/tools/22-hrgt.md | 2 +- docs/terms/corpus.md | 4 +- docs/terms/curate.md | 4 +- docs/terms/curator.md | 4 +- docs/terms/define.md | 4 +- docs/terms/definition.md | 6 +-- docs/terms/form-phrase-macro.md | 4 +- docs/terms/form-phrase.md | 4 +- docs/terms/identifier.md | 54 ------------------- docs/terms/identify.md | 38 ------------- docs/terms/knowledge-artifact.md | 29 ---------- docs/terms/mental-model.md | 2 +- docs/terms/patterns/pattern-terminology.md | 34 ++++++------ docs/terms/regularized-text.md | 2 +- docs/terms/scope.md | 6 +-- docs/terms/scoped-term.md | 4 +- docs/terms/scopetag.md | 8 +-- docs/terms/semantic-unit.md | 8 +-- docs/terms/semantics.md | 2 +- docs/terms/tag.md | 2 +- docs/terms/term-identifier.md | 2 +- docs/terms/term-selection-instruction.md | 2 +- docs/terms/term-type.md | 4 +- docs/terms/term.md | 6 +-- docs/terms/termid.md | 4 +- docs/terms/terminology-identifier.md | 2 +- docs/terms/terminology-process.md | 18 +++---- docs/terms/terms-community.md | 8 +-- docs/terms/tev2-toolbox.md | 2 +- docs/terms/versiontag.md | 6 +-- 45 files changed, 139 insertions(+), 265 deletions(-) delete mode 100644 docs/terms/identifier.md delete mode 100644 docs/terms/identify.md delete mode 100644 docs/terms/knowledge-artifact.md diff --git a/docs/guides/10-preparation-git.md b/docs/guides/10-preparation-git.md index 22ea1fb2c1..4e709250b3 100644 --- a/docs/guides/10-preparation-git.md +++ b/docs/guides/10-preparation-git.md @@ -243,7 +243,7 @@ versions: - "term[action]@essif-lab" - "rename action [id:act, term:act, formPhrases:'act{ss}']" - "term[party,actor,onboarding,action,organization,community,entity,legal-entity]@essif-lab" - - "term[ssi,assertion,claim,credential,issue,verify,validate,transaction]@essif-lab" + - "term[ssi,assertion,claim,credential,issue,verify,validate]@essif-lab" - "term[manage,management,governance,risk,owner,owned]@essif-lab" - "term[jurisdiction,objective,control,expectation,obligation]@essif-lab" - "term[control-objective,risk-objective,compliance-objective]@essif-lab" diff --git a/docs/manuals/curator/42-curator-terminology-construction.md b/docs/manuals/curator/42-curator-terminology-construction.md index 0de650be0c..ae8124273c 100644 --- a/docs/manuals/curator/42-curator-terminology-construction.md +++ b/docs/manuals/curator/42-curator-terminology-construction.md @@ -22,7 +22,7 @@ The specification of a [terminology](@) exists as an entry in the [`versions` se A new [terminology](@) specification must at least have -- a [versiontag](@) that allows the [terminology](@) to be [identified](@) (within its [scope](@)), +- a [versiontag](@) that allows the [terminology](@) to be identified (within its [scope](@)), - a list of [term selection instructions](@) that specify the [terms](@) that are to be included (or removed) from the [terminology](@) as it is being constructed, and - some meta-data (see the [documentation](/docs/specs/files/saf#versions). @@ -89,7 +89,7 @@ In the syntax specification for [term selection instructions](@), we use the fol | Symbol | Description | | :----- | :---------- | | `` | a text that corresponds with a field name in an [MRG entry](@) of a designated [MRG](@), or the [header](@) (front-matter) of a [curated text](@). Examples: `term`, `grouptags`, `status`. | -| `` | a text that is used to [identify](@) an [MRG entry](@) or a [curated text](@). | +| `` | a text that is used to identify an [MRG entry](@) or a [curated text](@). | @@ -108,7 +108,7 @@ However, any (existing) [MRG](@) can be used as an alternative source, by adding The following syntaxes are available for adding all terms from a specific source to the [provisional MRG](@): - **`*`**
Add all [terms](@) that are described by a [curated texts](@) in the [current scope](@).
  -- **`* @`**
Add all [terms](@) that have an [MRG entry](@) in the [MRG](@) as [identified](@) by the [terminology-identifier](@) ``. This [MRG](@) must have been made available in the [glossarydir](@) of the [current scope](@). +- **`* @`**
Add all [terms](@) that have an [MRG entry](@) in the [MRG](@) as identified by the [terminology identifier](@) ``. This [MRG](@) must have been made available in the [glossarydir](@) of the [current scope](@).
Examples: @@ -133,7 +133,7 @@ The following syntaxes are available for adding a selection of terms from a spec - `` is a text that corresponds with a field name in a [header](@) (front-matter) of a [curated text](@), such as `term`, `grouptags`, `status`, etc. - ``, ``, ... are texts that are used to determine whether or not a [curated text](@) is to be selected for inclusion in the [provisional MRG](@).
  - **`` [ ``, ``, ... ] `@`**, where: - - `` is a [terminology identifier](@) that [identifies](@) an [MRG](@) (that must have been made available in the [glossarydir](@) of the [current scope](@)). + - `` is a [terminology identifier](@) that identifies an [MRG](@) (that must have been made available in the [glossarydir](@) of the [current scope](@)). - `` is a text that corresponds with a field name in an [MRG entry](@) that resides in that [MRG](@), such as `term`, `grouptags`, `status`, etc. - ``, ``, ... are texts that are used to determine whether or not an [MRG entry](@) from that [MRG](@) is to be selected for inclusion in the [provisional MRG](@). @@ -196,7 +196,7 @@ In analogy with [namespaces](https://en.wikipedia.org/wiki/Namespace), we accomm The following syntaxes are available for renaming fields in an [MRG entry](@) that is part of the [provisional MRG](@): - **`rename` `` [ ``:``, `:`, ... ]**, where: - - `` is the value of the `term` field in the [MRG entry](@) of the [provisional MRG](@) that is selected for the renaming process, which may optionally be preceded with `:` (where `` would then be the value of the `termType` field in that [MRG entry](@)). Note that this value is an [identifier](@) for that [MRG entry](@). + - `` is the value of the `term` field in the [MRG entry](@) of the [provisional MRG](@) that is selected for the renaming process, which may optionally be preceded with `:` (where `` would then be the value of the `termType` field in that [MRG entry](@)). Note that this value is an identifier for that [MRG entry](@). - `` is a text that corresponds with a field name in an [MRG entry](@) in the [provisional MRG](@), such as `formPhrases`, `glossaryText`, `grouptags`, `status`, etc. - `` is a text that will replace the existing text of the field identified by ``. If the text contains multiple words, it is advised to surround it with quotes. diff --git a/docs/overview/00-tev2-common-understanding.md b/docs/overview/00-tev2-common-understanding.md index a940665ee4..a91efad5d3 100644 --- a/docs/overview/00-tev2-common-understanding.md +++ b/docs/overview/00-tev2-common-understanding.md @@ -13,7 +13,7 @@ export const mark = ({children}) => ( {children} ); -In order for a [community](@) (e.g. a workgroup, taskforce, project/product team, department, etc.) to realize its [objectives](@), it is beneficial that its members have a common set of the ideas, [concepts](@) and other [semantic units](@) that are relevant for realizing these [objectives](@). The ability to realize such a common understanding, and to demonstrate that this is actually the case, is a critical capability for success. +In order for a [community](@) (e.g. a workgroup, taskforce, project/product team, department, etc.) to realize its [objectives](@essif-lab), it is beneficial that its members have a common set of the ideas, [concepts](@) and other [semantic units](@) that are relevant for realizing these [objectives](@essif-lab). The ability to realize such a common understanding, and to demonstrate that this is actually the case, is a critical capability for success. The Terminology Engine (v2) is a set of specifications and tools that (technically) facilitate such capabilities, by recognizing that each [community](@) wants (and needs): diff --git a/docs/saf.yaml b/docs/saf.yaml index 005389c5fc..48b7e25bad 100644 --- a/docs/saf.yaml +++ b/docs/saf.yaml @@ -49,13 +49,8 @@ versions: termselection: - "[action]@essif-lab" - "rename action [id:act, term:act, formPhrases:'act{ss}']" - - "[party,actor,onboarding,action,organization,community,entity,legal-entity]@essif-lab" - - "[ssi,assertion,claim,credential,issue,verify,validate,transaction]@essif-lab" - - "[manage,management,governance,risk,owner,owned]@essif-lab" - - "[jurisdiction,objective,control,expectation,obligation]@essif-lab" - - "[control-objective,risk-objective,compliance-objective]@essif-lab" - - "[identity,partial-identity,identifier,identify,identification]@essif-lab" - - "[concept,relation,property,semantic-unit,terminology,vocabulary,knowledge]@essif-lab" + - "[action]@essif-lab" + - "[party,actor,organization,community,entity,legal-entity]@essif-lab" - "*" # import all tev2 terms. # - "termType[concept,acronym,abbreviation]" # import all of our own stuff (except patterns) - "-excludeFromMRG[yes]" # exclude all curated texts whose `excludeFromMRG` field contains `yes` diff --git a/docs/specs/files/10-curated-text-file.md b/docs/specs/files/10-curated-text-file.md index 9b0f118d70..4a3075c56c 100644 --- a/docs/specs/files/10-curated-text-file.md +++ b/docs/specs/files/10-curated-text-file.md @@ -87,13 +87,13 @@ Different [TEv2 tools](@) use header fields in [headers](@) for various purposes | Name | Req'd | Description | | --------------- | :---: | ----------- | -| `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`. If not specified, its value defaults to the `defaulttype`-field in the [scope section](/docs/specs/files/saf#scope-section) of the [SAF](@). | +| `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`. If not specified, its value defaults to the `defaulttype`-field in the [scope section](/docs/specs/files/saf#scope-section) of the [SAF](@). | | `term` | Y | text that is used to refer to the [semantic unit](@) that is documented by this [curated text](@). | -| `isa` | n | [Term identifier](@) that [identifies](@) the [semantic unit](@) of which this is a specialization. | +| `isa` | n | [Term identifier](@) that identifies the [semantic unit](@) of which this is a specialization. | | `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](@). | +| `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.
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 [specifying form phrases](form-phrase#specifying@). | | `status` | n | Text that identifies the status of the term. ([Communities](@) of) [scopes](@) may specify values for this field. An example is the [status tags used by ToIP](https://github.com/trustoverip/concepts-and-terminology-wg/blob/master/docs/status-tags.md). | diff --git a/docs/specs/files/12-saf.md b/docs/specs/files/12-saf.md index c09fe097c5..d899f4177f 100644 --- a/docs/specs/files/12-saf.md +++ b/docs/specs/files/12-saf.md @@ -64,7 +64,7 @@ The following fields are defined for the `scope` section of a [SAF](@): | `scopedir` | Y | URL of the location of the [scopedir](@) associated with the [scopetags](@) listed in the `scopetags` field. | | `curatedir` | Y | Path to the directory where all [curated files](@) are located. This directory may contain subdirectories to allow [curators](@) to organize the files in any way they see fit. Full URL is ``/``. `curatedir` may also be an empty string. | | `glossarydir` | Y | Path to the directory where all [glossary](@)-related files are located. Full URL is ``/``. This directory SHOULD contain one [MRG](@) for every element in the version-section in the [SAF](@). It MAY contain other files, e.g. [HRGs](@) or [HRG](@) templates, files that contain instructions, headers, footers or other things that are necessary for generating specific [glossaries](@). | -| `defaultvsn` | Y | [versiontag](@) that [identifies](@) the default [terminology](@) for this [scope](@). The associated [MRG](@) is located at `scopedir`/`glossarydir`/mrg.`scopetag`.`defaultvsn`.yaml | +| `defaultvsn` | Y | [versiontag](@) that identifies the default [terminology](@) for this [scope](@). The associated [MRG](@) is located at `scopedir`/`glossarydir`/mrg.`scopetag`.`defaultvsn`.yaml | | `defaulttype` | n | Text that is used to identify the default kind of [semantic unit](@) for a [curated text](@). It is the default value for the `termType`-field in [curated texts](@). Default value for `defaulttype` is `concept`. | | `website` | n | Base URL for creating links to rendered versions of [Curated Texts](@). It should also serve as the home page of the [terminology](@). If not specified, it is assumed to be the empty string. | | `navpath` | n | Path to the directory where [Curated Texts](@) are rendered, relative to the value of `website`. What `curatedir` is for [Curated Texts](@), is `navpath` for the rendered versions of [Curated Texts](@). If not specified, it is assumed to be the empty string. | @@ -121,7 +121,7 @@ It may be simpler to change the `scopetags`-field, which is currently a list of ### SAF Versions - Enabling changes and updates in a scope's Terminology {#versions} -The third section (called `versions`) in the [SAF](@) specifies the [terminologies](@) that are actively maintained by the [curators](@) of the [scope](@). Each such [terminology](@) is [identified](@) (within that [scope](@)) by a (main) [versiontag](@) and optionally also alternative [versiontags](@). The contents of a [terminology](@) is specified by so-called [term selection instructions](@). See the [Terminology Construction page](/docs/manuals/curator/terminology-construction) and the [term selection syntax page](/docs/specs/syntax/term-selection) for details. +The third section (called `versions`) in the [SAF](@) specifies the [terminologies](@) that are actively maintained by the [curators](@) of the [scope](@). Each such [terminology](@) is identified (within that [scope](@)) by a (main) [versiontag](@) and optionally also alternative [versiontags](@). The contents of a [terminology](@) is specified by so-called [term selection instructions](@). See the [Terminology Construction page](/docs/manuals/curator/terminology-construction) and the [term selection syntax page](/docs/specs/syntax/term-selection) for details. This `versions` section contains a list of fields that each specify one [terminology](@) and some meta-data, e.g., regarding the state/validity of the [terminology](@) over time. This may be of interest to the [curators](@) of other [scopes](@) as they need to decide whether or not to import [terms](@) from such a [terminology](@). @@ -171,11 +171,11 @@ The following fields are defined for the `versions` section of a [SAF](@): | Name | Req'd | Description | | ------------- | :---: | ----------- | -| `vsntag` | Y | [Versiontag](@) that that is used to [identify](@) this version within the set of all other versions that are maintained within this [scope](@). in this [SAF](@). It MUST NOT be changed during the lifetime of this version. | +| `vsntag` | Y | [Versiontag](@) that that is used to identify this version within the set of all other versions that are maintained within this [scope](@). in this [SAF](@). It MUST NOT be changed during the lifetime of this version. | | `altvsntags` | n | List of alternative [versiontags](@) that may be used to refer to this version of the [scope's](@) [terminology](@). A typical use of this field would be to tag a version as the 'latest' version. | | `termselection` | Y | List of [term selection instructions](@) that are used to generate (this version of) the [scope's](@) [terminology](@). See the [Terminology Construction page](/docs/manuals/curator/terminology-construction) and the [term selection syntax page](/docs/specs/syntax/term-selection) for details. | | `license` | n | File that contains the (default) licensing conditions. Full URL is `scopedir`/`license`. If not specified, its value defaults to the value of the `license` field in the `scope` section (of this [SAF](@)). The purpose of this field is to allow different versions of the [scope's](@) [terminology](@) to have different licenses. | -| `status` | n | Text that [identifies](@) the status of the [term](@). ([Communities](@) of) [scopes](@) may specify values for this field. If not specified, the status SHOULD be assumed to be 'concept', 'draft', 'proposed', or similar. An example is the [status tags used by ToIP](https://github.com/trustoverip/concepts-and-terminology-wg/blob/master/docs/status-tags.md). | +| `status` | n | Text that identifies the status of the [term](@). ([Communities](@) of) [scopes](@) may specify values for this field. If not specified, the status SHOULD be assumed to be 'concept', 'draft', 'proposed', or similar. An example is the [status tags used by ToIP](https://github.com/trustoverip/concepts-and-terminology-wg/blob/master/docs/status-tags.md). | | `from` | F | Date at which it was decided to establish this version. | | `to` | F | Date at which this version will expire (or has expired). | diff --git a/docs/specs/files/32-mrg.md b/docs/specs/files/32-mrg.md index 0d6bc4a86f..9f84c06040 100644 --- a/docs/specs/files/32-mrg.md +++ b/docs/specs/files/32-mrg.md @@ -28,8 +28,8 @@ Within this [glossarydir](@) we can generate (or import), and hence also find al - **`mrg...yaml`** is the name of a file that contains an actual [MRG](@), or it is a file that links (references) such a file, where: - - **``** is the [scopetag](@) that [identifies](@) the [scope](@) in which the [MRG](@) is curated, as specified in the [SAF](@) of the [scope](@) we are in. Thus, its value must either be that of the `scopetag`-field in the [`scope`-section](docs/specs/files/saf#scope-section) of the [SAF](@), or it must be one of the values in the `scopetags`-field in the [scopes (plural) section](docs/specs/files/saf#scopes) of that [SAF](@). - - **``** is the [versiontag](@) that [identifies](@) the version of the [terminology](@) for which the [MRG](@) contains [entries](mrg-entry@). Its value must be either one of the `vsntag`-fields, or appear in one of the `altvsntag`-fields in the [`versions` section](/docs/specs/files/saf#versions) of the [SAF](@). + - **``** is the [scopetag](@) that identifies the [scope](@) in which the [MRG](@) is curated, as specified in the [SAF](@) of the [scope](@) we are in. Thus, its value must either be that of the `scopetag`-field in the [`scope`-section](docs/specs/files/saf#scope-section) of the [SAF](@), or it must be one of the values in the `scopetags`-field in the [scopes (plural) section](docs/specs/files/saf#scopes) of that [SAF](@). + - **``** is the [versiontag](@) that identifies the version of the [terminology](@) for which the [MRG](@) contains [entries](mrg-entry@). Its value must be either one of the `vsntag`-fields, or appear in one of the `altvsntag`-fields in the [`versions` section](/docs/specs/files/saf#versions) of the [SAF](@). - **`mrg..yaml`** is a copy of the file `mrg...yaml`, where `` is the value of `defaultvsn`-field in the [`scope`-section](docs/specs/files/saf#scope-section) of the [SAF](@). @@ -87,7 +87,7 @@ The following fields are defined for the sections `terminology`: | `scopedir` | Y | URL that locates the [scope directory](@) associated with that [scope](@). | | `curatedir` | Y | Path to the directory where all [curated files](@) are located. This directory may contain subdirectories to allow [curators](@) to organize the files in any way they see fit. Full URL is ``/``.| | `vsntag` | Y | [versiontag](@) by which the [terminology](@) of this [MRG](@) can be distinguished from the other versions of the [terminology](@) (in other [MRGs](@)). Its value MUST match the `vsntag` field of the corresponding `versions` section in the [SAF](@) | -| `altvsntags` | n | List of alternative [versiontags](@) that can be used to [identify](@) this version. Each of the values MUST be in the list of [versiontags](@) in the `altvsntags` field of the the corresponding `versions` section in the [SAF](@). | +| `altvsntags` | n | List of alternative [versiontags](@) that can be used to identify this version. Each of the values MUST be in the list of [versiontags](@) in the `altvsntags` field of the the corresponding `versions` section in the [SAF](@). | | `license` | n | File that contains the (default) licensing conditions. Full URL is `scopedir`/`license`. Its value MUST match the `license` field of the corresponding `versions` section in the [SAF](@), or if that isn't specified, the `license` field of the `scope` section in the [SAF](@). | ```mdx-code-block @@ -116,7 +116,7 @@ The following fields are defined for the section `scopes`: The `entries` section of an [MRG](@) is a list of [MRG entries](@), the purpose of which is that the various tools can find all data that is relevant for the purpose that such a tool serves. -This `entries` section documents the [terminology](@) that is [identified] by each of the [versiontags](@) in either the `vsntag` field or the `altvsntag` field in the `terminology` section of the [MRG](@). +This `entries` section documents the [terminology](@) that is identified by each of the [versiontags](@) in either the `vsntag` field or the `altvsntag` field in the `terminology` section of the [MRG](@). An [MRG entry](@) has a few fields that are always present, because they are either required as a part of the [header](@) of [curated texts](@), or generated by the [MRGT](@), as follows: @@ -126,11 +126,11 @@ An [MRG entry](@) has a few fields that are always present, because they are eit | Field | Value(s) that are assigned to the fields | | -------------- | :---------- | -| `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. | +| `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. | +| `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](@). | @@ -169,18 +169,18 @@ The following table documents the fields that are used within the context of [TE | 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. | +| `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`. | +| `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](@). | +| `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.
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] | diff --git a/docs/specs/syntax/10-term-refs.md b/docs/specs/syntax/10-term-refs.md index df4239e7f2..08356fc213 100644 --- a/docs/specs/syntax/10-term-refs.md +++ b/docs/specs/syntax/10-term-refs.md @@ -43,7 +43,7 @@ where: - `termType` (optional) is a [term type](@). When not specified, it is given the default type for [semantic units](@) in the [current scope](@), which usually would be `concept`. - `term` (optional) is a [term](@). If not specified, its value is constructed based on the value of `showtext`, as specified in the [TRRT](trrt#id@). - `trait` (optional) refers to a particular characteristic of the [semantic unit](@). If specified, it must be the [heading id](https://www.markdownguide.org/extended-syntax/#heading-ids) of the section in the [body](@) of a [curated text](@) that describes the characteristic. If not specified it refers to the whole of (the documentation of) the [semantic unit](@). -- `terminology-identifier` is a [terminology-identifier](@). If not specified, its value is taken to be the default [terminology](@) of the [current scope](@). +- `terminology-identifier` is a [terminology identifier](@). If not specified, its value is taken to be the default [terminology](@) of the [current scope](@). ### Examples @@ -59,7 +59,7 @@ This [TermRef](@) refers to the [semantic unit](@) that is identified by the [te The par - that [identifies](@) the [terminology](@) in which `termid` [identifies](@) a [semantic unit](@). + that identifies the [terminology](@) in which `termid` identifies a [semantic unit](@). Here is an example of a [TermRef](@): `[definitions](definition@)`. When this text is rendered into a human readable form, it will show the text `definitions` (plural) enhanced, and it will link to the text that describes (or defines) the term `definition` (singular). If you would want to use this term as it is defined in the [scope](@) called `essif-lab`, you could do that by writing `[definitions](definition@essif-lab)` (provided that `essif-lab` is a defined [scopetag](@) within the [scope](@) that you operate in). diff --git a/docs/specs/syntax/21-term-identifiers.md b/docs/specs/syntax/21-term-identifiers.md index 8f58c93e27..5426d280cf 100644 --- a/docs/specs/syntax/21-term-identifiers.md +++ b/docs/specs/syntax/21-term-identifiers.md @@ -5,9 +5,9 @@ date: 20230915 --- # Term Identifier -A **Term Identifier** is a [text](identifier@) that is used for [identifying](@) a [semantic unit](@) within a designated [terminology](@). This means that it can be used for selecting an [MRG entry](@) that exists in the [MRG](@) associated with that [terminology](@). It does NOT mean that any such text will actually [identify](@) such an [MRG entry](@). [Term identifiers](@) can be ambiguous (refer to multiple [MRG entries](@)). It is also possible that a [term identifier](@) does not [identify](@) any such [MRG entry](@). +A **Term Identifier** is a [text](identifier@) that is used for identifying a [semantic unit](@) within a designated [terminology](@). This means that it can be used for selecting an [MRG entry](@) that exists in the [MRG](@) associated with that [terminology](@). It does NOT mean that any such text will actually identify such an [MRG entry](@). [Term identifiers](@) can be ambiguous (refer to multiple [MRG entries](@)). It is also possible that a [term identifier](@) does not identify any such [MRG entry](@). -Similarly, [term identifiers](@) can be used for [identifying](@) the [curated text](@) that describes the [semantic unit](@) within a designated [terminology](@). Here, too, [term identifiers](@) exist that are ambiguous, or do not refer to any [curated text](@). +Similarly, [term identifiers](@) can be used for identifying the [curated text](@) that describes the [semantic unit](@) within a designated [terminology](@). Here, too, [term identifiers](@) exist that are ambiguous, or do not refer to any [curated text](@). ## Syntax @@ -24,9 +24,9 @@ where | Name | Req'd | Description | | --------- | :---: | :---------- | | `term` | Y | is a text that is used to refer to a [semantic unit](@) within the designated [terminology](@). It either appears in the (required) `term`-field of [curated texts](@) and [MRG entries](@), or it is one of the [form phrases](@) by which the [semantic unit](@) is referred to. | -| `termType` | n | specifies the [kind of semantic unit](term-type@) that is to be [identified](@). Typical values are `concept`, `relation`, `pattern` (or `mental-model`), or `use-case`.
If not specified, the `:` (in front of the `term`) MUST NOT be present, and its value defaults to that of the `defaulttype`-field in the [scope section](/docs/specs/files/saf#scope-section) of the [SAF](@). | -| `scopetag` | n | is the [scopetag](@) that [identifies](@) the [scope](@) of the [terminology](@).
If `scopetag` is omitted, the [scope](@) defaults to the current [scope](@). | -| `vsntag` | n | is the [versiontag](@) that [identifies](@) the version of the [terminology](@) to be used.
If not specified, the `:` preceding the `vsntag` MUST NOT be present, and its value defaults to the default version of the [terminology](@), as specified in the `defaultvsn` field in the [`scope`-section](/docs/specs/files/saf#scope-section) of the [SAF](@) of the [scope](@) in which the [terminology](@) is maintained. | +| `termType` | n | specifies the [kind of semantic unit](term-type@) that is to be identified. Typical values are `concept`, `relation`, `pattern` (or `mental-model`), or `use-case`.
If not specified, the `:` (in front of the `term`) MUST NOT be present, and its value defaults to that of the `defaulttype`-field in the [scope section](/docs/specs/files/saf#scope-section) of the [SAF](@). | +| `scopetag` | n | is the [scopetag](@) that identifies the [scope](@) of the [terminology](@).
If `scopetag` is omitted, the [scope](@) defaults to the current [scope](@). | +| `vsntag` | n | is the [versiontag](@) that identifies the version of the [terminology](@) to be used.
If not specified, the `:` preceding the `vsntag` MUST NOT be present, and its value defaults to the default version of the [terminology](@), as specified in the `defaultvsn` field in the [`scope`-section](/docs/specs/files/saf#scope-section) of the [SAF](@) of the [scope](@) in which the [terminology](@) is maintained. | ```mdx-code-block @@ -37,11 +37,11 @@ where
Assumptions regarding the default values for optional parts -- `tev2` is a [scopetag](@) that [identifies](@) the [scope](@) in which the [TEv2](@) [terminology](@) is being [curated](@). +- `tev2` is a [scopetag](@) that identifies the [scope](@) in which the [TEv2](@) [terminology](@) is being [curated](@). - the default kind of [semantic unit](@) documented within `tev2` is `concept`. -- `terms` is a [vsntag](@) that [identifies](@) the [terminology](@) within `tev2` that consists of all [terms](@) that are [defined](@) within `tev2`. +- `terms` is a [vsntag](@) that identifies the [terminology](@) within `tev2` that consists of all [terms](@) that are [defined](@) within `tev2`. - `terms` is the [vsntag](@) for the default [terminology](@) of `tev2`. -- `myscope` is a [scopetag](@) that [identifies](@) the current [scope](@). +- `myscope` is a [scopetag](@) that identifies the current [scope](@). - `latest` is the [vsntag](@) for the default [terminology](@) of `myscope`. - the default kind of [semantic unit](@) documented within `myscope` is `use-case`. @@ -60,7 +60,7 @@ where This section describes how this dereferencing process works, i.e., how the [MRG entry](@) that corresponds to a [term identifier](@) can be found (if it exists). -1. First, the [term identifier](@) is split at the `@`-sign, where the part behind the `@`-sign is a [terminology identifier](@) that [identifies](@) the [terminology](@) and hence the [MRG](@) that contains all [MRG entries](@) thereof. This set of [MRG entries](@) is what we start out with. +1. First, the [term identifier](@) is split at the `@`-sign, where the part behind the `@`-sign is a [terminology identifier](@) that identifies the [terminology](@) and hence the [MRG](@) that contains all [MRG entries](@) thereof. This set of [MRG entries](@) is what we start out with. 2. Then, the part in front of the `@`-sign is processed, as follows: 1. we only keep [MRG entries](@) whose `term` field equals the value specified by `term`;[^3] @@ -69,7 +69,7 @@ This section describes how this dereferencing process works, i.e., how the [MRG 3. Now we're done with selecting. In case the number of elements in the set of [MRG entries](@) is - 0: the [term identifier](@) cannot be resolved; there is no matching [semantic unit](@). - - 1: one [semantic unit](@) is [identified](@); it is described by the selected [MRG entry](@); + - 1: one [semantic unit](@) is identified; it is described by the selected [MRG entry](@); - 2: the [term identifier](@) is ambiguous, i.e., or more than one [semantic units](@) are a match. This can occur when there are 2 or more [MRG entries](@) that both have the same `term`-field, and each of them has a `termType` field that is not the default `termType` for its that [scope](@), and the [term identifier](@) did not contain a specification for the `termType` [^3]: in some cases, this step works a bit different: first the `term` field is [regularized](@); then all [MRG entries](@) are kept that have this result as one of the elements in its `formPhrases` field. \ No newline at end of file diff --git a/docs/specs/syntax/31-terminology-identifiers.md b/docs/specs/syntax/31-terminology-identifiers.md index f895480d78..1687fcc47f 100644 --- a/docs/specs/syntax/31-terminology-identifiers.md +++ b/docs/specs/syntax/31-terminology-identifiers.md @@ -6,7 +6,7 @@ date: 20230929 # Terminology Identifiers -A **Terminology Identifier** a [text](identifier@) that [identifies](@) a [terminology](@) from within a particular [scope](@), and can also be used to find the [MRG](@) file (in the [glossarydir](@) of that same [scope](@)) that contains [entries](mrg-entry@) for every [term](@) contained in that [terminology](@). +A **Terminology Identifier** a [text](identifier@) that identifies a [terminology](@) from within a particular [scope](@), and can also be used to find the [MRG](@) file (in the [glossarydir](@) of that same [scope](@)) that contains [entries](mrg-entry@) for every [term](@) contained in that [terminology](@). ## Syntax @@ -19,13 +19,13 @@ The syntaxes that can be used for a [terminology identifier](@) are as follows ( where -- the empty string (null) [identifies](@) the [terminology](@) that is being used by default in the context in which the [terminology identifier](@) is being used. Typically, that would be the default version of the [terminology](@) in the current [scope](@). [^1] +- the empty string (null) identifies the [terminology](@) that is being used by default in the context in which the [terminology identifier](@) is being used. Typically, that would be the default version of the [terminology](@) in the current [scope](@). [^1] -[^1]: When a [terminology](@) is being constructed, the empty string [identifies](@) the [terminology that is under construction](provisional MRG)(@). +[^1]: When a [terminology](@) is being constructed, the empty string identifies the [terminology that is under construction](provisional MRG)(@). -- **`scopetag`** is a [scopetag](@) that [identifies](@) the [scope](@) of the [terminology](@). If `scopetag` is omitted, the [scope](@) defaults to the current [scope](@). +- **`scopetag`** is a [scopetag](@) that identifies the [scope](@) of the [terminology](@). If `scopetag` is omitted, the [scope](@) defaults to the current [scope](@). -- **`vsntag`** is a [versiontag](@) that [identifies](@) the version of the [terminology](@) to be used. If `:vsntag` (including the `:`) is omitted, the default version of the [terminology](@) is assumed, as specified in the `defaultvsn` field in the [`scope`-section](/docs/specs/files/saf#scope-section) of the [SAF](@) of the [scope](@) in which the [terminology](@) is maintained. +- **`vsntag`** is a [versiontag](@) that identifies the version of the [terminology](@) to be used. If `:vsntag` (including the `:`) is omitted, the default version of the [terminology](@) is assumed, as specified in the `defaultvsn` field in the [`scope`-section](/docs/specs/files/saf#scope-section) of the [SAF](@) of the [scope](@) in which the [terminology](@) is maintained. ## Finding the [MRG](@) that corresponds with a [Terminology Identifier](@) @@ -39,9 +39,9 @@ Since all [MRGs](@) follow the [MRG naming conventions](/docs/specs/files/mrg#fi In the following examples, we assume that -- `tev2` is a [scopetag](@) that [identifies](@) the [scope](@) in which the [TEv2](@) [terminology](@) is being [curated](@). -- `terms` is a [vsntag](@) that [identifies](@) the [terminology](@) that consists of all [terms](@) that are [defined](@) within the [scope](@) identified by `tev2`. -- `myscope` is a [scopetag](@) that [identifies](@) the current [scope](@). +- `tev2` is a [scopetag](@) that identifies the [scope](@) in which the [TEv2](@) [terminology](@) is being [curated](@). +- `terms` is a [vsntag](@) that identifies the [terminology](@) that consists of all [terms](@) that are [defined](@) within the [scope](@) identified by `tev2`. +- `myscope` is a [scopetag](@) that identifies the current [scope](@). | terminology-identifier | refers to | | :--------------------- | :-------- | diff --git a/docs/specs/syntax/41-mrg-refs.md b/docs/specs/syntax/41-mrg-refs.md index 4a21fb8403..f902e7c090 100644 --- a/docs/specs/syntax/41-mrg-refs.md +++ b/docs/specs/syntax/41-mrg-refs.md @@ -143,7 +143,7 @@ Under the assumption that the [terminology identifier](@) `tev2` refers to a [te | Term | Description | | :--- | :---------- | | Glossary | an alphabetically sorted list of [terms](@) with the (single) meaning it has in (at least) one context. | -| Curator (of a Scope) | a person responsible for curating, managing, and maintaining the [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@). | +| Curator (of a Scope) | a person responsible for curating, managing, and maintaining the [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@essif-lab). | | Definition | the combination of a [term](@) and a descriptive text, where the [term](@) refers to a [concept](@) or other [semantic unit](@), and the descriptive text enables a set of [parties](@) to have the same understanding about that [concept](@). Ideally, the descriptive text is a criterion that such [parties](@) can use to determine what is, and what is not, an instance (or example) of that [concept](@). | --- ~~~ @@ -223,7 +223,7 @@ an alphabetically sorted list of [terms](@) with the (single) meaning it has in ### [Curator (of a Scope)](/docs/terms/curator) -a person responsible for curating, managing, and maintaining the [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@). +a person responsible for curating, managing, and maintaining the [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@essif-lab). ### [Definition](/docs/terms/definition) diff --git a/docs/specs/syntax/62-term-selection.md b/docs/specs/syntax/62-term-selection.md index f3f5b27f35..0b809be1ac 100644 --- a/docs/specs/syntax/62-term-selection.md +++ b/docs/specs/syntax/62-term-selection.md @@ -40,7 +40,7 @@ Take care to properly nest quotes (as in the 'rename' instruction of the example | Instruction | Description | | ----------- | ----------- | -| `` | a [terminology identifier](@) that [identifies](@) the [terminology](@) that the [MRGT](@) will use as its source. | +| `` | a [terminology identifier](@) that identifies the [terminology](@) that the [MRGT](@) will use as its source. | | ``, `` | a [formphrase](@) (for a particular [term](@)). | | `` | the name of a field in the [header](@) of a [curated text](@), or in an [MRG entry](@) of the [MRG](@), whichever the [MRGT](@) uses as its source. | | ``, `` | a text value. | @@ -56,7 +56,7 @@ Take care to properly nest quotes (as in the 'rename' instruction of the example [^1]: 'matching' means that [TBD: specify the matching algorithm, in particular when the field itself is an arry, such as `grouptags`, `headingids`, etc.] :::tip Adding terms from other scopes -By adding `@` to any of the above instructions, you specify that the [MRG entries](@) that are to be selected must originate from the [terminology](@) that the [terminology identifier](@) `` [identifies](@). +By adding `@` to any of the above instructions, you specify that the [MRG entries](@) that are to be selected must originate from the [terminology](@) that the [terminology identifier](@) `` identifies. The instruction `"[ party, actor ]@essif-lab"` will copy all [MRG entries](@) from the (default version) of the [MRG] as it exists in the [scope](@) `essif-lab`. Of course, `essif-lab` must be defined as a [scopetag](@) in one of the entries of the [scopes section](/docs/specs/files/saf#scopes) of the [SAF](@). ::: @@ -70,8 +70,8 @@ The instruction `"[ party, actor ]@essif-lab"` will copy all [MRG entries](@) fr | "term [actor]" | select every [curated text](@) in the [current scope](@), of which the `term` field in its [header](@) has the value `actor`. | | "status[proposed,approved]" | select every [curated text](@) in the [current scope](@), of which the `status` field in its [header](@) has the value `proposed` or `approved`. | | "somefield []" | select every [curated text](@) in the [current scope](@), of which the `somefield` field in its [header](@) has no value specified. | - | "[actor,party]@tev2:v1" | select every [MRG entry](@) in the [terminology](@) [identified](@) by `@tev2:v1`, that [matches](form-phrase#matching@) any of the [form phrases](@) `actor` or `party`. | - | "term [actor,party]@tev2:v1" | select every [MRG entry](@) in the [terminology](@) [identified](@) by `@tev2:v1`, of which the `term` field has the value `actor` or `party`. | + | "[actor,party]@tev2:v1" | select every [MRG entry](@) in the [terminology](@) identified by `@tev2:v1`, that [matches](form-phrase#matching@) any of the [form phrases](@) `actor` or `party`. | + | "term [actor,party]@tev2:v1" | select every [MRG entry](@) in the [terminology](@) identified by `@tev2:v1`, of which the `term` field has the value `actor` or `party`. | | "grouptags[x,y,z]@essif-lab" | select every [MRG entry](@) in the default [terminology](@) of [scope](@) `essif-lab`, of which the `grouptags` field contains one or more of the values `x`, `y`, or `z`. |
@@ -120,7 +120,7 @@ The following syntaxes are available for renaming fields in a [provisional MRG e | Instruction | Description | | ----------- | ----------- | -| `` | is the value of the `term` field in the [MRG entry](@) of the [provisional MRG](@) that is selected for the renaming process, which may optionally be preceded with `:` (where `` would then be the value of the `termType` field in that [MRG entry](@)). Note that this value is an [identifier](@) for that [MRG entry](@). | +| `` | is the value of the `term` field in the [MRG entry](@) of the [provisional MRG](@) that is selected for the renaming process, which may optionally be preceded with `:` (where `` would then be the value of the `termType` field in that [MRG entry](@)). Note that this value is an identifier for that [MRG entry](@). | | `>` | a text that corresponds with a field name in an [MRG entry](@) in the [provisional MRG](@), such as `formPhrases`, `glossaryText`, `grouptags`, `status`, etc. | | `>` | a text that will replace the existing text of the field identified by `>`. If the text contains multiple words, it should be surrounded with quotes. | @@ -128,7 +128,7 @@ The following syntaxes are available for renaming fields in a [provisional MRG e | Instruction | Description | | ----------- | ----------- | -| `"rename [ :, :, ... ]"` | In the [MRG entry](@) that is [identified](@) by `` in the [provisional MRG](@), the values of the fields `k` are replaced by their corresponding values `v` (also if `v` is the empty string) | +| `"rename [ :, :, ... ]"` | In the [MRG entry](@) that is identified by `` in the [provisional MRG](@), the values of the fields `k` are replaced by their corresponding values `v` (also if `v` is the empty string) | Here is how it works. First, the [provisional MRG Entry](@) is searched that has a `term` field whose value is ``. If found, all ``:`` pairs are processed in the sequence they are specified. Processing a ``:`` pair consists of looking for a field named `` in the selected [MRG entry](@). We now have the following situations: diff --git a/docs/specs/tools-envisaged/11-ict.md b/docs/specs/tools-envisaged/11-ict.md index 60047c76f5..f4427db291 100644 --- a/docs/specs/tools-envisaged/11-ict.md +++ b/docs/specs/tools-envisaged/11-ict.md @@ -132,7 +132,7 @@ The columns in the following table are defined as follows: | `scopedir` | `` | Y | * | Path to the [scopedir](@) within which the tool is to operate, i.e.: _this scopedir_. | | `syntax` | | n | * | This argument has no value. If present, the syntax of all (YAML) fields in the file is checked against their specifications (see e.g. [SAF specs](docs/specs/files/saf), [Curated Texts](/docs/specs/files/curated-text-file), [TermRefs](/docs/specs/syntax/term-refs)), etc., etc. | | `vsntag` | `` | | `-mrg` | [versiontag](@) that is used to select the version of the [MRG](@) to be checked. The [MRG](@) that is selected will either have `` as the contents of the field `terminology.vsntag`, or as an element in the list of `terminology.altvsntags`. | -| `term` | `` | n | -txt | [term](@) that [identifies](@) a particular [curated file](@). The [curated file](@), whose (front-matter) field `term` matches this parameter, will be integrity-checked. | +| `term` | `` | n | -txt | [term](@) that identifies a particular [curated file](@). The [curated file](@), whose (front-matter) field `term` matches this parameter, will be integrity-checked. | | `grouptags` | `` | n | -txt | List of [grouptags](@). Every [curated file](@), whose (front-matter) field `grouptags` has an element that also appears as an element in the `` list, will be integrity-checked. | ## Integrity Checks diff --git a/docs/specs/tools/12-trrt.md b/docs/specs/tools/12-trrt.md index 6654002b90..8a2c59ac52 100644 --- a/docs/specs/tools/12-trrt.md +++ b/docs/specs/tools/12-trrt.md @@ -199,8 +199,8 @@ The [interpreter profile](@) of the [TRRT](@) consist of the following [named ca | `type` | n | The [term type](@) of the [semantic unit](@) that is referred to. | | `term` | n | The [term](@) of the [semantic unit](@) that is referred to. | | `trait` | n | A text that is expected to correspond with one of the `headingids` in the [MRG entry](@) of the [semantic unit](@) that is referred to. | -| `scopetag` | n | The [scopetag](@) that [identifies](@) the [scope](@) that [curates](@) the [semantic unit](@) that is referred to. | -| `vsntag` | n | A [versiontag](@) that [identifies](@) the [terminology](@) that contains the [semantic unit](@) that is referred to. | +| `scopetag` | n | The [scopetag](@) that identifies the [scope](@) that [curates](@) the [semantic unit](@) that is referred to. | +| `vsntag` | n | A [versiontag](@) that identifies the [terminology](@) that contains the [semantic unit](@) that is referred to. | :::info Note that the values of these specified [capturing groups](@) will be [regularized](regularize@) before they are used for [processing](#processing). @@ -218,7 +218,7 @@ The most general form of the `default` [interpreter](@) syntax is: where: - `show text` (required) is the text that will be highlighted/emphasized to indicate it is linked. It must not contain the characters `@` or `]` (this is needed to distinguish [TermRefs](@) from regular [markdown links](https://www.markdownguide.org/basic-syntax/#links)). -- `termType` (optional) is a [term type](@). It need not be specified if the `term` field is (already) a unique [identifier](@) for the [semantic unit](@) that is being refered to. +- `termType` (optional) is a [term type](@). It need not be specified if the `term` field is (already) a unique identifier for the [semantic unit](@) that is being refered to. - `term` (optional) is a [term](@). It need not be specified if the [term](@) can be derived from the `showtext`, as specified in the section on [Finding an MRG Entry](#finding-mrg-entry) (bullet 2.ii). - `trait` (optional) refers to a particular characteristic of the [semantic unit](@). It need not be specified if the reference is not to a particular characteristic. If it is specified, it must be a [heading id](https://www.markdownguide.org/extended-syntax/#heading-ids) of the section in the [body](@) of a [curated text](@) that describes the characteristic. - `scopetag`:`vsntag` (optional) is a [terminology-identifier](@). If not specified, its value is taken to be the default [terminology](@) of the [current scope](@). diff --git a/docs/specs/tools/21-mrgt.md b/docs/specs/tools/21-mrgt.md index 650d49acff..fea8728f62 100644 --- a/docs/specs/tools/21-mrgt.md +++ b/docs/specs/tools/21-mrgt.md @@ -166,7 +166,7 @@ An [MRG](@) SHOULD NOT have two (or more) [MRG entries](@) that have a same elem When the creation of a [provisional MRG](@) is complete, a filename `mrg...yaml` is constructed, where: - `` is the [scopetag](@) that is used within the [current scope](@) to refer to itself. Its value can be found in the `scopetag`-field in the [`scope` section](docs/specs/files/saf#terminology) of the [SAF](@). -- `` is the [versiontag](@) that [identifies](@) the version of the [terminology](@) for which the [MRG](@) contains [entries](mrg-entry@). Its value must be equal to that found in the `vsntag`-field of the element in the [versions section](/docs/specs/files/saf#versions) of the [SAF](@) from which the [MRG](@) was generated. +- `` is the [versiontag](@) that identifies the version of the [terminology](@) for which the [MRG](@) contains [entries](mrg-entry@). Its value must be equal to that found in the `vsntag`-field of the element in the [versions section](/docs/specs/files/saf#versions) of the [SAF](@) from which the [MRG](@) was generated. If a file with that name already exists in the [glossarydir](@) of the [current scope](@), it will be deleted. Then, a new file with that name will be created, which will contain: diff --git a/docs/specs/tools/22-hrgt.md b/docs/specs/tools/22-hrgt.md index 43b8de6c98..1fab1838b1 100644 --- a/docs/specs/tools/22-hrgt.md +++ b/docs/specs/tools/22-hrgt.md @@ -270,7 +270,7 @@ When this markdown file is processed by the [HRGT](@), a new file is created whe | Term | Description | | :--- | :---------- | | Glossary | an alphabetically sorted list of [terms](@) with the (single) meaning it has in (at least) one context. | -| Curator (of a Scope) | a person responsible for curating, managing, and maintaining the [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@). | +| Curator (of a Scope) | a person responsible for curating, managing, and maintaining the [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@essif-lab). | | Definition | the combination of a [term](@) and a descriptive text, where the [term](@) refers to a [concept](@) or other [semantic unit](@), and the descriptive text enables a set of [parties](@) to have the same understanding about that [concept](@). Ideally, the descriptive text is a criterion that such [parties](@) can use to determine what is, and what is not, an instance (or example) of that [concept](@). | ~~~ diff --git a/docs/terms/corpus.md b/docs/terms/corpus.md index cc0fcdd819..efe0635daa 100644 --- a/docs/terms/corpus.md +++ b/docs/terms/corpus.md @@ -7,7 +7,7 @@ term: corpus termType: concept isa: glossaryTerm: -glossaryText: "the documentation that describes the [knowledge](@) around a set of [terms](@) and [concepts](@)." +glossaryText: "the documentation that describes the [knowledge](@essif-lab) around a set of [terms](@) and [concepts](@)." grouptags: [ ] formPhrases: [ "corpus", "corpora", "corpus-of-terminology", "corpus-of-a-terminology", "terminology corpus" ] # Curation status @@ -23,7 +23,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Corpus ## Short Description -The **Corpus** or **Corpus of Terminology** is the documentation that describes the [knowledge](@) around a set of [terms](@) and [concepts](@). It is typically governed by conventions that are specified by a group of [terms communities](@), such as [TOIP's Concepts and Terminology Working Group](https://wiki.trustoverip.org/pages/viewpage.action?pageId=65700). +The **Corpus** or **Corpus of Terminology** is the documentation that describes the [knowledge](@essif-lab) around a set of [terms](@) and [concepts](@). It is typically governed by conventions that are specified by a group of [terms communities](@), such as [TOIP's Concepts and Terminology Working Group](https://wiki.trustoverip.org/pages/viewpage.action?pageId=65700). The [terminology pattern](pattern:terminology@) relates this concept with other terminological [concepts](@). diff --git a/docs/terms/curate.md b/docs/terms/curate.md index c1960e3a1e..c2cd24cf14 100644 --- a/docs/terms/curate.md +++ b/docs/terms/curate.md @@ -7,7 +7,7 @@ term: curate termType: concept isa: glossaryTerm: Curate -glossaryText: "to select, organize, and present [terms](@), [definitions](@), and other, related content in a thoughtful and purposeful manner to establish shared understanding among a [community](@) working together on a particular set of [objectives](@)." +glossaryText: "to select, organize, and present [terms](@), [definitions](@), and other, related content in a thoughtful and purposeful manner to establish shared understanding among a [community](@) working together on a particular set of [objectives](@essif-lab)." grouptags: [ "terminology", "cm-party-actor-action" ] formPhrases: [ "curates", "curated", "curating", "curation" ] # Curation status @@ -22,7 +22,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Curate -**Curate**: to select, organize, and present [terms](@), [definitions](@), and other, related content in a thoughtful and purposeful manner to establish shared understanding among a [community](@) working together on a particular set of [objectives](@). The act of curation involves careful consideration of the relevance, clarity, and context of the [concepts](@) and their [definitions](@), ensuring that they are unambiguous and effectively support communication and collaboration within the [community](@). +**Curate**: to select, organize, and present [terms](@), [definitions](@), and other, related content in a thoughtful and purposeful manner to establish shared understanding among a [community](@) working together on a particular set of [objectives](@essif-lab). The act of curation involves careful consideration of the relevance, clarity, and context of the [concepts](@) and their [definitions](@), ensuring that they are unambiguous and effectively support communication and collaboration within the [community](@). ### Notes diff --git a/docs/terms/curator.md b/docs/terms/curator.md index e4952a0e82..8056ef337e 100644 --- a/docs/terms/curator.md +++ b/docs/terms/curator.md @@ -7,7 +7,7 @@ term: curator termType: concept isa: glossaryTerm: "Curator (of a Scope)" -glossaryText: "a person responsible for curating, managing, and maintaining the [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@)." +glossaryText: "a person responsible for curating, managing, and maintaining the [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@essif-lab)." grouptags: [ "terminology" ] formPhrases: [ "curator{ss}", "terminology-curator{ss}" ] # Curation status @@ -22,7 +22,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Curator (of a Scope) -A **Curator** is a person responsible for curating, managing, and maintaining [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@). They carefully select, organize, and present the [terminology](@), ensuring that the [definitions](@) are clear, precise, and reflect the [community's](@) agreed-upon understanding of the [concepts](@) (and other [semantic units](@)) they use. +A **Curator** is a person responsible for curating, managing, and maintaining [terminologies](@), to ensure shared understanding among a [community](@) working together on a particular set of [objectives](@essif-lab). They carefully select, organize, and present the [terminology](@), ensuring that the [definitions](@) are clear, precise, and reflect the [community's](@) agreed-upon understanding of the [concepts](@) (and other [semantic units](@)) they use. ### Examples diff --git a/docs/terms/define.md b/docs/terms/define.md index 8a72b93d01..3dbf5340ca 100644 --- a/docs/terms/define.md +++ b/docs/terms/define.md @@ -22,7 +22,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Define -To **define** is to provide a clear and precise explanation of a concept or term, including its essential characteristics, to establish a shared understanding among a community working together on a particular set of [objectives](@). This is done by: +To **define** is to provide a clear and precise explanation of a concept or term, including its essential characteristics, to establish a shared understanding among a community working together on a particular set of [objectives](@essif-lab). This is done by: 1. providing a criterion, where the criterion can be used by people to determine whether or not something is an instance/example of a [concept](@) (or other [semantic unit](@)) 2. providing a [term](@), that is proposed for the purpose of referring to that [concept](@) itself, or an arbitrary instance thereof. @@ -37,4 +37,4 @@ To **define** is to provide a clear and precise explanation of a concept or term ### Notes -Defining concepts accurately is a foundational step in the curation process, as it establishes a common understanding of key terms within the community. A well-defined terminology ensures that individuals within the community can communicate effectively, resolve ambiguities, and work towards shared [objectives](@) with precision. +Defining concepts accurately is a foundational step in the curation process, as it establishes a common understanding of key terms within the community. A well-defined terminology ensures that individuals within the community can communicate effectively, resolve ambiguities, and work towards shared [objectives](@essif-lab) with precision. diff --git a/docs/terms/definition.md b/docs/terms/definition.md index 32b2b4458d..1d38c028d9 100644 --- a/docs/terms/definition.md +++ b/docs/terms/definition.md @@ -25,7 +25,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? ### Summary A **Definition** is the combination of a [term](@) and a descriptive text, where the [term](@) refers to a [concept](@) or other [semantic unit](@), and the descriptive text enables a set of [parties](@) to have the same understanding about that [concept](@). Ideally, the descriptive text is a criterion that such [parties](@) can use to determine what is, and what is not, an instance (or example) of that [concept](@). The quality of a definition is the extent in which [parties](@) can use it to actually demonstrate that they have the same understanding. -The problem that definitions (as we see them) contribute to solving is misunderstandings that may arise as every [party](@) has its own [knowledge](@) and autonomously determines the [semantics](@) it uses to express itself in texts/speech/pictures, and interpret that of other parties. The fact that the semantics of parties is subjective makes it realistic to assume that the meaning that a party intends to convey as it expresses itself is not the same as how another party interprets that expression - a 'misunderstanding'. +The problem that definitions (as we see them) contribute to solving is misunderstandings that may arise as every [party](@) has its own [knowledge](@essif-lab) and autonomously determines the [semantics](@) it uses to express itself in texts/speech/pictures, and interpret that of other parties. The fact that the semantics of parties is subjective makes it realistic to assume that the meaning that a party intends to convey as it expresses itself is not the same as how another party interprets that expression - a 'misunderstanding'. All parties have learned, with varying degrees of sophistication, to identify misunderstandings, and ways to recover from that. @@ -33,7 +33,7 @@ A common mechanism for reducing the likelihood of misunderstandings to occur, is Therefore, we insist that such texts -- are associated with a [scope](@) within which they are considered to be valid/useful (for the [objectives](@) that [parties](@) pursue in that [scope](@)); +- are associated with a [scope](@) within which they are considered to be valid/useful (for the [objectives](@essif-lab) that [parties](@) pursue in that [scope](@)); - are phrased as a [criterion](https://www.lexico.com/definition/criterion) that every such [party](@) can evaluate so as to determine whether or not something qualifies to be referred to by that term. The quality of such texts is the extent in which parties reach the same conclusion as they evaluate the criterion in an arbitrary use-case that is relevant for the scope. @@ -48,7 +48,7 @@ Working together is easier when you and your peers share the same ideas. We need ### Criteria A **definition** is a text that comprises at a minimum: -- a [scope](@) that is [curated](@) by a [party](@), and that is related to (the pursuit of) a non-empty set of [objectives](@); +- a [scope](@) that is [curated](@) by a [party](@), and that is related to (the pursuit of) a non-empty set of [objectives](@essif-lab); - a [criterion](https://www.lexico.com/definition/criterion) that specifies the necessary and sufficient conditions for determining what does and what does not constitute some [concept](@) (idea, class of [entities](@)); - a [name or phrase](term@) that is used within the [scope](@) to refer to (unidentified, or arbitrary, or specific) [entities](@) that satisfy the criterion. diff --git a/docs/terms/form-phrase-macro.md b/docs/terms/form-phrase-macro.md index 987a6dac2d..591ba66900 100644 --- a/docs/terms/form-phrase-macro.md +++ b/docs/terms/form-phrase-macro.md @@ -7,7 +7,7 @@ term: form-phrase-macro termType: concept isa: glossaryTerm: "Form Phrase Macro" -glossaryText: "a sequence of characters (the macro name) that [identifies](@) a sequence (map) of character strings that specify typical variations of a [form phrase](@), such as plural forms, possessie extensions, verb-conjugation forms, etc." +glossaryText: "a sequence of characters (the macro name) that identifies a sequence (map) of character strings that specify typical variations of a [form phrase](@), such as plural forms, possessie extensions, verb-conjugation forms, etc." formPhrases: [ "formphrase macro{ss}", "form-phrase macro{ss}" ] # Curation status status: proposed @@ -21,7 +21,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Form Phrase Macro -A **Form Phrase Macro** is a sequence of characters (the macro name) that [identifies](@) a sequence (map) of character strings that specify typical variations of a [form phrase](@), such as plural forms, possessie extensions, verb-conjugation forms, etc. +A **Form Phrase Macro** is a sequence of characters (the macro name) that identifies a sequence (map) of character strings that specify typical variations of a [form phrase](@), such as plural forms, possessie extensions, verb-conjugation forms, etc. For example, when the macro `{ss}` is used in a [form phrase](@) specification `"actor{ss}"`, or `act`, this is a shorthand for the set `"actor", "actors", "actor's", "actor(s)"`, or the set `"act", "acts", "act's", "act(s)"` respectively. diff --git a/docs/terms/form-phrase.md b/docs/terms/form-phrase.md index a725cf6b2a..fe42264014 100644 --- a/docs/terms/form-phrase.md +++ b/docs/terms/form-phrase.md @@ -25,7 +25,7 @@ A **Form Phrase** is a word or phrase that occurs in oral or written texts and t ## Purpose -[Form phrases](@) act as (standardized, human readable) [identifiers](@) for [semantic units](@), enabling consistent and unambiguous references across various texts such as manuals, specifications, and guidelines. This is particularly useful (if not vital) in fields where precise terminology is key, ensuring that all stakeholders have a common understanding of the terms used and thereby reducing the potential for misinterpretation or confusion. +[Form phrases](@) act as (standardized, human readable) identifiers for [semantic units](@), enabling consistent and unambiguous references across various texts such as manuals, specifications, and guidelines. This is particularly useful (if not vital) in fields where precise terminology is key, ensuring that all stakeholders have a common understanding of the terms used and thereby reducing the potential for misinterpretation or confusion. ## Specifying Form Phrases in Curated Texts {#specifying} @@ -51,7 +51,7 @@ formPhrases: [ "actor{ss}", "human actor{ss}", "machine actor{ss}" ] ## Using/Matching Form Phrases {#matching} -Form phrases are used to refer to a particular [semantic unit](@) as known in a particular [terminology](@). In other words, they must [identify](@) the [MRG entry](@) and/or the [curated text](@) that documents this [semantic unit](@). +Form phrases are used to refer to a particular [semantic unit](@) as known in a particular [terminology](@). In other words, they must identify the [MRG entry](@) and/or the [curated text](@) that documents this [semantic unit](@). Here is how a [from phrase](@) is matched against: diff --git a/docs/terms/identifier.md b/docs/terms/identifier.md deleted file mode 100644 index fc19750a2a..0000000000 --- a/docs/terms/identifier.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -# Docusaurus header -id: identifier -displayed_sidebar: tev2SideBar -# TEv2 Curated Text Header -term: identifier -termType: concept -isa: -glossaryTerm: -glossaryText: "a character string that is being used for the identification of some [entity](@) (yet may refer to 0, 1, or more [entities](@), depending on the context within which it is being used)." -grouptags: [ ] -formPhrases: [ "identifier{ss}" ] -# Curation status -status: proposed -created: 20210601 -updated: 20210601 -# Origins/Acknowledgements -contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" -originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" ---- - -# Identifier - -### Short Description -An **Identifier** is a character string that is being used for identification purposes (by a specific [party](@)).[^1] This includes names and labels, as they are (obviously) used for such purposes. - -Note that while an identifier is used for identification purposes, this does not automatically imply that it actually identifies (singles out) anything. It also depends on what [RFC 3986](https://tools.ietf.org/html/rfc3986) calls the 'scope of identification', or what [Pfitzmann and Hansen (2010)](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) refer to as an 'identifiability set', which are relevant for explaining whether or not (and if so: what) an identifier actually identifies (singles out) in a given context. See the [Discussion](./identifier#discussion---scope-of-identification) below. - -Also note that [entities](@) need not be tangible in order to be [identified](@), thus enabling the use of [terms](@) as a means to [identify](@) (and represent) [semantic units](@). - -### Purpose -[Parties](@) have a need to reason about [entities](@), i.e. things they know to exist, which requires them to have a conscious representation of such things, as well as the ability to identify (single) out individual entities. One way to do that is to tag an entity with a character string (label, name), that would then qualify as an identifier. - -Also, identifiers may serve identification purpose in communications between different [parties](@), the idea being that when one [party](@) mentions an identifier (that identifies some [entity](@) for this [party](@) ) to another [party](@), the latter would be able to determine the [entity](@) that the first is talking about. See the [Discussion](./identifier#discussion---scope-of-identification) below. - -### Criterion -An **Identifier** is a character string that is being used for identification purposes by a specific [party](@). - -### Examples -The following strings are examples: 'localhost', 'https://localhost/', 'Trust over IP community', 'the mayor of New York', 'guardianship', 'my mother', 'did:sov:2wJPyULfLLnYTEFYzByfUR', 'did:sov:2wJ', 'issue #24', etc., etc. - ------ -### Notes -[^1]: This is the definition of [RFC 3986, Section 1.1.](https://tools.ietf.org/html/rfc3986#section-1.1) but without the requirement of complying with URI syntax constraints. Note that there is consensus in the literature about this. For example, [(Allen, 2016)](http://www.lifewithalacrity.com/2016/04/the-path-to-self-soverereign-identity.html) defines 'Identifier' as “A name or other label that uniquely identifies an identity.”. [Pfitzmann and Hansen, 2010](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) say (in footnote 57): “A name or another bit string”. The [DID-core specification](https://www.w3.org/TR/did-core/) of W3C [defines 'decentralized identifiers' as specializations of URIs](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers). - -### Discussion - Scope of Identification -[RFC 3986, Section 1.1.](https://tools.ietf.org/html/rfc3986#section-1.1) states _"an identifier embodies the information required to distinguish what is being identified from all other things within its **scope of identification"**_. This statement suggests that identifiers (URIs) have a single scope, supposedly specified by "_the URI schemes and naming authority (if any)_". However, there is no such requirement, and there is nothing in place to guarantee this (apart from IANA, many other (sometimes even very commonly used) URI schemes exist). [Pfitzmann and Hansen (2010)](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) (section 13.2) use the term 'identifiability sets' rather than 'scope of identification', and describe how 'attackers' - but that could equally well have been regular users - each have, or construct their own scope, and use contextual information to do so. - -The criterion that makes a text string qualify as an identifier doesn't seem to cut it, as only _using_ a text for identification purposes doesn't make it have (what we will call) the 'identification property', i.e. the property that it _actually_ identifies something. It may only have that property in combination with an associated (single) scope of identification, which may depend on the context in which it is being used. [RFC 2986, page 6](https://tools.ietf.org/html/rfc3986#page-6) illustrates this using the identifier "http://lcoalhost/". - -The lack of (identifying) scopes of identification becomes an issue when a [party](@) (say Alice) sends the identifier (e.g. `my car`) to another [party](@) (say Bob), expecting that Bob will then be able to identify the same [entity](@) that she identifies with it (presumably some specific car). - -If Bob had just met Alice for the first time, and hadn't seen her coming in a car, then Alice must acquaint Bob with the existence of the [entity](@) that she refers to with `my car`, e.g. by pointing her finger to it, or describing the make, brand and license plate or some other characteristic that allows Bob to single out her car (in the context of their meeting one another). Then, Bob can 'register' the existence of that car in his [knowledge](@) (optionally tagging it with an identifier of his own, e.g. `Alice's car`), and associate it with the attribute (party='Alice', identifier='`my car`'). It is important to have the "party='Alice'" part in there, because other parties, (e.g. Carol) may also use an identifier `my car`, which would and should then refer to another car. This shows that the scope of interpretation for an identifier has to do with the ([knowledge](@) of) [parties](@) that use it, and that understanding the intended meaning requires a proper identification of that scope. diff --git a/docs/terms/identify.md b/docs/terms/identify.md deleted file mode 100644 index 6692b4ba26..0000000000 --- a/docs/terms/identify.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -# Docusaurus header -id: identify -displayed_sidebar: tev2SideBar -# TEv2 Curated Text Header -term: identify -termType: concept -isa: -glossaryTerm: -glossaryText: "an [act](action@), by or on behalf of a [party](@), that results in the selection of either - a single [partial identity](@) that the party [owns](@), given some (observed or received) data, or - a single [entity](@) from a given set of entities that is the [subject](@) of a specified [partial identity](@) that the party [owns](@)." -grouptags: [ ] -formPhrases: [ "identify", "identifying", "identifies", "identified", "identifiable", "identification" ] -# Curation status -status: proposed -created: 20210601 -updated: 20210601 -# Origins/Acknowledgements -contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" -originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" ---- - -# Identify - -### Short Description -**Identification** is an [act](action@), by or on behalf of a [party](@), that results in either the selection of -1. a single [partial identity](@) that the party [owns](@), given some (observed or received) data, or -2. a single [entity](@) from a given set of entities that is the [subject](@) of a specified [partial identity](@) that the party [owns](@). - -An example of the first clause is where you answer the door for a person. The first thing you do is to observe characteristics of that person, and see if there is a match with the characteristics in one of the [partial identities](@) that you have in your [knowledge](@). In case you have trouble finding one (e.g. when you suspect it might be an acquaintance that you haven't seen for a long time) you may ask questions, eliciting further observations that allow you to select a specific [partial identity](@). A sigh of relief may signal that the act of identification has successfully terminated. If you didn't find a [partial identity](@), you would typically (and automatically) start to construct one, which would enable you to identify this person in future situations. - -An example of the second clause is where you need to see or talk to a specific [entity](@), i.e. an entity that - since you know it exists - you have a (single) [partial identity](@) for. Here, you acquire characteristics for the various entities that you encounter until you find a match with that [partial identity](@). Then, you proceed to interact with that entity as you intended. - -Issues/misunderstandings related to identification can easily arise, because if an entity is known to exist by different parties, they would each have different partial identities for it, which may cause misunderstandings in communications if parties are unaware of these differences. - -One of various well-known problems related to identification is the transfer of files/dossiers, e.g. in the health and education domains. Since (the contents of) such files represent knowledge about their [subject](@), and the [partial identity](@) of that [subject](@) that is [owned](@) by the [owner](@) of such files includes all [knowledge](@) about that [subject](@), the knowledge represented in the file are a part of this [partial identity](@). Now when such files are transferred to another party, the receiving party has to make sure that these files are associated with that party's [partial identity](@) of that same [subject](@). - -Non-human [actors](@) can also perform identification. However, since they cannot access the [partial identities](@) of the [party](@) on whose behalf they work (because these reside in the information domain - see the [identity pattern](pattern:identity@essif-lab)), they have to do with may be referred to as a user/account registration. Such registrations contain 'user records' or 'accounts', each of which represents an excerpt of a specific [partial identity](@), that contains all necessary data for the non-human [actor](@) to execute the [actions](@) that it is tasked with. Typically, a user record would contain a username, i.e. an [identifier](@) that the [actor](@) can use to identify the user record. Also, it typically contains authentication data, e.g. a password, that the [actor](@) can use to ensure that the user is the actual [subject](@) of the user record (account) that it has selected. However, it would also contain additional data to facilitate further interactions between this [actor](@) and the user, e.g. role assignments or other attributes. diff --git a/docs/terms/knowledge-artifact.md b/docs/terms/knowledge-artifact.md deleted file mode 100644 index b6604db3f0..0000000000 --- a/docs/terms/knowledge-artifact.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -# Docusaurus header -id: knowledge artifact -displayed_sidebar: tev2SideBar -# TEv2 Curated Text Header -term: knowledge artifact -termType: concept -isa: -glossaryTerm: Knowledge Artifact -glossaryText: "See: [semantic unit](@). (term is deprecated)" -synonymOf: semantic-unit -grouptags: [ ] -formPhrases: [ "knowledge-artifact{ss}" ] -# Curation status -status: deprecated -created: 20220727 -updated: 20230926 -# Origins/Acknowledgements -contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" -originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" ---- - -# Knowledge Artifact - -:::info -This term is DEPRECATED, but the [concept](@) to which it referred has not. -We use the term [semantic unit](@) to refer to this concept, so as to be more in line with terminology of cognitive science. -::: diff --git a/docs/terms/mental-model.md b/docs/terms/mental-model.md index 40decbff7f..733970f969 100644 --- a/docs/terms/mental-model.md +++ b/docs/terms/mental-model.md @@ -46,7 +46,7 @@ A limited set of [concepts](@) (preferably not exceeding 7+/-2)[^1], [relations] ### Notes The first purpose of a mental model is to help us think and reason about a certain topic or issue. -One signal that indicates the need of such a model is when we're running circles in our thoughts, and we have this feeling of not understanding, of the topic being (too) complex. Often, we are thinking in terms of concepts that are not fit for the [objectives](@) we pursue. +One signal that indicates the need of such a model is when we're running circles in our thoughts, and we have this feeling of not understanding, of the topic being (too) complex. Often, we are thinking in terms of concepts that are not fit for the [objectives](@essif-lab) we pursue. ### On Using (existing) Mental models diff --git a/docs/terms/patterns/pattern-terminology.md b/docs/terms/patterns/pattern-terminology.md index c7420b89e9..2062df9d2a 100644 --- a/docs/terms/patterns/pattern-terminology.md +++ b/docs/terms/patterns/pattern-terminology.md @@ -7,7 +7,7 @@ term: terminology termType: pattern isa: glossaryTerm: "Terminology Pattern" -glossaryText: "a [mental model](@) that describes the relations between a [community](@), its (intangible) [knowledge](@), and the artifacts we use to document that [knowledge](@), such as [terms](@), [definitions](@), [mental models](@), [glossaries](@), etc." +glossaryText: "a [mental model](@) that describes the relations between a [community](@), its (intangible) [knowledge](@essif-lab), and the artifacts we use to document that [knowledge](@essif-lab), such as [terms](@), [definitions](@), [mental models](@), [glossaries](@), etc." grouptags: [ ] formPhrases: [ "terminology-pattern{ss}" ] # Curation status @@ -24,21 +24,21 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? import useBaseUrl from '@docusaurus/useBaseUrl' -This [mental model](@) describes the relations between a [community](@), its (intangible) [knowledge](@), and the artifacts we use to document that [knowledge](@), such as [terms](@), [definitions](@), [mental models](@), [glossaries](@), etc. +This [mental model](@) describes the relations between a [community](@), its (intangible) [knowledge](@essif-lab), and the artifacts we use to document that [knowledge](@essif-lab), such as [terms](@), [definitions](@), [mental models](@), [glossaries](@), etc. It aims to serve the following purposes: -- enabling members of a [community](@), as well as other [parties](@), to document their understanding of the [concepts](@) and other [semantic units](@) (e.g., [mental models](@)) that are relevant for their purposes (i.e., for realizing their [objectives](@)). -- provide a solid basis for the design and development of a [set of IT tools](/docs-overview) that support [communities](@) as they document their [knowledge](@). +- enabling members of a [community](@), as well as other [parties](@), to document their understanding of the [concepts](@) and other [semantic units](@) (e.g., [mental models](@)) that are relevant for their purposes (i.e., for realizing their [objectives](@essif-lab)). +- provide a solid basis for the design and development of a [set of IT tools](/docs-overview) that support [communities](@) as they document their [knowledge](@essif-lab). ### Introduction This pattern has two basic parts: -1. the [management](@)-related part. This part consists of a [community](@) that [owns](@) its particular set of [objectives](@) which exist for establishing cooperation between its members, and for which it needs to establish and maintain, a [terminology](@). [Managing, or curating](curate@) a [terminology](@) consists of realizing the [objectives](@) that the terminology is intended to serve, i.e. to establish a set of [concepts](@), [definitions](@), [terms](@) and [mental models](@), the quality of which is meant to be such that +1. the [management](@essif-lab)-related part. This part consists of a [community](@) that [owns](@essif-lab) its particular set of [objectives](@essif-lab) which exist for establishing cooperation between its members, and for which it needs to establish and maintain, a [terminology](@). [Managing, or curating](curate@) a [terminology](@) consists of realizing the [objectives](@essif-lab) that the terminology is intended to serve, i.e. to establish a set of [concepts](@), [definitions](@), [terms](@) and [mental models](@), the quality of which is meant to be such that - members of the [community](@) use them in the same, single meaning, thereby preventing difficulties in their cooperation, caused by differences in the individual understandings of words or phrases, and - non non-members of the [community](@) can obtain a precise understanding of the communications within that community. -Also, this [management](@) may cause reference documents to be created and maintained, e.g. a [glossary](@) that lists the [terminology](@) of the [community](@), a [dictionary](@) that includes its [terminology](@) as well as [terminologies](@) from other, related [communities](@). +Also, this [management](@essif-lab) may cause reference documents to be created and maintained, e.g. a [glossary](@) that lists the [terminology](@) of the [community](@), a [dictionary](@) that includes its [terminology](@) as well as [terminologies](@) from other, related [communities](@). 2. the terminology-related part. This is where [concepts](@), [definitions](@), [terms](@), [glossaries](@) etc. live. This part is what one needs to create tools/support for managing and maintaining a [terminology](@). Here, we have [concepts](@) with their [definitions](@) and [terms](@) as a means to refer to either. A [concept](@), its [definition](@) live in the same [scope](@), and within that [scope](@) there must be a [term](@) to refer to that [concept](@) and its [definition](@). Within a specific [scope](@), every [term](@) is associated with precisely one such [concept](@) and [definition](@). However, within a [scope](@), a [concept](@)/[definition](@) pair may be referred to by multiple [terms](@), which are then synonyms or aliases of each other. @@ -54,7 +54,7 @@ The figure shows three areas: - the [white area](#white) has the [concepts](@) that deal with the organization of this. - the [green area](#green) represents a [scope](@), in which at most one [terminology](@) lives, and that also includes [tags](@), [scoped terms](@) and [definitions](@). The (contents of the) [scope](@) is curated (developed, maintained) by a single so-called [terms-community](@). -- the [yellow area](#yellow) represents a [knowledge](@), in which intangible artifacts such as [objectives](@) and [concepts](@) reside. +- the [yellow area](#yellow) represents a [knowledge](@essif-lab), in which intangible artifacts such as [objectives](@essif-lab) and [concepts](@) reside. #### White: Parties, Communities {#white} @@ -65,12 +65,12 @@ Our [model](mental-model@) expresses this idea by saying that a [community](@) c A [terms-community](@) is a [community](@) (whose members are called [curators](@)) that aims to serve/support specific [communities](@) (including perhaps itself) by enabling them to: - prevent misunderstandings amongst their members, and - [author](@) communications in such a way that the likelihood of non-members misunderstanding such communications is minimized. -- [manages](@) these [objectives](@) itself, producing results that include: +- [manages](@essif-lab) these [objectives](@essif-lab) itself, producing results that include: - one or more [HRGs](@) that each render the [terminology](@) of the [scope](@) that it curates; - the specification of (any number of) [tags](@) that either - - [identify](@) a [scope](@) (and thereby implicitly also its [terminology](@)) - the so-called [scope tags](@), or + - identify a [scope](@) (and thereby implicitly also its [terminology](@)) - the so-called [scope tags](@), or - can be associated with [definitions](@) as a means of grouping the [concepts](@) such [definitions](@) define - the so-called [group tags](@). - - [identify](@) a specific version of the [terminology](@) - the so-called [version tags](@). + - identify a specific version of the [terminology](@) - the so-called [version tags](@). We refer the reader to @@ -85,7 +85,7 @@ Every [terminology](@) is scoped, i.e. part of a [scope](@). This [scope](@) con The central [concept](@) in this part is the [curated text](@), as it [documents](/docs/specs/files/curated-text-file) a specific [semantic unit](@), provides its [definition](@) (when appropriate), and specifies the [scoped term](@) that represents such [semantic unit](@) as well as its [synonyms](@). It also contains various other data, e.g. the [term type](@) (which is also the type of the [semantic unit](@)), the list of [grouptags](@) that identify the groups of [semantic units](@) to which (the [semantic unit](@) that) it (documents,) belongs, etc. Basically, *any* changes to documentation or attributes related to a particular [semantic unit](@) are done in its [curated text](@). -Another important [concept](@) is the [MRG entry](@), i.e. a [(machine readable) representation](http://localhost:3000/docs/specs/files/mrg#entries) of the meta data of a [semantic unit](@) that it refers to. Note that this [semantic unit](@) need not reside in the [knowledge](@) of the [community](@) that owns the [scope](@) (in which case it would mainly consists of the header data of the [curated text](@) that documents the [semantic unit](@)), but can also reside in another [knowledge](@) (in which case it would be a copy of an [MRG entry](@) in an [MRG](@) of a [scope](@) that documents that [semantic unit](@)). +Another important [concept](@) is the [MRG entry](@), i.e. a [(machine readable) representation](http://localhost:3000/docs/specs/files/mrg#entries) of the meta data of a [semantic unit](@) that it refers to. Note that this [semantic unit](@) need not reside in the [knowledge](@essif-lab) of the [community](@) that owns the [scope](@) (in which case it would mainly consists of the header data of the [curated text](@) that documents the [semantic unit](@)), but can also reside in another [knowledge](@essif-lab) (in which case it would be a copy of an [MRG entry](@) in an [MRG](@) of a [scope](@) that documents that [semantic unit](@)). The [MRG](@) for a specific [terminology](@) of the [scope](@) is a [structure](/docs/specs/files/mrg#structure) that consists of some meta-data followed by a set of such [MRG entries](@) (with some meta data added). Within a [scope](@), multiple [terminologies](@) (and hence also multiple [MRGs](@)) can exist, e.g., which are distinguished between by their [version tags](@). @@ -101,14 +101,14 @@ Apart from the multiplicity constrained that are showed in the figure, some addi When we say that a [terms-community](@) [curates](@) a [scope](@), this means that the [terms-community](@) -- [manages](@) (creates/maintains) the set of [definitions](@) that define [concepts](@) that are relevant for realizing its [objectives](@); -- [manages](@) (creates/maintains) all [terminologies](@) of the [scope](@), and designate which of them is to be considered the default [terminology](@). +- [manages](@essif-lab) (creates/maintains) the set of [definitions](@) that define [concepts](@) that are relevant for realizing its [objectives](@essif-lab); +- [manages](@essif-lab) (creates/maintains) all [terminologies](@) of the [scope](@), and designate which of them is to be considered the default [terminology](@). - ensures that a [terminology](@) consists of: - at least one term for every [definition](@) that is part of the [scope](@), and - - at least one term for any other [definition](@) (which is part of *another* [scope](@), i.e. curated by another [terms-community](@)) that defines a concept that is relevant for realizing one or more [objectives](@) of the [terms-community](@). -- [manages](@) (creates/maintains) the various [tags](@) in the scope, i.e. defines a [scopetag](@) for the [scope](@), [versiontags](@) (if necessary) for the different versions of the [terminology](@) of that [scope](@), and (optionally) any [grouptags](@) for grouping sets of [terms](@). + - at least one term for any other [definition](@) (which is part of *another* [scope](@), i.e. curated by another [terms-community](@)) that defines a concept that is relevant for realizing one or more [objectives](@essif-lab) of the [terms-community](@). +- [manages](@essif-lab) (creates/maintains) the various [tags](@) in the scope, i.e. defines a [scopetag](@) for the [scope](@), [versiontags](@) (if necessary) for the different versions of the [terminology](@) of that [scope](@), and (optionally) any [grouptags](@) for grouping sets of [terms](@). #### Yellow: Intangible Concepts {#yellow} -The intangible [semantic units](@) (e.g., [concepts](@), [relations](@), [patterns](@) etc.) are important because this is where the misunderstandings live. The [knowledge](@) of a [party](@) uses a subjective [conceptualization](@) of the world (that the [party](@) has perceived to be living in for as long as it exists) for its individual reasoning, arguing, communicating, decision making etc. Because of this, two [parties](@) that collaborate (i.e.: form a [community](@)) cannot be expected to have the same conceptualizations. However, it is a common belief that if one uses a [term](@) to refer to a [concept](@) in its [knowledge](@), the other will then relate it to 'the same' [concept](@) within its own knowledge, that we should not assume actually exists. For example, when one of them uses the [term](@) 'identity', it knows which [concept](@) that relates to within its own [knowledge](@). However, others need to hallucinate as to what that [concept](@) might be, and typically respond by thinking that the [concept](@) that the [term](@) refers to in their own [knowledge](@) would be its intended meaning. In many cases that doesn't pose a problem, because the [concepts](@) of both [knowledges](@) are 'sufficiently the same'. In other cases, the differences in meaning may be such that it disrupts the collaboration between the [parties](@). And that is when it helps to have 'good [definitions](@)', because they have the property that collaborators can assess whether or not the [concepts](@) in their [knowledge](@) (that a well-defined [term](@) refers to) are 'sufficiently the same'. +The intangible [semantic units](@) (e.g., [concepts](@), [relations](@), [patterns](@) etc.) are important because this is where the misunderstandings live. The [knowledge](@essif-lab) of a [party](@) uses a subjective [conceptualization](@) of the world (that the [party](@) has perceived to be living in for as long as it exists) for its individual reasoning, arguing, communicating, decision making etc. Because of this, two [parties](@) that collaborate (i.e.: form a [community](@)) cannot be expected to have the same conceptualizations. However, it is a common belief that if one uses a [term](@) to refer to a [concept](@) in its [knowledge](@essif-lab), the other will then relate it to 'the same' [concept](@) within its own knowledge, that we should not assume actually exists. For example, when one of them uses the [term](@) 'identity', it knows which [concept](@) that relates to within its own [knowledge](@essif-lab). However, others need to hallucinate as to what that [concept](@) might be, and typically respond by thinking that the [concept](@) that the [term](@) refers to in their own [knowledge](@essif-lab) would be its intended meaning. In many cases that doesn't pose a problem, because the [concepts](@) of both [knowledges](@) are 'sufficiently the same'. In other cases, the differences in meaning may be such that it disrupts the collaboration between the [parties](@). And that is when it helps to have 'good [definitions](@)', because they have the property that collaborators can assess whether or not the [concepts](@) in their [knowledge](@essif-lab) (that a well-defined [term](@) refers to) are 'sufficiently the same'. -In order to keep the work of devising [definitions](@) to a minimum, it helps to know the [objectives](@) that the members of the [community](@) collaboratively seek to realize. Any [definition](@) should define a [concept](@) that is relevant for that collaboration. Other definitions are just useless work. +In order to keep the work of devising [definitions](@) to a minimum, it helps to know the [objectives](@essif-lab) that the members of the [community](@) collaboratively seek to realize. Any [definition](@) should define a [concept](@) that is relevant for that collaboration. Other definitions are just useless work. diff --git a/docs/terms/regularized-text.md b/docs/terms/regularized-text.md index 171d1ec9ed..8674080567 100644 --- a/docs/terms/regularized-text.md +++ b/docs/terms/regularized-text.md @@ -37,7 +37,7 @@ A **Regularized Text** is a character string that starts with a lowercase charac ## Use of Regularized Texts within [TEv2](@) Within [TEv2](@), [regularized texts](@) are used: -- to construct more complex [identifiers](@) such as [term refs](@), [term ids](@), [terminology identifiers](@), URLs, etc. +- to construct more complex identifiers such as [term refs](@), [term ids](@), [terminology identifiers](@), URLs, etc. - as a class of texts, with members such as `termType`, `term`, `grouptags`, and `scopetag`. - to represent [form phrases](@) in [MRG entries](@) (note that the `formPhrases` field of [curated texts](@) do not typically contain [regularized texts](@)) - etc. diff --git a/docs/terms/scope.md b/docs/terms/scope.md index 28ab0c259e..4dd37d3b27 100644 --- a/docs/terms/scope.md +++ b/docs/terms/scope.md @@ -7,7 +7,7 @@ term: scope termType: concept isa: glossaryTerm: -glossaryText: "the extent of the [terms](@), [definitions](@) and other documentation that a [community](@) (which we call the [owner](@) of the [scope](@)) needs to express, communicate and validate its [knowledge](@) as relevant to achieving a specific subset of its [objectives](@)." +glossaryText: "the extent of the [terms](@), [definitions](@) and other documentation that a [community](@) (which we call the [owner](@essif-lab) of the [scope](@)) needs to express, communicate and validate its [knowledge](@essif-lab) as relevant to achieving a specific subset of its [objectives](@essif-lab)." grouptags: [ ] formPhrases: [ "scope{ss}", "scope-context{ss}" ] # Curation status @@ -23,7 +23,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Scope ### Summary -A **scope** is the extent of the [terms](@), [definitions](@) and other documentation that a [community](@) (which we call the [owner](@) of the [scope](@)) needs to express, communicate and validate its [knowledge](@) as relevant to achieving a specific subset of its [objectives](@). +A **scope** is the extent of the [terms](@), [definitions](@) and other documentation that a [community](@) (which we call the [owner](@essif-lab) of the [scope](@)) needs to express, communicate and validate its [knowledge](@essif-lab) as relevant to achieving a specific subset of its [objectives](@essif-lab). Other documentation includes [curated texts](@), and artifacts that are generated from that, such as [glossaries](@), [dictionaries](@) and the like. It also includes [tags](@) that can be used e.g. to refer to other [scopes](@) ([scopetags](@)), identify different versions for artifacts ([versiontags](@)), or create particular groups of [terms](@) ([grouptags](@)). @@ -37,4 +37,4 @@ The [terminology pattern](pattern:terminology@) provides an overview of how this ### Purpose -The purpose of having [scopes](@) is that it enables [communities](@) (and other [parties](@)) to come to develop and maintain [terminologies](@) that are not only relevant for realizing specific [objectives](@), but also are fit for expressing and communicating the [knowledge](@) that is used for doing so. This is known as [curation](@) of a [scope](@). Specifically, [scopes](@) provide the members of the [owning community](terms-community@) (but also non-members) to establish a provable similar understanding of the [concepts](@) and other [semantic units](@), which is prerequisite for fruitful cooperation, and realizing [objectives](@). +The purpose of having [scopes](@) is that it enables [communities](@) (and other [parties](@)) to come to develop and maintain [terminologies](@) that are not only relevant for realizing specific [objectives](@essif-lab), but also are fit for expressing and communicating the [knowledge](@essif-lab) that is used for doing so. This is known as [curation](@) of a [scope](@). Specifically, [scopes](@) provide the members of the [owning community](terms-community@) (but also non-members) to establish a provable similar understanding of the [concepts](@) and other [semantic units](@), which is prerequisite for fruitful cooperation, and realizing [objectives](@essif-lab). diff --git a/docs/terms/scoped-term.md b/docs/terms/scoped-term.md index 3208494f42..db29e2ac67 100644 --- a/docs/terms/scoped-term.md +++ b/docs/terms/scoped-term.md @@ -7,7 +7,7 @@ term: scoped-term termType: concept isa: term glossaryTerm: Scoped Term -glossaryText: "a [term](@) that represents (and [identifies](@)) a specific [semantic unit](@) of a particular [community](@) (or [party](@))." +glossaryText: "a [term](@) that represents (and identifies) a specific [semantic unit](@) of a particular [community](@) (or [party](@))." grouptags: [ ] formPhrases: [ "scoped-term{ss}" ] # Curation status @@ -23,4 +23,4 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Scoped Term ### Summary -A **scoped term** is a [term](@) that represents (and [identifies](@)) a specific [semantic unit](@) of a particular [community](@) (or [party](@)). +A **scoped term** is a [term](@) that represents (and identifies) a specific [semantic unit](@) of a particular [community](@) (or [party](@)). diff --git a/docs/terms/scopetag.md b/docs/terms/scopetag.md index 933f140802..0234ff1532 100644 --- a/docs/terms/scopetag.md +++ b/docs/terms/scopetag.md @@ -7,7 +7,7 @@ term: scopetag termType: concept isa: tag glossaryTerm: -glossaryText: "a [tag](@) that is used to [identify](@) [scopes](@) from within a specific [scope](@)" +glossaryText: "a [tag](@) that is used to identify [scopes](@) from within a specific [scope](@)" grouptags: [ ] formPhrases: [ "scopetag{ss}", "scope-tag{ss}" ] # Curation status @@ -23,14 +23,14 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Scopetag ### Summary -A **Scopetag** is a [tag](@) that is used to [identify](@) [scopes](@), e.g. in [TermRefs](@). +A **Scopetag** is a [tag](@) that is used to identify [scopes](@), e.g. in [TermRefs](@). -Scopetags [identify](@) a [scope](@) (from within a given [scope](@)), and hence can be used (within that given [scope](@)) to disambiguate [terms](@). +Scopetags identify a [scope](@) (from within a given [scope](@)), and hence can be used (within that given [scope](@)) to disambiguate [terms](@). The [terminology pattern](pattern:terminology@) provides an overview of how this concept fits in with related concepts. ### Criteria -A **Scopetag** (of/within a [scope](@)) is a [tag](@) that is used within that [scope](@) to [identify](@) itself or other [scopes](@). It satisfies the [regex](@) `[a-z0-9_-]+`. +A **Scopetag** (of/within a [scope](@)) is a [tag](@) that is used within that [scope](@) to identify itself or other [scopes](@). It satisfies the [regex](@) `[a-z0-9_-]+`. ### Examples Examples of scopetags are `essif-lab`, `toip`, or `ctwg`. diff --git a/docs/terms/semantic-unit.md b/docs/terms/semantic-unit.md index 850131c47d..1ec35cbb1c 100644 --- a/docs/terms/semantic-unit.md +++ b/docs/terms/semantic-unit.md @@ -7,7 +7,7 @@ term: semantic-unit termType: concept isa: glossaryTerm: Semantic Unit -glossaryText: "a basic building block of meaning or representation that exists within the 'mind' of a [party](@) (i.e., in its [knowledge](@))." +glossaryText: "a basic building block of meaning or representation that exists within the 'mind' of a [party](@) (i.e., in its [knowledge](@essif-lab))." glossaryNotes: - "Examples include ideas, or [concepts](@), [properties](@) of [concepts](@), [relations](@) between [concepts](@), constraints over such [concepts](@) and [relations](@), etc." grouptags: [ ] @@ -25,7 +25,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Semantic Unit ## Summary -A **Semantic Unit** is a basic building block of meaning or representation that exists within the 'mind' of a [party](@) (i.e., in its [knowledge](@)). +A **Semantic Unit** is a basic building block of meaning or representation that exists within the 'mind' of a [party](@) (i.e., in its [knowledge](@essif-lab)). Examples include ideas, or [concepts](@), [properties](@) of [concepts](@), [relations](@) between [concepts](@), constraints over such [concepts](@) and [relations](@), etc. @@ -40,7 +40,7 @@ Within [TEv2](@), [semantic units](@) can be [defined](@) in, and described by [ The [terminology pattern](pattern:terminology@) provides an overview of how this concept fits in with related concepts. ## Purpose -[Semantic units](@) exist because they are somehow relevant for realizing [objectives](@) of the [party](@) that has this [knowledge](@). Since [parties](@) rarely realize their [objectives](@) all by themselves, they will need to find ways to communicate them (their meanings) to other [parties](@) and/or [actors](@) that work for/with them, such that the lot of them have something we might call a 'common understanding'. To realize this 'common understanding', the [owner](@) of (the [knowledge](@) that contains) the [semantic units](@) must actively (consciously) understand and distinguish between each of them, specify names ([terms](@)) that represent them, and create and maintain [curated texts](@), [definitions](@) and perhaps other stuff. +[Semantic units](@) exist because they are somehow relevant for realizing [objectives](@essif-lab) of the [party](@) that has this [knowledge](@essif-lab). Since [parties](@) rarely realize their [objectives](@essif-lab) all by themselves, they will need to find ways to communicate them (their meanings) to other [parties](@) and/or [actors](@) that work for/with them, such that the lot of them have something we might call a 'common understanding'. To realize this 'common understanding', the [owner](@essif-lab) of (the [knowledge](@essif-lab) that contains) the [semantic units](@) must actively (consciously) understand and distinguish between each of them, specify names ([terms](@)) that represent them, and create and maintain [curated texts](@), [definitions](@) and perhaps other stuff. ## Criteria -A **Semantic unit** is something that can be thought of as a basic building block of meaning or representation that exists within the 'mind' of a [party](@) (i.e., in its [knowledge](@)). Typically, [parties](@) have (at least) one [term](@) that they use to refer to that [semantic unit](@). \ No newline at end of file +A **Semantic unit** is something that can be thought of as a basic building block of meaning or representation that exists within the 'mind' of a [party](@) (i.e., in its [knowledge](@essif-lab)). Typically, [parties](@) have (at least) one [term](@) that they use to refer to that [semantic unit](@). \ No newline at end of file diff --git a/docs/terms/semantics.md b/docs/terms/semantics.md index 43a04967f3..b6b9da0c3c 100644 --- a/docs/terms/semantics.md +++ b/docs/terms/semantics.md @@ -23,7 +23,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Semantics ### Summary -We use the term **semantics** to refer to the mapping between (tangible) [terms](@) and (intangible) [concepts](@) (their meaning, the ideas behind it). Semantics are scoped, i.e. every [scope](@) has its own semantic mapping. This implies that every [party](@) has - and maintains - its own (subjective) semantics, which is its subjective mapping of a set of terms onto the concepts/ideas in its [knowledge](@). The (erroneous) assumption that [parties](@) would (automagically) share a semantics is the cause of many misunderstandings, and hence should be identified and deleted as soon as possible. +We use the term **semantics** to refer to the mapping between (tangible) [terms](@) and (intangible) [concepts](@) (their meaning, the ideas behind it). Semantics are scoped, i.e. every [scope](@) has its own semantic mapping. This implies that every [party](@) has - and maintains - its own (subjective) semantics, which is its subjective mapping of a set of terms onto the concepts/ideas in its [knowledge](@essif-lab). The (erroneous) assumption that [parties](@) would (automagically) share a semantics is the cause of many misunderstandings, and hence should be identified and deleted as soon as possible. In the [terminology pattern](pattern:terminology@), the [relation](@) `refers to` from [scoped term](@) to [concept](@) represents the semantics of [scoped terms](@). diff --git a/docs/terms/tag.md b/docs/terms/tag.md index 1b91bd2651..33e14e35b6 100644 --- a/docs/terms/tag.md +++ b/docs/terms/tag.md @@ -25,7 +25,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? ### Summary A **Tag** is an alphanumeric string that satisfies the [regex](@) `[a-z0-9_-]+`, and that is used to identify [scopes](@) (so called 'scopetags'), group [terms](@) (so called 'grouptags'), or identify a specific version of a [terminology](@) (so called 'versiontags') from within a specific [scope](@). -Scopetags [identify](@) a [scope](@) (from within a given [scope](@)), and hence can be used (within that given [scope](@)) to disambiguate [terms](@). For example, `essif-lab:term` is an [identifier](@) for the [concept](@) that within the [scope](@) [identified](@) by the scopetag `essif-lab` is referred to by the [term](@) 'term'. +Scopetags identify a [scope](@) (from within a given [scope](@)), and hence can be used (within that given [scope](@)) to disambiguate [terms](@). For example, `essif-lab:term` is an identifier for the [concept](@) that within the [scope](@) identified by the scopetag `essif-lab` is referred to by the [term](@) 'term'. Grouptags may be used within a [scope](@) to tag various sorts or [semantic units](@) such as [terms](@), [concepts](@), [patterns](@) and the like. One can then say that this grouptag represents the group of [semantic units](@) that are associated with that tag. This may be used for different purposes. One example is to tag every term that is part of a [pattern](@) with a pattern-specific tag. diff --git a/docs/terms/term-identifier.md b/docs/terms/term-identifier.md index 6e53294bbe..055c49f8ed 100644 --- a/docs/terms/term-identifier.md +++ b/docs/terms/term-identifier.md @@ -4,7 +4,7 @@ termType: concept isa: identifier bodyFile: /specs/syntax/21-term-identifiers.md glossaryTerm: Term Identifier -glossaryText: "a [text](identifier@), of the form `@`, that is used for [identifying](@) a [semantic unit](@) within a designated [terminology](@)." +glossaryText: "a [text](identifier@), of the form `@`, that is used for identifying a [semantic unit](@) within a designated [terminology](@)." glossaryNotes: - "If `@` is omitted, the current (or default) [terminology](@) is assumed." formPhrases: [ "term-identifier{ss}" ] diff --git a/docs/terms/term-selection-instruction.md b/docs/terms/term-selection-instruction.md index 955bee2905..64ee592fc0 100644 --- a/docs/terms/term-selection-instruction.md +++ b/docs/terms/term-selection-instruction.md @@ -36,4 +36,4 @@ The [MRGT](@) interprets the [term selection instructions](@) in the sequence in ## Notes - Term selection instructions are essential for ensuring that the terminological assets in a scope are relevant, accurate, and comprehensive. -- Curators use term selection instructions to tailor the terminology to the specific needs and [objectives](@) of the community or project. +- Curators use term selection instructions to tailor the terminology to the specific needs and [objectives](@essif-lab) of the community or project. diff --git a/docs/terms/term-type.md b/docs/terms/term-type.md index 5cffae6639..1a44ff41d6 100644 --- a/docs/terms/term-type.md +++ b/docs/terms/term-type.md @@ -7,7 +7,7 @@ term: term-type termType: concept isa: identifier glossaryTerm: Term Type -glossaryText: "a [text](identifier@) that [identifies](@) a particular *kind* of [semantic unit](@) within a particular [scope](@). Examples include `concept`, `relation`, `pattern` (or `mental-model`)." +glossaryText: "a [text](identifier@) that identifies a particular *kind* of [semantic unit](@) within a particular [scope](@). Examples include `concept`, `relation`, `pattern` (or `mental-model`)." grouptags: [ ] formPhrases: [ "term-type{ss}", "termtype{ss}" ] # Curation status @@ -22,7 +22,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Term Type -A **Term Type** is an [identifier](@) that is used to [identify](@) a particular *kind* of [semantic unit](@). Examples include `concept`, `relation`, `pattern` (or `mental-model`). +A **Term Type** is an identifier that is used to identify a particular *kind* of [semantic unit](@). Examples include `concept`, `relation`, `pattern` (or `mental-model`). The ability to specify a [term type](@) as part of a [term](@) mimics the common practice of disambiguating semantically overloaded [terms](@). With in the context of [TEv2](@), this is currently not used. diff --git a/docs/terms/term.md b/docs/terms/term.md index 24a01025ed..f7c66c2780 100644 --- a/docs/terms/term.md +++ b/docs/terms/term.md @@ -7,7 +7,7 @@ term: term termType: concept isa: identifier glossaryTerm: -glossaryText: "a word or phrase (i.e.: text) that is used to represent ([identify](@)) a specific [semantic unit](@) (in some [scope](@))." +glossaryText: "a word or phrase (i.e.: text) that is used to represent (identify) a specific [semantic unit](@) (in some [scope](@))." grouptags: [ ] formPhrases: [ "term{ss}", "word{ss}", "phrase{ss}" ] # Curation status @@ -23,7 +23,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Term ### Summary -A **Term** is a word or phrase (i.e.: text) that is used to represent ([identify](@)) a specific [semantic unit](@), e.g. a [concept](@), [relation](@) or [mental model](@), in a particular [scope](@): +A **Term** is a word or phrase (i.e.: text) that is used to represent (identify) a specific [semantic unit](@), e.g. a [concept](@), [relation](@) or [mental model](@), in a particular [scope](@): - a single [term](@) may (and typically does) have different meanings ([semantics](@)) in different [scopes](@)/contexts. For example, in the context of a beauty-salon, the term 'nail' has a different meaning than in the context of constructing buildings. - different [terms](@) (in the same, or different [scopes](@)/contexts) may have the same meaning (i.e. represent the same [concept](@) ([synonymity](https://en.wikipedia.org/wiki/Synonym), [alias](https://www.merriam-webster.com/dictionary/alias)). @@ -42,7 +42,7 @@ Understanding words or phrases uttered by others requires that we are able to 't ### Criteria -A term is a word or phrase (i.e.: text) that is used in at least one [scope](@)/context, in each of which it represents (and [identifies](@))) one specific [semantic unit](@) that is part of the [knowledge](@) of the [community](@) that [owns](@) that [scope](@). +A term is a word or phrase (i.e.: text) that is used in at least one [scope](@)/context, in each of which it represents (and identifies)) one specific [semantic unit](@) that is part of the [knowledge](@essif-lab) of the [community](@) that [owns](@essif-lab) that [scope](@). ### Notes diff --git a/docs/terms/termid.md b/docs/terms/termid.md index 5c9c393608..eff01903d0 100644 --- a/docs/terms/termid.md +++ b/docs/terms/termid.md @@ -7,7 +7,7 @@ term: termid termType: concept isa: identifier glossaryTerm: -glossaryText: "a text of the form `:` that serves as an unambiguous [identifier](@) for a specific [semantic unit](@) in some given [scope](@)." +glossaryText: "a text of the form `:` that serves as an unambiguous identifier for a specific [semantic unit](@) in some given [scope](@)." grouptags: [ ] formPhrases: [ "termid{ss}", "term-id{ss}" ] # Curation status @@ -22,7 +22,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Term-ID -A **Term-ID** is a text of the form `:` that serves as an unambiguous [identifier](@) for a specific [semantic unit](@) in some given [scope](@), where `` represents a [term type](@), and `` is a [term](@). +A **Term-ID** is a text of the form `:` that serves as an unambiguous identifier for a specific [semantic unit](@) in some given [scope](@), where `` represents a [term type](@), and `` is a [term](@). The reason for having term-ids is that a [term](@) may be ambiguous within (a [terminology](@)) of some [scope](@). For example, terms such as `jurisdiction`, `identifier`, etc. could refer to a [concept](@), but equally well to a [mental model](@), or a [relation](@) that links some [concepts](@). diff --git a/docs/terms/terminology-identifier.md b/docs/terms/terminology-identifier.md index e944f91d93..d7f38cb323 100644 --- a/docs/terms/terminology-identifier.md +++ b/docs/terms/terminology-identifier.md @@ -4,7 +4,7 @@ termType: concept isa: identifier bodyFile: /specs/syntax/31-terminology-identifiers.md glossaryTerm: Terminology Identifier -glossaryText: "a [text](identifier@), of the form `:`, that [identifies](@) a [terminology](@) from within a particular [scope](@), and can also be used to find the [MRG](@) file (in the [glossarydir](@) of that same [scope](@)) that contains [entries](mrg-entry@) for every [term](@) contained in that [terminology](@)." +glossaryText: "a [text](identifier@), of the form `:`, that identifies a [terminology](@) from within a particular [scope](@), and can also be used to find the [MRG](@) file (in the [glossarydir](@) of that same [scope](@)) that contains [entries](mrg-entry@) for every [term](@) contained in that [terminology](@)." glossaryNotes: - "If `` and/or `:` is omitted, their values are taken be the current (or default) ones." grouptags: [ ] diff --git a/docs/terms/terminology-process.md b/docs/terms/terminology-process.md index 6c6ccb52ae..ddd0afc11f 100644 --- a/docs/terms/terminology-process.md +++ b/docs/terms/terminology-process.md @@ -22,14 +22,14 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Terminology Process -The eSSIF-Lab **terminology process** is a method for recognizing misunderstandings as such, and creating or maintaining [definitions](@) that resolve them. It helps [parties](@) that work together to realize certain [objectives](@) (in some [scope](@)) by enabling them to establish a [terminology](@) that has the property that every party has the same understanding of each of its [terms](@), and that each of these [terms](@) is relevant for the realizations of these [objectives](@).xx +The eSSIF-Lab **terminology process** is a method for recognizing misunderstandings as such, and creating or maintaining [definitions](@) that resolve them. It helps [parties](@) that work together to realize certain [objectives](@essif-lab) (in some [scope](@)) by enabling them to establish a [terminology](@) that has the property that every party has the same understanding of each of its [terms](@), and that each of these [terms](@) is relevant for the realizations of these [objectives](@essif-lab).xx ## Prerequisites This process focuses on the creation and maintenance of qualitatively good definitions, i.e. [definitions](@) that satisfy the following quality criteria: - the [definition](@) is associated with a [scope](@) that is explicitly defined, i.e. any [party](@) can unambiguously determine whether or not the definition applies; - the [criteria](https://www.lexico.com/definition/criterion) of the definition are well-formed, meaning that all stakeholders make the same judgments c.q. reach the same conclusions when using these criteria in a given situation that is relevant within the scope. -- the definition is relevant, which means that stakeholders have identified cases that demonstrate how the use of this definition helps them realize their [objectives](@) and/or address issues that prevent them from doing so, or they have agreed that relevance is obvious. +- the definition is relevant, which means that stakeholders have identified cases that demonstrate how the use of this definition helps them realize their [objectives](@essif-lab) and/or address issues that prevent them from doing so, or they have agreed that relevance is obvious. - there is consensus between the stakeholders regarding the [term](@) - the actual word or phrase - that is to be used to refer to (unidentified, or arbitrary, or specific) [entities](@) that satisfy the criterion. This process does not prohibit that definitions may satisfy other criteria, or be associated with other attributes so that they may become better suited to serve other purposes as well. For example, a definition that is to be used in an educational context may be required to come with examples, and/or explanations about why the distinction is made as it is. @@ -38,9 +38,9 @@ This process does not prohibit that definitions may satisfy other criteria, or b The process (step) for creating and/or changing a definition starts with a request to this end. -Processing this request, which includes deciding whether or not to service it in the first place, should be done by one or more stakeholders of the term. After all, they are the ones that contribute to the realization of the [objectives](@) for which the term was defined, and hence need to ensure they can (keep) work(ing) with it.[^note] +Processing this request, which includes deciding whether or not to service it in the first place, should be done by one or more stakeholders of the term. After all, they are the ones that contribute to the realization of the [objectives](@essif-lab) for which the term was defined, and hence need to ensure they can (keep) work(ing) with it.[^note] -This doesn't mean that others Of course, it doesn't mean that others cannot have good ideas, but whether or not that is the case is for the stakeholders to decide. Too often do we see e.g. people adding terms to a glossary for purposes that don't serve the [objectives](@). +This doesn't mean that others Of course, it doesn't mean that others cannot have good ideas, but whether or not that is the case is for the stakeholders to decide. Too often do we see e.g. people adding terms to a glossary for purposes that don't serve the [objectives](@essif-lab). We do not prescribe any specific way for stakeholders to process the request. We only state the conditions that anyone can check to see if the work is done, which is the case when the definition qualifies as a 'good definition' according to the criteria stated above. Thus, stakeholders can do whatever they deem appropriate, as long as the end result satisfies these criteria. @@ -68,11 +68,11 @@ A common way to foster mutual understanding is to define terms. The idea is that We propose an approach that focuses on the effects that we want definitions to have in discussions, the most important one of which is that people that use a term in a discussion agree as to what is, and what is not an instance of the term, and that this agreement extends to multiple, different situations. -Note that this effect is limited to the scope of a discussion, which would allow the same term to have a different meaning/interpretation in other discussions (as is common practice). Terminologies however are typically meant to be used in large(r) scopes, where people pursue specific [objectives](@). For example, a terminology may be needed for creating, maintaining and using (a set of) standards, or an IT system. +Note that this effect is limited to the scope of a discussion, which would allow the same term to have a different meaning/interpretation in other discussions (as is common practice). Terminologies however are typically meant to be used in large(r) scopes, where people pursue specific [objectives](@essif-lab). For example, a terminology may be needed for creating, maintaining and using (a set of) standards, or an IT system. -We postulate that the use of a specific terminology is limited to a (set of) scope(s) within which specific [objectives](@) are being pursued. Doing this allows us to discuss the relevance of terms within a scope: a definition that does not help people to realize the [objectives](@) of the scope has no place in the terminology of that scope. Conversely, any distinction that helps people to realize one or more of the [objectives](@) should be made explicit, and assigned a term. This makes terminology the invaluable asset that we feel it should be. +We postulate that the use of a specific terminology is limited to a (set of) scope(s) within which specific [objectives](@essif-lab) are being pursued. Doing this allows us to discuss the relevance of terms within a scope: a definition that does not help people to realize the [objectives](@essif-lab) of the scope has no place in the terminology of that scope. Conversely, any distinction that helps people to realize one or more of the [objectives](@essif-lab) should be made explicit, and assigned a term. This makes terminology the invaluable asset that we feel it should be. -Within this document, we use the term 'stakeholder (of a terminology)' to refer to a person that contributes to realizing [objectives](@) of some scope for which that terminology exists, or is being developed/maintained. Having this notion allows us to distinguish between people that have a working interest in the terms defined therein, and those that do not. We will only allow stakeholders of a terminology to participate in discussions to create, update or delete terms therein. +Within this document, we use the term 'stakeholder (of a terminology)' to refer to a person that contributes to realizing [objectives](@essif-lab) of some scope for which that terminology exists, or is being developed/maintained. Having this notion allows us to distinguish between people that have a working interest in the terms defined therein, and those that do not. We will only allow stakeholders of a terminology to participate in discussions to create, update or delete terms therein. Terms that are defined in a terminology use usually classifications of things we know to exist. For example, 'cup' represents a class of things that have specific characteristics. If stakeholders want to agree on what a cup is, they should devise a criterion that allows them to distinguish between things that are a cup, and things that are not. One part of a definition should thus be a criterion by which any stakeholder can make this judgment. @@ -80,7 +80,7 @@ We say that a criterion is 'well-formed' if it has the property that all stakeho Criteria that are well-formed in one context may not be well-formed in another context. In the context of a café in which some students want to converse while drinking a cup of coffee, the criterion 'anything that can contain coffee and that a person can drink out of' would be well-formed. In the context of a space station in which some astronauts want to converse while drinking a cup of coffee, this criterion may not be appropriate as it would include cups that spill their coffee because of the lack of gravity[^NASA]. Therefore, another part of a definition should be a reference to the scope(s) within which it is applied. -We say that a criterion is 'relevant' if it has the property that all stakeholders agree – possibly for different reasons – that the distinction it makes helps them to realize their [objectives](@) and/or address issues that prevent them from doing so. Testing for this property (i.e. asking the stakeholders whether or not they think it helps to realize [objectives](@) and/or address issues[^test]) ensures that the criterion does not need to make distinctions that, while relevant in other scopes, are irrelevant in the scope in which it is established. +We say that a criterion is 'relevant' if it has the property that all stakeholders agree – possibly for different reasons – that the distinction it makes helps them to realize their [objectives](@essif-lab) and/or address issues that prevent them from doing so. Testing for this property (i.e. asking the stakeholders whether or not they think it helps to realize [objectives](@essif-lab) and/or address issues[^test]) ensures that the criterion does not need to make distinctions that, while relevant in other scopes, are irrelevant in the scope in which it is established. Obviously, criteria that are relevant in one context may not not be relevant in another context. For example, in the context of a chic restaurant in which some students want to have a good time, conversing with one another and drinking glasses of wine, the criterion for a glass: 'anything that can contain wine and that a person can drink out of' would be relevant. In the context of that same restaurants in which the same students want to taste wine as part of their training to become a sommelier, this criterion is no longer relevant. @@ -94,4 +94,4 @@ Obviously, criteria that are relevant in one context may not not be relevant in [^NASA]: NASA has designed so-called 'space cups' for drinking liquids such a s coffee in the International Space Station ISS. See https://www.nasa.gov/mission_pages/station/research/experiments/2029.html. -[^test]: If you test a criterion by simply asking stakeholders to assert that the criteria is relevant, you run the [risk](@) that they have their own interpretation of the term 'relevant'. In order to mitigate this [risk](@), you should either define 'relevance (of a criterion that is used in a definition)' as the property of helping stakeholders in the scope of that definition to to realize their [objectives](@) and/or address issues that prevent them from doing so, or you should ask the question as we stated here. \ No newline at end of file +[^test]: If you test a criterion by simply asking stakeholders to assert that the criteria is relevant, you run the [risk](@) that they have their own interpretation of the term 'relevant'. In order to mitigate this [risk](@), you should either define 'relevance (of a criterion that is used in a definition)' as the property of helping stakeholders in the scope of that definition to to realize their [objectives](@essif-lab) and/or address issues that prevent them from doing so, or you should ask the question as we stated here. \ No newline at end of file diff --git a/docs/terms/terms-community.md b/docs/terms/terms-community.md index d275f68446..342ccdc93e 100644 --- a/docs/terms/terms-community.md +++ b/docs/terms/terms-community.md @@ -25,12 +25,12 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? ### Summary A **terms-community** is a [community](@) that maintains a [terminology](@) for the purpose of its members to avoid misunderstandings in their collaborations. They do so by: -- [defining](@) a set of [terms](@) that are specific to them, and that are relevant for its members to interact as they seek to realize their individual [objectives](@). +- [defining](@) a set of [terms](@) that are specific to them, and that are relevant for its members to interact as they seek to realize their individual [objectives](@essif-lab). - determining which [terms](@) they will be using within their [community](@) in the meaning as [defined](@) by others. -Note that a terms-community (whose [objectives](@) are limited to maintaining a [terminology](@)) would typically be a part of a larger [community](@) with other (additional) [objectives](@), and the [terminology](@) that is being maintained might well be devised to serve the realization of these [objectives](@). +Note that a terms-community (whose [objectives](@essif-lab) are limited to maintaining a [terminology](@)) would typically be a part of a larger [community](@) with other (additional) [objectives](@essif-lab), and the [terminology](@) that is being maintained might well be devised to serve the realization of these [objectives](@essif-lab). -A terms-community would typically create and (automatically) publish a [glossary](@) that contains all terms that it curates, i.e. both defined by themselves as by others. Such a document then serves as the authoritative register for terminology within the [scope](@) of the (larger) [community](@) as it seeks to realize its community-[objectives](@). Also, this [glossary](@) is useful for non-members, as they will be enabled to understand what is being communicated within, or from that [community](@). +A terms-community would typically create and (automatically) publish a [glossary](@) that contains all terms that it curates, i.e. both defined by themselves as by others. Such a document then serves as the authoritative register for terminology within the [scope](@) of the (larger) [community](@) as it seeks to realize its community-[objectives](@essif-lab). Also, this [glossary](@) is useful for non-members, as they will be enabled to understand what is being communicated within, or from that [community](@). The [terminology pattern](pattern:terminology@) provides an overview of how this concept fits in with related concepts. @@ -47,4 +47,4 @@ a [community](@) that maintains a [terminology](@) for the purpose of its member ## Notes -- The set of parties that form one terms-community can also form a different terms-community for the realization of other [objectives](@). For example, the members of the [ToIP CTWG](https://wiki.trustoverip.org/pages/viewpage.action?pageId=65700) have one set of [objectives](@) related to the [definition](@) and curation of terminology-related [terms](@), procedures for creating good [definitions](@) etc. That same group of [parties](@) might also serve the purposes of [identifying](@) [terms](@) that are commonly used throughout ToIP, and ensuring that these [terms](@) are properly defined and curated. This set of [parties](@) will thus form multiple [terms-communities](@). +- The set of parties that form one terms-community can also form a different terms-community for the realization of other [objectives](@essif-lab). For example, the members of the [ToIP CTWG](https://wiki.trustoverip.org/pages/viewpage.action?pageId=65700) have one set of [objectives](@essif-lab) related to the [definition](@) and curation of terminology-related [terms](@), procedures for creating good [definitions](@) etc. That same group of [parties](@) might also serve the purposes of identifying [terms](@) that are commonly used throughout ToIP, and ensuring that these [terms](@) are properly defined and curated. This set of [parties](@) will thus form multiple [terms-communities](@). diff --git a/docs/terms/tev2-toolbox.md b/docs/terms/tev2-toolbox.md index db3e4173a7..2d406aa7a4 100644 --- a/docs/terms/tev2-toolbox.md +++ b/docs/terms/tev2-toolbox.md @@ -43,7 +43,7 @@ The tools within the TEv2 Toolbox serve multiple functions, including: 5. [MRGT](@): Enables the generation of [MRDs](@) from [curated texts](@) (and existing [MRGs](@) from other [scopes](@)). 6. [ICT](@): Ensures the conformity of various files to their [TEv2 specifications](/docs/specs/files), maintaining data integrity. -The TEv2 Toolbox empowers [curators](@) to streamline the terminology management process, ensuring the creation of accurate, accessible, and well-structured terminological assets that align with the [objectives](@) of the community or project involved. +The TEv2 Toolbox empowers [curators](@) to streamline the terminology management process, ensuring the creation of accurate, accessible, and well-structured terminological assets that align with the [objectives](@essif-lab) of the community or project involved. ## Examples diff --git a/docs/terms/versiontag.md b/docs/terms/versiontag.md index 83137eafaf..e2b2b588eb 100644 --- a/docs/terms/versiontag.md +++ b/docs/terms/versiontag.md @@ -7,7 +7,7 @@ term: versiontag termType: concept isa: tag glossaryTerm: -glossaryText: "a [tag](@) that is used to [identify](@) a specific version of a [terminology](@) from within a specific [scope](@)." +glossaryText: "a [tag](@) that is used to identify a specific version of a [terminology](@) from within a specific [scope](@)." grouptags: [ ] formPhrases: [ "versiontag{ss}", "version tag{ss}", "vsntag{ss}" ] # Curation status @@ -23,12 +23,12 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? # Versiontag ### Summary -A **Versiontag** is a [tag](@) that is used to [identify](@) a specific version of a [terminology](@) from within a specific [scope](@). It may have various forms, and would typically be chosen such that it comes in handy with the tools that the [terms community](@) has decided to use to curate that [scope](@). +A **Versiontag** is a [tag](@) that is used to identify a specific version of a [terminology](@) from within a specific [scope](@). It may have various forms, and would typically be chosen such that it comes in handy with the tools that the [terms community](@) has decided to use to curate that [scope](@). The [terminology pattern](pattern:terminology@) provides an overview of how this concept fits in with related concepts. ### Criteria -A **Versiontag** (of/within a [scope](@)) is a [tag](@) that is used within that [scope](@) to [identify](@) a specific version of that [scope's](@) [terminology](@). The alphanumeric string satisfies the [regex](@) `[a-z0-9_-]+`. +A **Versiontag** (of/within a [scope](@)) is a [tag](@) that is used within that [scope](@) to identify a specific version of that [scope's](@) [terminology](@). The alphanumeric string satisfies the [regex](@) `[a-z0-9_-]+`. ### Examples Examples of versiontags are `v0.1`, `latest`, `afa65fe9` (a (git) commit-hash), etc.