§ Terminology Governance Guide
Specification Status: v0.6 Draft
Latest Draft:
https://github.com/henkvancann/terminology-governance-guide
Editors:
Contributors:
- Neil Thomson
- Darrell O’Donnell, Continuum Loop Inc.
- Rieks Joosten
- Drummond Reed
- Ed Eykholt
- Kor Dwarshuis
- Kevin Griffin, GLEIF
- Daniel Hardman, Provenant, Inc
Participate:
In the Guide:
| TBW |
- Template improvements:
§ Status of This Memo
The document structure is based on a template specification for ToIP.
The home Github repository from which this Guide is currently generated is https://github.com/trustoverip/ctwg-terminology-governance-guide.
This document is a guide for spec authors and a discription of how the tooling works. The normative section is aimed at developers of the specification template mentioned above.
§ Copyright Notice
This specification is subject to the OWF Contributor License Agreement 1.0 - Copyright available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright.
If source code is included in the specification, that code is subject to the Apache 2.0 license unless otherwise marked. In the case of any conflict or confusion within this specification between the OWF Contributor License and the designated source code license, the terms of the OWF Contributor License shall apply.
These terms are inherited from the Concepts and Terminology Working Group at the Trust over IP Foundation. Working Group Home
§ Terms of Use
These materials are made available under and are subject to the OWF CLA 1.0 - Copyright & Patent license. Any source code is made available under the Apache 2.0 license.
THESE MATERIALS ARE PROVIDED “AS IS.” The Trust Over IP Foundation, established as the Joint Development Foundation Projects, LLC, Trust Over IP Foundation Series (“ToIP”), and its members and contributors (each of ToIP, its members and contributors, a “ToIP Party”) expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL ANY ToIP PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THESE MATERIALS, ANY DELIVERABLE OR THE ToIP GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
§ RFC 2119
The Internet Engineering Task Force (IETF) is a large open international community of network designers, operators, vendors, and researchers concerned with the evolution of the Internet architecture and to ensure maximal efficiency in operation. IETF has been operating since the advent of the Internet using a Request for Comments (RFC) to convey “current best practice” to those organizations seeking its guidance for conformance purposes.
The IETF uses RFC 2119 to define keywords for use in RFC documents; these keywords are used to signify applicability requirements. ToIP has adapted the IETF RFC 2119 for use in the Terminology Specification Guide, and therefore its applicable use in ToIP-compliant governance frameworks.
The RFC 2119 keyword definitions and interpretation have been adopted. Those users who follow these guidelines SHOULD incorporate the following phrase near the beginning of their document: The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
RFC 2119 defines these keywords as follows:
- MUST: This word, or the terms “REQUIRED” or “SHALL”, mean that the definition is an absolute requirement of the specification.
- MUST NOT: This phrase, or the phrase “SHALL NOT”, means that the definition is an absolute prohibition of the specification.
- SHOULD: This word, or the adjective “RECOMMENDED”, means that there MAY exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course.
- SHOULD NOT: This phrase, or the phrase “NOT RECOMMENDED” means that there MAY exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications SHOULD be understood, and the case carefully weighed before implementing any behavior described with this label.
- MAY: This word, or the adjective “OPTIONAL”, means that an item is truly optional. One vendor MAY choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor MAY omit the same item.
Requirements include any combination of Machine-Testable Requirements and Human-Auditable Requirements. Unless otherwise stated, all Requirements MUST be expressed as defined in RFC 2119.
- Mandatories are Requirements that use a MUST, MUST NOT, SHALL, SHALL NOT or REQUIRED keyword.
- Recommendations are Requirements that use a SHOULD, SHOULD NOT, or RECOMMENDED keyword.
- Options are Requirements that use a MAY or OPTIONAL keyword.
An implementation which does not include a particular option MUST be prepared to interoperate with other implementations which include the option, recognizing the potential for reduced functionality. As well, implementations which include a particular option MUST be prepared to interoperate with implementations which do not include the option and the subsequent lack of function the feature provides.
§ Foreword
This publicly available specification was approved by the ToIP Foundation Steering Committee on [dd month yyyy must match date in subtitle above]. The ToIP permalink for this document is:
[permalink for this deliverable: see instructions on this wiki page]
The mission of the Trust over IP (ToIP) Foundation is to define a complete architecture for Internet-scale digital trust that combines cryptographic assurance at the machine layer with human accountability at the business, legal, and social layers. Founded in May 2020 as a non-profit hosted by the Linux Foundation, the ToIP Foundation has over 400 organizational and 100 individual members from around the world.
Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement.
This document was prepared by the ToIP Concepts and Terminology Working Group.
Any feedback or questions on this document should be directed to https://github.com/trustoverip/specification/issues
THESE MATERIALS ARE PROVIDED “AS IS.” The Trust Over IP Foundation, established as the Joint Development Foundation Projects, LLC, Trust Over IP Foundation Series (“ToIP”), and its members and contributors (each of ToIP, its members and contributors, a “ToIP Party”) expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL ANY ToIP PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THESE MATERIALS, ANY DELIVERABLE OR THE ToIP GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
§ Executive Summary
Governance and user manual of our concepts & terminology for groups/scopes within ToIP and ToIP as a whole.
§ Conclusion
Governing terminology is akin to herding cats — seemingly impossible. We tried our best.
§ Introduction
The Terminology Governance Guide is an up-to-date guide of assimilated expertise within Trust-over-IP with regard to Concepts and Terminology. It’s objective is to offer a comprehesive description of various data stores, tools and processes to manage terminology in a consistent and reproducable manner. The process intents to keep track of who did what in which role.
Authors of concepts & terminology use the Guide to produce internally and externally consistent specifications, they could look up how to reference term internally (refer to definitions within the own scope) and externally: refer to definitions externally, either within the own umbrella organisation (ToIP) other totally external (e.g. IETF).
Curators of concepts & terminology have an insight were in the process consistency of terminology is validated by hand or by tools that verify the structure, defs, refs, abbreviation and aliasses that authors might use.
There is a brief history to the Guide in the annex.
§ Scope
This Guide uses tools currently in use and proven open-source technology as much as possible:
- git and github for version control, issue-handling and project management in the own github repo
- GitHub user management
- The existing Slack group CTWG for discussions
- Use of github wiki-based source management of terminologies
- Archive obsolete sources of terminology
- Reuse harvesting / consensus creation tools that are available and anticipate improvements of those
- Connect to TEv2 step by step
- Use Spec-Up / specification template and anticipate improvements of this
§ Roadmap
How do TEv2, Spec-Up and KERISSE relate? The goal is unification and we prevent reinventing tools that are already in place.
The issue of unification is currently open, but it might be solved with the design of this Guide. A sequence numbered roadmap to unification (presumming that that’s the goal) can be found below.
| TBW |
§ Terminology design aids
"Please let me just write my document and add some glossary items and we’re done. We skip all the academic hassle about meaning, concepts, artefacts and what have we. Let’s get some work done!”
§ Do not proceed if…
Cliff hanger! First, do you recognize the emotional remarks above (under “Terminology design aids”)?
Why can’t we give in? Simply skip the nerdy stuff? The reason is devastatingly basic:
If communication and understanding each other were just that easy, we could leave the hard part out.
But we can’t skip the design of terminology if we want to convey a (new) concept and make sense for other people.
Since we’ve just told you, you can only knowingly neglect the duty of designing proper terminology.
Do not proceed with this chapter if you’re a sender, only sending or broadcasting.
Because you need to understand first, to be understood.
§ One word solution (trailer)
Hold your breath for the magic word, the solution for everything in terminology design!
But first we have to make a small, but very important detour! And that is:
why are we doing this?!
§ Who benefits
For who are we doing this, what can this person do with it and what is the unique result?
Are you going to be faster, better, easier-going in writing texts? Will you be better understood by a larger audience?
The brief answer is yes. Just imprint this paragraph for more backing:
§ Why are we doing this?
Authors and curators of texts can follow this guideline for terminology design in order to create their terminology, invent smart criteria to distinguish their concepts from others, thereby identifying their own concepts clearer, understand their peers better and finally be understood better and quicker by others.
Oops the magic word is in there! Have you been able to locate it? No? Keep going!
§ Reality check
Most term definitions in the world do not comply with the distinguishing-criteria rule, and that’s the uniqueness of this Guide: it’s easy to follow and the result is an immensely improved terminology.
This guide won’t be as comprehensive as the TNO Terminology Design. However, we offer the best of both worlds, resulting in: simplicity and speed and about eighty percent the right way how it should be done.
Before we’ll share the all-encompassing solution in just one word, we’ll lay out the step-by-step to get your terminology done.
§ Iterate through concepts
The idea is that anyone willing to explain some concepts by (first) understanding the perception of the receiving party will go through this loop for every term that is unclear, conflates, or is otherwise not fully understood.
At least one clear generally applicable criterium should come out of this step-by-step per term.
Tada! Our matching guidelines are:
- Start writing your objectives and ideas, and identify the concepts behind the terms you use (why-what is it?)
- Write the concept in a specific way: formulate criteria (why-how-what is good?) when you expect confusion to arise
- As long as a term is not understood by the target group: replace it with your criteria (why-how?)
- As soon as it’s understood: define the term with those criteria and replace the criteria in the text with the term. (why-how?)
§ Example: Health Care intake
Although we inevitably introduce some unexplained terms with an example, here’s an example:
§ Step 1
In the digital identity field you might want to write a vision document on how Self-Sovereign Identity could work in Health Care. One of the concepts / mechanisms within healthcare is to be absolutely sure who(se knee) is going to be operated next. You write how that’s going to work out with terms covering this reassurance: validation and verification. The concept as a whole concluded succesfully we call authentication.
§ Step 2
“Validation” and “Verification” of a visitor at the desk of the outpatient clinic are terms that might conflate with the “authentication” that needs to be succesfully fullfilled: “Is this person really who he/she says he/she is?!”
You decide to distinguish validation and verification with a criterium for verification:
it must be “an automatic digital process” to be verification.
The criterium is simple: must be an automatic digital process.
This distinguishing criterium comes in handy because validation can also be something a person does!
Decryption on a computer is verification, checking a passport by the desk officer is not.
§ Step 3
Although you wrote ‘authentication is partly done by an automatic digital process called verification’, your team members are confused by the word ‘digital’. One of them brings forward that ‘computerized’ instead of digital is clearer and the team agrees unanimously.
For the sake of the team members that weren’t present at the meeting, you leave the criteria in the text:
‘authentication is partly done by an automatic computerized process called verification’
§ Step 4
Everyone understands the criteria and the term covering the concept behind it. You could now put the term definition including the criteria in your Terminology Engine and Glossary and replace the criteria in the text with only the term used:
‘authentication is partly done by verification’
The term definition looks like this:
[[def: verification]]
~
a data item or statement may be cryptographically securely attributable to its source (party at the source end) by any recipient verifier (party at the destination end) The process must be an automatic computerized process.
End of example.
In this process and iteration you could look for over-arching or adjacent term definitions (with criteria!) that match your concept. Of this is the case, you could adopt a term definition, with or without an extra note. That’s when consensus building comes in as a spin-off of your terminology design.
§ The magic word
Still wondering what the magic word could be? No worries! Ladies and gentlemen … (drum roll) … the magic word in designing all your terms, defining them in a reproducible way so that anyone could identify your concepts, understand your ideas better and apply the word by himself or herself…… (drums hold!)…: Criteria!
A least one well-formulated criterium is what we need per term definition, or should we say we need minimally one in order to distinguish wether something is
- included or excluded from the definition
- inside or outside of the concept behind the term Criteria! It just pure magic.
Ah, happily you’re still here. We need to share a question at this stage. Remember, we’re trying to offer a simple and speedy guideline to create great terminology for your project.
Why is it so d.mn difficult to get people to write proper criteria? If the “magic word” ‘criteria’ delivers to the promise, why all the fuzz, why are nearly all definitions in the digital world without proper criteria??
Because…
- it’s work, it’s a task
- it needs practise
- it needs communication
- it needs understanding others
- it needs the dear wish to want to understand other people first, before you push to be understood.
§ The why and how of all steps
Our guidelines revisted, but now with reasons and further instructions.
§ 1. Start writing your objectives and ideas, and identify the concepts behind the terms you use
§ why writing your objectives and ideas down
You want to be understood and seek support for your plans or ideas. To guide this process, it’s good to have a reference.
§ what is “identifying a concept”?
An identifier points to something, in this case to a concept. Identification is the process of clearly describing what the concept is and defining the term that points to it.
§ 2. Write the concept in a specific way: formulate criteria when you expect confusion to arise
§ why criteria?
Another person should be able to apply wording to a certain concept and then be able to independently decide whether something falls in or out of the criterium. Example: if a stool is defined with the criterium “all furniture to comfortably sit on with exactly 3 legs from seat to each non-fixed contact point of the leg on the floor”, then anyone could (dis)qualify various instances of something to sit on that looks like a stool to many. Although you might not fully agree that a 4-legged stool is no stool according to this definition with this criterium, the fact is that it’s the generally applicable criterium that we were looking for.
§ Stools IN the criterium
§ Stools OUTSIDE the criterium
Communication, understanding and learning will sky rocket with clear criteria, invest time in them and earn time back further down the road.
Example: moving stools
If a group of people had to move every stool, but only stools, from a furniture warehouse into a large lorry without clear criteria what a stool is and isn’t, you will end up leaving stools behind and for sure bringing back half a lorry of furniture upon unloading.
§ how to formulate criteria
In text. And you could add examples to a criterium of edge cases / corner cases: what falls just in the criterium and what is just outside?
§ what are good criteria?
Criteria that are determistic and clearly distinguish something.
§ 3. As long as a term is not understood by the target group: replace it with your criteria
§ why replace terms by criteria?
Criteria can be independently applied, terms have a aledged meaning and interpretation might of terms might point to distinctive concepts. Example: move the stools into the van might be interpreted as “break out the fixed stools in the cantina and bring the remnants to the van”.
§ how to replace terms by criteria?
Simply replace the term by the sentences criteria might consist of.
Example: move the stools into the van -> move into the van all furniture to comfortably sit on with exactly 3 legs from seat to each non-fixed contact point of the leg on the floor
§ 4. As soon as it’s understood: define the term with those criteria and replace the criteria in the text with the term.
§ why put back terms
Once you’ve succesfully identified a concept for all stakeholders, it makes no sense to maintain repetitions of lengthy criteria descriptions in a text. Maitenance of the criteria is also easier with a single point of defnition.
§ how to put back terms
Be sure to create a Terminology definition with the criteria and identify this concept with the term intended.
For example:
[[def: stool, stools]]
~ furniture to comfortably sit on with exactly 3 legs from seat to each non-fixed contact point of the leg on the floor
AND then change the concept criteria in the text with the concept term:
move the [[ref: stools]]
into the van.
§ Next time
You might come across a concept that has already been identified and defined with a term + criteria:
§ Wrap up
Isn’t the magic word “Criteria” a bit cruel? It might snatch average human beings in the heart of their weakness: understanding others. Yet “mutual understanding” is needed to be able to formulate suitable criteria.
§ Move forward
Note that Terminology building is concise and extensive work. Beyond the basic terms, often defined as noun or noun phrase (e.g. “validation” and “peer to peer validation” ) we come accross these challenges:
- different styles to describe a concept: nouns, verbs, adverbs, adjectives, and relationship. E.g. validation, validator, validate, validated, valid?, validly?, validated data, validated person, validated intake, etc.
- abbreviations for example VALD, p2p-validation
- synomyms
- forms e.g. validations, Validation, Peer-to-peer Validation, etc.
§ Two for the road
- How could we incentivice people doing the hard work of proper terminology design?
Ideas are welcome.
- Never forget the magic word: Criteria!
§ Further reading
See more here:
§ How to write definitions in your terminology
- Repeat the objectives or goals of a certain community
- Discuss, communicate towards consensus about a certain concept or term
- Define the scope or mental model together
- Write criteria for which is inside or outside the reach of a certain term
Needless to say, this process is important for mutual understanding.
§ How to write criteria
- Criteria must make sense for all roles involved in the community
For example a criterium like “A self-adressing identifier is automatically a self-sovereign identifier, but not the other way around.” might not resonate with a Reader.
- Criteria should be deterministic, either to be in or out the definition
- abbrev
- a shorthand in capitals for a term. It may contain special characters. It may not contain spaces.
Criterium for not being an abbreviation: If the word is not in uppercase, in our context the word is more likely to be an alias for the term.
- Formulate edge cases: What is just included a defnition, and what is just excluded from a definition?!
E.g. X.509 could be an abbreviation, and ‘EU ID’ is not an abbreviation
A lot of adding-criteria work needs to be done, before we discuss anything like reusing definitions in another mental model. It just makes no sense to refer / link to a non-deterministic definition of somebody else, for this inherently introduces confusion: we think we are talking about the same thing, but most probably we’re not!
Some good news is that enhancement in the written version of concepts and terminology can be achieved in parallel with other activities:
- archiving old concept and glossaries
- tool development
- consensus building But unfortunately not together with referencing existing poorly-formulated definitions because that’ll put a burden on the future.
§ Towards automatic processing in github actions
Currently we allow for four types of source management tools of terminologies in ToIP context. Check them out here: | TBW Link to the chapter |.
This example uses the github.com wiki of the target repository, but the other source management options could adopt the same guidelines for designing and editing a terminology in ToIP context.
Here are a few practical rules from the originator ToIP to get these wiki terms through their equivalent github actions script, please:
- beware all new wiki items you create, lead to new .md files. Because we’d like to know about new definitions, flant them in discussions or social media: throw links!
- introduce lowercase names with spaces (they will convert into lower case names with dashes between the words)
- start with ## Definition header; example
- start with uppercase abbreviations with only the “## See” header; example
- don’t delete items (i.e. .md files) but make clear they are depreciated and / or link to the new concept / term
- don’t change or update the name of an item single handed, for it might change the concept / meaning for other people and create dead links for those who read - or link to the term. Please open an issue or a PR to discuss first.
- any other immediate updates and amendments welcome, the revisions are available for us to be able to (partially) revert if something unwanted or unexpected happens.
Have fun CRU-ing!
'* CRU=Create Read Update
§ A glossary “reads” this
| TBW this section is draft and incomplete|
Where as the wiki source management tool (or input tool) of terminology, there is no way to add metadata to the terminology.
Currently some ToIP groups use workarounds to add metadata and extra functionality to their wiki terminology, based on the combination of labelling content and extra metadata. E.g. The WebofTrust-harboured engine KERISSE regularly scrapes the the WOT-terms wiki into KERISSE, we add features and metadata through a Google Sheet, we connect relevant matching terms from related glossaries and finally we index it for the KERI Suite Search Engine (KERISSE).
| TBW |
§ Roles
This section is informative.
A clear specification of roles in- and outside an average ToIP “group” might clear up the different viewpoints people have when looking at concepts and terminology.
- minimalistic use cases for them
- then the necessary consecutive steps to get there
§ Role: ToIP glossary maintainer
Uses: Source management tool. Reads and compares concepts in text and terminology in glossaries, (for example generated by Spec-Up) to use within his/hers “own” over-arching ToIP glossary. He/she builds as much consensus around terms and concepts and promotes using the ToIP glossary as reference material.
§ Role: Specification content author, describing concepts
Focusses on content of definitions covering concepts of the group he/she belongs to. Uses: an IDE, git and a browser extension, to edit Spec-Up markdown files for his/her specific context (mental model) in a version managed environment, authenticated, to write the concept and specification and offer this as a PR. He/she uses browser extensions to check technical consistency of the links in the text and harvests a personal collection of term definitions.
§ Role: Specification terminology author, covering concepts
Focusses on term definitions covering concepts of the group he/she belongs to. Uses: an IDE, git and a browser extension, to edit Spec-Up markdown files for his/her specific context (mental model) in a version managed environment, authenticated, to write the concept and specification and offer this as a PR. He/she uses browser extensions to check technical consistency of the links in the text and harvests a personal collection of term definitions. Specification author terms that cover those concepts.
§ Role: Curator
Uses an IDE and git and browser extensions, to check logical consistency & meaning of term definition in a certain context and uses browser extensions to harvest a personal collection of term definitions, based on those recommended by the specification authors.
§ Role: Reader
Uses github.io website, reads concepts in text and terminology in glossaries, (for example generated by Spec-Up) with its own tailor-made contextual glossary that generates pop-ups here and there in the text offered.
§ Questions and usecases
| TBW |
How are the following roles supported (applies to either KERISSE or TEv2)?
- Authors of technical documents that need to reference glossaries/glossary entries
- Authors of glossary terms
- Curators of glossaries (manage changes, toolsets, etc.)
- Glossary Tech developers
- Instructors and educators for organizations creating and using glossaries and glossary terms for ToIP-related documentation?
What are the supported source document types for:
- Documents that reference glossary terms and concepts
- Authoring terms and related extended definitions, examples, and illustrations (in-depth explanations?)
- Term/Concept metadata (gdocs? JSON?)
§ Curation of Concepts vs. Terminology
Why do github action of a scope go off on ‘push’ and ‘by hand’ (and not on ‘gollum’; the latter is the wiki server)?
Because
An author why will a changed Source of the Terminology not automatically (via github actions scripts) be promulgated to the production environment of the Scope and elsewhere if other Scopes use the MRG at hand?:
because a curator has to check the content and invoke the github action script by hand.
| TBW |
Guidance on diagrams (and managing their source) would be helpful.
For example, should diagrams always be rendered and controlled as png and preferably svg, too (for presentations, etc)?
Is it feasible to offer links in diagrams and if so, can we check and repair broken links easily?
| TBW |
§ Tools landscape
People like to understand the components and structure of ToIP’s concepts and terminology machinery and its governance.
§ git and github
§ Why?
- We need to know who did what
- We need to be able to get back and link to historical (intermediate) result
§ How?
Every role that changes stuff (Create, Update or Delete) needs to be on github and sign off their work
This way:
- original sources are GitHub managed and so is the provenance of each definition
- we can track provenance carefully. This is a step towards fully managed, individually versioned glossary management tooling such as being developed with TEv2 and KERISSE.
§ Github landscape
Every group within ToIP that uses Spec-Up has a setup more or less like the following. Only WOT-terms uses a combination of wiki source management and publication in KERISSE (Still Docusaurus-based, looking into a Spec-Up variant as of Feb 2024).
Platform | Git branch | Software |
---|---|---|
github.com repo | main or ‘own choice’ | Spec-Up |
VsCode | ||
Node.js / NPM | ||
github.io pages | gh-pages | user.github.io/repo |
github actions | ||
kerific | ||
github.com wiki | master | github.com/user/repo/wiki |
github actions |
§ Flow of Writing a Specification in Spec-Up
§ Glossary Flow: Ingest - Curation - Output
By: Darrell O’Donnell, Jan 2024
§ Combining central, external and internal references to definitions
| TBW : ToIP’s position on KERISSE (a superset of terms and concepts documentation) and TEv2? |
ToIP might need both, particularly to onramp organizations leveraging ToIP.
What are the components of the following glossary/term/concept toolsets
- Github (repo, pages and wiki)
- Spec-Up
- KERISSE platform toolset
- TEv2 toolset
What features exist in both, and what is unique in each toolset? If there is overlap, how are they different (e.g., how does an author craft a link from a word in a source document to a term in a specified glossary), and how could they be combined?
What is the future of the KERISSE suite and TEv2?
| TBW |
§ Writing
In case of a specification it is important to ask yourself “Is what I write implementable?” Follow it step by step. Check all the MUSTs and SHOULDs in the normative section.
§ Readability
- numbering of paragraphs
- Informative stuff per section below the normative
§ Review and cooperation
Keep stuff in place where it was/is during the review period. When the review period is over, you could
- relocate sections and paragraphs in the most logical - of best flowing manner
- split the text over markdown files in the spec-up
./spec
folder
§ Style guide for ToIP terminology
A term that is intended to be generic SHOULD be lowercase in the glossary and in the specs and other documents that use that term. A term SHOULD only be uppercase if it is a proper noun. The only exception is an acronym. For example, the following terms are all generic nouns:
- wallet
- agent
- public key (and public-key)
- key event log (and key-event-log)
§ Transform spaces to dashes
| TBW : see guideline ToIP by Daniel Hardman for the wiki markdown-files|
§ Forms
Terminology can be defined in various forms: nouns, verbs, adjectives/adverbs, and relations(hips).
§ Example
Noun: Verifier Verb: Verify Adjective: verified (signature) Relationships: verifying
Authors are free to choose any form of a term. It’s a way to express their objectives and concepts and give meaning. Even multiple forms are welcome, which means that in your scope you COULD define the noun, the verb and a relationship. E.g. verifier, verify and veryfying.
§ Acronyms
The following terms are proper nouns or acronyms:
- ToIP
- W3C
- DIF
- X.509
- Diffie-Hellman
- KEL
§ Special characters
Notice that the Acrynom X.509
has a special character (.
) You SHOULD use special characters only if it’s crucial for the meaning of the term.
So for example not this: security@hub4issuer
but stick to guidelines above and define for example security-at-hub-for-issuer
.
§ Constants, variables and terms in coding
Sometimes acronyms in code are (partly) in lowercase (e.g. vLEI
, eID
, ind
) for various reasons. And one needs to explain those acronyms in concepts and terminology, we allow for doing so, in their original case.
§ Authors partly comply and have freedom of choice
§ Comply with
- all of the above-mentioned style guides
- the governance of terms using the current terminolgy source management tools
See the Roles section for the various subroles of an author.
§ Terminology
- proper noun
- | TBW |
§ Source Management Use Cases
Input knowledge level: You know how to create, read and update term definitions in relation to your concept or mental model. Here are some guidelines: edit wiki term definitions
§ What is this about?
This section is about the source management of term and definitions: the latest single source of truth about them in a certain scope. The elementary part is {term}.md
file that contains (spec-up extended) markdown. We offer various ways of managing these source files while keeping the overall integrity.
§ What can I do with it?
Source management culminates in the latest version of any glossary in which the term are accessible (linkable) with a permanent URL and we have a history avaiable who referered this term at what time in the past.
:::info You can reference this glossary in your own write-ups and add to the general consensus about terms at the same time. :::
§ Why source management?
We want to offer multiple ways to edit term definitions. So not wiki or markdown or github frontend but wiki and markdown and github frontend?
The end-result is always a git(hub) tracked directory with separate .md
files of a spec-up based specification. The use case are described below. The term definitions themselves use the spec-up markdown extensions syntax: def
, ref
and xref
.
Example given:
[[def: access control]]:
~ The process of granting or denying specific [[ref: request]]s for obtaining
and using information and related information [[xref: processing]] services.
§ Why not simply use a Content Management System like Wordpress??!
Just to name a few reasons:
- user management in github ecosystem instead of centralized technological island creation
- Spec-up static website generation, we don’t want introduction of databases
- Continuous Developement Continuous Integration (CDCI) versus staging by hand
- Business rules and Permanent linking made possible via Github Actions
§ For who is source management of terminology relevant?
The roles involved in the use cases are editor
, production repo
master and curator
.
One person could have more than one role.
All roles have a github user account, because we need to know
- who proposes a change on what and when this occurred.
- who changes what and when. Git keeps track for us.
He/she who has write
user rights on the target repo (TrustoverIP main glossary) can directly edit and commit the latest version. Other roles will have to adapt to those results. For example merge conflicts might arise and then need to be solved.
Further guidelines:
- editors COULD have a fork of the repo. They NEED TO have a forked target repo for option 2, 3 and 4 below.
- curators don’t need to have a user github repo, only a github user account and they use the functionality to comment on PRs.
§ How it works
Github Actions will pick up and process changes as they occur and trigger staging of chancing to the production server.
This is the process diagram:
There are two main options we have use cases for:
-
A. Wiki based = edits WITHOUT curation and PR are possible, see 1. below
-
B. PR based WITH optinal curation and mandatory PRs, see option 2, 3 and 4 below.
§ 1. Wiki
Go to the wiki of your project repo on github.com (which is controlled by master). The wiki offers edit functionality.
DEEP DIVE: This is what happens if you can straight away save the wiki pages you edit: The terms-definitions directory will be exported to a clone of the target repo wiki by the production repo
master
. The wiki (sub) repo of a github repo allows for different user right settings than the repo itself.
GitHub allows the master to configure access permissions for wikis independently of the main repository settings. Here’s how the permission settings can differ:
By default, a repository’s wiki inherits the permissions from the repository itself. This means that if someone has write access to your repository, they can also edit the wiki. However, GitHub provides an option to modify these permissions specifically for the wiki. Under the “Settings” tab for the repository, the master will find a section for the wiki where he/she can choose to either:
a. Inherit permissions from the repository, meaning those with write access to the repository can edit the wiki. b. Allow everyone with a GitHub account to edit the wiki, which makes the wiki more open, regardless of their access to the repository itself.
This flexibility allows project maintainers to either keep their wikis as collaborative spaces open to the wider GitHub community or restrict them to be consistent with the access controls applied to the source code in the repository. It’s worth noting that these settings can be changed at any time by the repository owner (master) or users with admin access to the repository.
§ CRUD
Now editors
can use the wiki of the target repo to CRU term definition. We describe separate use cases for Create, Read and Update (CRU). Delete (D) is very rare, because the history of terms should be kept available.
Curators
could add markdown comments to the sources of the wiki.
NB: Editing of the target github wiki repo on your local machine is possible but a rather strange way to manage sources of your terms definitions. But it can be done if you have the user rights: push the wiki repo to the target wiki repo. We advise to choose one of the other source management options, because it’s more direct.
After this source editing has been saved our solution also overwrites the repo file /spec/splitted-dir/{term}.md
(if present) for syncing purposes.
§ 2. Github edit
Editors go the the term definition they want to C R U on the github.com user site of the target repo (which is controlled by master).
This way editors can edit (after having forked the target repo to their own user account) the term definition and offer a PR to master. After the PR is made the curator can comment on the changes proposed and live viewable on the user account of the editor.
After this source editing have been saved our solution also overwrites the wiki repo file /{term}.md
(if present) for syncing purposes.
§ 3. Terminal - text file edit
This way editors can edit (after having cloned the target repo to their own user account). He/she uses a text editor to write changes in the separate .md file of the term and definitions directory. He/she use git on the command line to add, commit and push files to their own github user account version of the target repo. From the target repo he/she creates a PR by hand for the curator and the master to assess and eventually accept or decline. After the PR is made the curator can comment on the changes proposed and live viewable on the user account of the editor.
After this source editing have been saved our solution also overwrites the wiki repo file /{term}.md
(if present) for syncing purposes.
§ 4. IDE
An integrated Development Environment, e.g. Visual studio Code - text file edit
This way editors can edit (after having cloned the target repo to their own user account). He/she uses an IDE to write changes in the separate .md file of the term and definitions directory. He/she uses the IDE git functinality to finally create a PR on the target repo for the curator and the master to assess and eventually accept or decline. After the PR is made the curator can comment on the changes proposed and live viewable on the user account of the editor.
§ Source management of terminology wrapped up
The input is a per-term splitted directory of term md files The process : four options to make changes The end result two options to get the results accepted in the target repo and final spec-up html output: Via 1. Wiki and via 2,3,4 : PR.
All methods have full git tracing of who did what and when.
After this source editing have been saved our solution also overwrites the wiki repo file /{term}.md
(if present) for syncing purposes.
§ How it works in use cases
The rest of this chapter outlines the use cases for managing term definitions in a spec-up based specification, focusing on the roles of editors, production repo masters, and curators.
We focus on terms and definitions only. We use the term target repo for the production repo, controlled by the role master
.
§ Roles in the usecases
- Editor: Individuals proposing changes to term definitions.
- Production Repo Master (Master): Oversees the merging of PRs and has the authority to delete term definitions.
- Curator: Engages in reviewing proposed changes to enhance quality and accuracy.
§ Editing Options
§ 1. Wiki Editing
§ Create ©
- Actor: Editor
- Process:
- Navigate to the GitHub repository page of the target repo.
- Access the Wiki section via the repository’s main page menu.
- Click “New Page” to add a term, title the page with the term name, and detail the definition using markdown syntax.
- Click “Save Page” to finalize.
§ Update (U)
- Process: Similar to “Create”, but select an existing term’s page to edit.
§ Read ®
- Directly view the term’s page in the Wiki section. Mind you, this is an extra view & search option of the resulting glossary.
§ 2. GitHub Edit (via GitHub UI)
§ Create and Update (C/U)
- Actor: Editor
- Process:
- Fork the target repository to your GitHub account.
- In your fork, navigate to the
terms-definitions
directory. - To add a new term, click “Add file” > “Create new file”. To update, click on an existing
.md
file and then the pencil icon (Edit this file). - Make changes or add the new term using markdown syntax. Commit the changes to a new branch in your fork, and start a pull request on the target repo.
§ Read ®
- View the
.md
files directly in the target repository or through the proposed changes in pull requests.
§ 3. Terminal - Text File Edit
§ Create and Update (C/U)
- Actor: Editor
- Process:
- Clone your fork of the target repository to your local machine using the terminal:
git clone [Your-Fork-URL]
. - Navigate to the
terms-definitions
directory within your local repository. - Use a text editor to create a new
.md
file or update an existing one with the term definition. - Use Git commands to add (
git add .
), commit (git commit -m "your message"
), and push (git push origin main
) the changes. - Create a pull request from your GitHub fork’s page.
- Clone your fork of the target repository to your local machine using the terminal:
§ 4. IDE - Visual Studio Code Text File Edit
§ Create and Update (C/U)
- Actor: Editor
- Process:
- Clone your fork of the target repository into Visual Studio Code (VS Code) using its Git: Clone command.
- Navigate to the
terms-definitions
directory within the VS Code Explorer. - Create a new
.md
file or edit an existing one, using markdown for the term definition. - Commit the changes using the Source Control panel in VS Code, pushing them to your fork.
- Initiate a pull request via GitHub’s website from your fork to the original repository.
§ Master and Curator Actions
§ Update (U) by Master
- Process: Review, potentially edit, and merge pull requests. Manage and resolve any merge conflicts.
§ Delete (D) by Master
- Process:
- For deleting a term, remove the
.md
file or edit its content to reflect the term’s deprecation, committing with a clear rationale. Only in exceptional cases, because it’s far better to archive instead of delete. So also edit wiki term definitions. - Push the changes to the main branch and update any documentation accordingly.
- For deleting a term, remove the
§ Curator Review
- Process: Engage in PR discussions, offering feedback and suggestions to ensure clarity and correctness of term definitions.
§ Notes
- Merge conflicts may arise during the PR process, requiring coordination for resolution.
- All changes, including deletions, should be documented with clear commit messages and PR descriptions to maintain a transparent history of modifications.
§ User manual defs, refs and xrefs
§ Background
To simplify the job of tech spec construction and editing, the Technology Stack WG has adopted the Spec-Up spec editing tool which is originally a DIF open source project (here).
TrustoverIP invests in improving this tool: The normative section we call the “Spec-Up glossary tool” (SGT); to give a name to the coding project for now.
§ Objective
To offer authors and curators a hands-up guide to handle Spec-up’s syntax correctly and efficiently with regard to defs
, refs
and xrefs
. Thereby respecting the golden rule:
“try (x)ref before def”
(why?)
§ Characteristics
Why bother? Because it’s going to be a mess soon if you don’t. Terminology has a life cycle. Some concepts and its specific terminology are long lived. They reside in their field related to other concepts. Other terminologies are contemporary. Terminology can have broad application or conversely have a very specific small niche. Nevetheless, they all share these characteristics:
- The sources (definitions or defs) need to be managed, because its content is burdened with reputation
- References (or refs and xrefs) need to be managed in the digital world where creating copies is easy ands every copy for no reason whatsoever might cause confusion
- Different roles and responsibilities work with and work on a terminology. We got to keep track who did what in which role.
§ ToIP glossary
In the ToIP Technology Architecture Specification it’s a long-desired feature to add an integrated glossary. Our objective is to offer a framework to offer this in a sustainably consistent way. The Concept & Terminology work group (CTWG) should begin publishing the ToIP Glossary as its own standalone Spec-Up specification, where every entry is properly formatted and people are able to include terms from the ToIP Glossary (without having to copy those 400+ terms over into its own glossary).
Process check:
March 2024 - The feature “xref” is constructed, but not yet operational
You should visually check each def
created in a local Spec-Up document against any def
that exists in any of the remotely referenced document URLs listed in the local document (see the title
list description in your specs.json
).
To find the list look for external_specs
"external_specs": [
{
"TP": "https://trustoverip.github.io/ctwg-main-glossary/"
}
...
§ Why “try ref before def”
These are the advantages of trying ref before def:
- consensus building: if you study defs of related scopes under the same unmbrella you’ll become more knowledgable and aware about the different fields
- less work: its easier to adopt a definition with well-formed criteria than having to design one yourself
- leading by example: you refs might be copied, enforcing the reputation of the def at hand.
Keep reading for an important caveat to these advantages! (No, bring me there now)
Decide whether you’d like to adopt as is, adopt with comment or define yourself. See flow diagram
§ Functionality
For an author there are mainly three relevant functionalities.
- Spec-Up already has a basic glossary feature:
def
tags for defining glossary entries andref
tags for marking up terms in the spec that refer to def-tagged terms. Def tags only reference def tags in the same Spec-Up document. - An
xref
supports remote refs.
March 2024 - The feature “xref” is constructed, but not yet operational
- We have functionality that detects dangling
refs
anddefs
. In other words, code that checks to see that: a. any ref tag defined in the spec has a corresponding def tag for the glossary entry, and
b. every def tag defining a glossary entry has at least one ref tag pointing to it.
Supported consistency pre-cautions and reporting:
March 2024 - The feature “checks” is being constructed step-by-step, but not yet fully operational
Each def
in a local Spec-Up document that has exactly the same def
* existing in any of the remotely referenced document URLs listed in the local document (see the title
list description in your specs.json
). This is also a recomended visual check performed by authors. (Why?)
Each ref
has an existing def
. Each xref
has an existing def
in the title
d glossary.
It checks each ref
and xref
created in reference doctags
against any def
that you’re about to remove from a local file.
It signals each ref
and xref
created in reference doctags
against any def
that you’re about to change in a local file.
When a local Spec-Up document includes a certain glossary from another remote Spec-Up document, this can be considered as a statement: “we think we might be on the same page as the people that maintain this glossary”.
It’s important to make explicit that somebody in a certain role added context to a remotely referenced term definition. Or he/she has chosen to refrain from that.
§ Title (formerly “Doctag”)
§ External linking (ref)
We need the capability for all ToIP specs to use remote refs to reference a common ToIP Glossary in addition to their own internal glossary. So far an inventarisation under TSWG spec authors would be fine with that capability: they can use any term already defined in the ToIP Glossary without having to repeat it in their glossary, and they can add any term specific to their spec.
[[ref: group#phrase]]
phrase
MUST be one of term
in any of group
’s glossary.
For example, a specification that includes a ref
tag that looks like this: toip#term would reference a def tag defined in the ToIP Glossary. Similarly, a ref that looks like hxwg#term would reference a defined term in the (theoretical) HXWG glossary.
With this remote reference feature, all ToIP specifications (and any other deliverable written with Spec-Up) would be able to include linked glossary terms (including hover pop-up definitions), both from within its own glossary and from any referenced glossary in another document that also uses Spec-Up.
Mind you, this process touches group dynamics, consensus building and communication.
§ Dangers of bluntly referencing and copying
It’s important to note that team members in various roles should feel free to define a term as they wish, after studying what’s available. This is an important caveat for refercing terms.
§ Add context and metadata
March 2024 - The feature “context metadata” is in design phase, so not operational
Adopting a term from a related scope (under the ToIP umbrella) or external has the possibility for the author, curator and maybe even other team members to add context to the definition adopted. The following metadata will be (automatically as much as possible) registered:
term
, or (optional)alias
or (optional)abbreviation
of the term definition used to referenceurl
of the spec in which the term definition list is present and the name of the headercommit hash
of the term definition plus specification adoptedauthenticated github user
that adopts the term (create), changes it’s context (update) or deletes the context.
This metadata can be added:
group name
from which the term will be adoptedrole
of theauthenticated github user
in the current scope
You could add or remove:
context
which is a block of free text.
The order in which these changes take place to a terminology definition, referencing and/or commenting will be registered.
Mind you: the adopter of a term can’t delete, nor alter the original definition, present in another scope.
§ Local versus Remote references
Technically, the only difference between a local ref and a remote ref is that the former are always within the same Spec-Up document — they look like:
[[ref: term]]
The latter allow the author to reference a def in a different Spec-Up document. They look something like:
March 2024 - The feature “xref” is under testing, so not fully operational yet
[[xref: title, term]]
is a short unique tag assigned to the remote Spec-Up document containing the def for the term being referenced. So any Spec-Up document that uses remote refs would need to include a doctag section that looks something like this:
In specs.json
:
"external_specs": [
{
"<title>": "<URL>"
}
example
"external_specs": [
{
"PE": "https://identity.foundation/presentation-exchange"
},
{
"TP": "https://trustoverip.github.io/ctwg-main-glossary/"
}
...
§ Adopt, add context or define
March 2024 - The feature “context metadata” is in design phase, so not operational
Check the flow diagram of writing terminology (references) in a specification here.
§ How to adopt a term “as is”?
Local preferable
[[xref: term]]
Or remote reference
[[xref: title, term]]
Where term
is either a term, abbreviation or alias.
§ How to adopt a term with added or updated context?
March 2024 - The feature “adopt a term with context and metadata” is in design phase, so not operational
Add:
[[def: term or abbreviation or alias]]
with in the text part of the definition
[[xref: title, term]]
Reference:
[[ref: term]]
Example
Where KE
is the title
(doctag) of KERI spec in spec-up format and TP
the title of the ToIP overall glossary in spec-up.
[[def: verification]]
~ Verification in Healthcare is in between the strict [[xref: KE, verification]]
and the more loose ToIP definition [[xref: TP, verification]]. However we have the same criteria as KERI
because our system will be KERI-based.
§ How to stop adding context to an adopted term?
March 2024 - The feature “adopt a term with context and metadata” is in design phase, so not operational
Remove the local def
and change
[[ref: term]]
into [[xref: term]]
Now the term is again externally referenced “as is”.
§ Normative section
Have a look at it here and be informed that Spec-Up is a longer running open source project that’s originated in DIF. ToIP invests in improvements to it in 2024. And offers these improvements as PRs to the DIF repo.
Here we focus on the informative aspects of the technical specification: what is it, why are we programming this and how to use it.
It is possible to include references to terms from external spec-up generated specifications. To include a source you would like to pull references from include an external_specs array in your spec config. The value should be a key/value object where the key is used in the external reference below and the value is the URL of the external spec.
To include an external term reference within your spec use the following format [[xref: {title}, {term}]]
where {title}
is the title given to the spec in the specs.json
configuration file and {term}
is the term being used.
For example using the PE
spec given in this example:
{
"specs": [
{
...
"external_specs": [
{"PE": "https://identity.foundation/presentation-exchange"}
]
}
]
}
§ Internal definition (def)
definitions (def
s)
The feature “abbreviation” is under construction!
[[def: term { | abbrev}, {alias}, {alias}, ... ]]
~ Lorem Ipsum ...
Define a term
in a ToIP definition style : lower case
Optionally an alias
could be referenced. If you do so the reference MUST end up at the definition of term
. Test by simply clicking the link.
Check defs
of aliases https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md#term-references
and the working refs
here https://identity.foundation/spec-up/#term-references
An abbrev
could be defined and referenced. If you do so a seperate definition of abbrev
must be present in the document itself.
March 2024 - This feature “abbrev” is in design phase, so not operational
§ Don’t do this
[[def: term (abbrev)]] and
[[ref: phrase]]
but do this
March 2024 - This feature “abbrev” is in design phase, so not operational
[[def: term | abbrev]]
How to add an abbreviation after the term? Two ways possible:
- in the markdown, but NOT in the reference to the term: ref:
- There will be post-markdown processing available to proportionally add abbreviation
§ Internal linking (ref)
[[ref: phrase]]
phrase
MUST be one of term
, abbrev
or alias
Three ways of offering references (ref
s) to definitions (def
s) by the author of a text:
-
explicitly created by author
-
extra by default, after n occurrences or below a header of certain level
-
MUST be done in the source by hand
-
MUST be done by code, we’ll add a data-attribute to the resulting hrml that indicates the origin of the link.
| TBW where is the registry to ensure uniqueness of doctags and prevention of duplicious doctags? |
§ System feature Consistency
Have a look at it here and be informed that Spec-Up is a longer running open source project that’s originated in DIF. ToIP invests in improvements to it in 2024. And offers these improvements as PRs to the DIF repo.
The tool will perform
- Basic domain checks
- Domain checks Spe-Up or github actions
- Parser checks Spe-Up or github actions
§ External Consistency
We like reuse of existing terminology, laid out in definitions and glossaries. If applied correctly, reuse will increase consensus within TrustoverIP.
Given this positive effect we encourage people to look what’s there already before defining and writing your own definition.
How do we know which known glossary to use? Maybe any glossary we have previously created a cross reference from should be included? There is already tooling available to include existing glossaries and give a unified overview of them in KERISSE. This listing can be adjusted to “ToIP only”.
§ No effective system without governance
The governance rules that we have to put in place (at least with the ToIP community) should be:
-
If the spec authors want to use a term with its definition term as defined in the ToIP Glossary, the spec authors MUST insert a remote ref to that term in their spec and MUST NOT copy the term (or worse, redefine it) in their internal spec glossary.
-
If the spec authors want to use a term defined in the ToIP Glossary but modify its definition, they COULD submit raise an issue and/or a pull request to the ToIP Glossary making the case for their proposed change. If that change is resolved to their satsifaction, they can proceed as per rule #1 above.
-
If the spec authors want to use a new term that does not exist in the ToIP Glossary to their liking, they have two choices:
- If the spec authors believe the term should apply “ToIP community-wide”, they can submit a PR to have it added to the ToIP Glossary. If accepted, they can then follow rule #1 above.
- If the spec authors believe the term only applies in the scope of their particular spec, they can define it with a def tag in their own internal spec glossary and then ref it there.
Of course, this set of rules only works within an coherent community willing to follow them. We can’t control the use of terminology outside of the ToIP community.
§ System feature functionality
The front-end functionality of the resulting github.io page can and must be altered to comply with various Reader allowances:
- Only so and so often a link to known term in the glossary
- Only so and so often an abbreviation of term added to the term in the core text
- Pop-ups consistenly showing definitions while hovering over the term
- Consensus tooling (kerific) as a browser extension
| TBW |
§ System feature layout
The front-end layout and pdf layout of the resulting github.io page can and must be altered to comply with various style-guide rules of external parties like IETF or ISO.
| TBW |
Guide normative~ What is the criterium something being a Guide versus a Specification? A Specification has enough normative statements to be directly implementatable.
normative ~ A theory is “normative” if it, in some sense, tells you what you should do - what action you should take.Also see KERISSE
- phrase
- Something is a phrase when it’s either a term, an abbreviation or an alias in the context of this guide.
- term
- The ToIP notation of a terminology item, that requires a definiton, that could have an abbreviation and zero or more aliasses. A term is supposed to be uniquely defined in a certain scope, but can have many exactly the same instances in a broader community.
The term also serves as a key in the source management tool of ToIP terminology sources and to make a comparison among terms.
Criterium: only if a certain word or phrase in ToIP notation and first placed in the definition tag, then it’s a term in the scope of this guide. Only a term can have just one abbreviation.
Also see term. - abbrev
- a shorthand in capitals for a term. It may contain special characters. It may not contain spaces.
Criterium for not being an abbreviation: If the word is not in uppercase, in our context the word is more likely to be an alias for the term. - alias
- Any notation of a terminology item, that is an alternative for a term being defined. The alias also serves as a comparison among term definitions.
An alias is typically a means to one-on-one relate specific wording to a term already defined. For example :
- Synonyms
- Plural - singular
- Different spelling
- Lowercase versus Uppercase
- another (!) abbreviation Mind you: the most applicable abbreviation should be in abbrev. Criterium: an alias | TBW |
- doctag
- A short unique tag assigned to the remote Spec-Up document containing the def for the term being referenced. So any Spec-Up document that uses remote refs would need to include a doctag section
§ Normative addendum - Spec-up improvements
This normative section is also called the “Spec-Up glossary tool” (SGT).
§ Background
To simplify the job of tech spec construction and editing, the Technology Stack WG has adopted the Spec-Up document rendering tool which is originally a DIF open source project (repo).
§ Objective
Based on use cases of certain roles we’d like to technically specify improvements in a normative way, so that they can be implemented right away and connected to issues.
In each topical section (header level 3) there’ll be various sub-topics (header level 4)
- features
- consistenty checks
- domain checks
- business rules
§ refs
One def and 1 to many refs may be present in a spec-up source document.
§ features
For an author there are mainly three relevant functionalities.
- Spec-Up already has a basic glossary feature:
def
tags for defining glossary entries andref
tags for marking up terms in the spec that refer to def-tagged terms. Def tags only reference def tags in the same Spec-Up document.
§ Internal definition (def)
definitions (def
s)
[[def: term { | abbrev}, {alias}, {alias}, ... ]]
~ Lorem Ipsum ...
A term
SHOULD be defined as a ToIP definition style : lower case
An alias
COULD be referenced. If you do so the reference MUST end up at the definition of term
This is already operational in the current version of Spec-Up and implemented with nested spans
::: ISSUE https://github.com/henkvancann/terminology-governance-guide/issues/1 :::
Check
defs
of aliases https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md#term-references and the workingrefs
here https://identity.foundation/spec-up/#term-references
abbrev
COULD be defined and referenced. If you do so a seperate definition of abbrev
MUST be present in the document itself:
[[def: abbrev]]
~ [the term the abbrev refers to]
Example of the duplet:
[[def: KEL]]
~ [[ref: key event log]]
[[def: key event log | KEL, Key-event log ]]
~ Lorem Ipsum ...
§ Don’t do this
[[def: term (abbrev)]] and
[[ref: phrase]]
but do this
[[def: term | abbrev]]
How to add an abbreviation after the term? Two ways possible:
- in the markdown, but NOT in the reference to the term: ref: There will be post-markdown processing available to proportionally add abbreviation
§ Internal linking (ref)
[[ref: phrase]]
phrase
MUST be one of term
, abbrev
or alias
Three ways of offering references (ref
s) to definitions (def
s) by the author of a text:
-
explicitly created by author
-
extra by default, after n occurrences or below a header of certain level
-
MUST be done in the source by hand
-
MUST be done by code, we’ll add a data-attribute to the resulting hrml that indicates the origin of the link.
| TBW where is the registry to ensure uniqueness of doctags and prevention of duplicious doctags? |
§ System feature Consistency
Consistency and rules for def:s and ref:s leads to github.io page with all kinds of working internal and external links and clear rules for writers.
§ Consistency pre-caution
Each def
in a local Spec-Up document that has exactly the same def
* existing in any of the remotely referenced document URLs listed in the local document (see the title
list description in your specs.json
).
Each ref
has an existing def
. Each def
has at least one ref
or xref
.
Spec-Up code that detects dangling refs
and defs
. In other words, code that checks to see that:
a. any ref tag defined in the spec has a corresponding def tag for the glossary entry, and
b. every def tag defining a glossary entry has at least one ref tag pointing to it.
§ Domain checks
term
, or (optional)alias
or (optional)abbreviation
of the term definition used to reference
Local references
The most important domain check between a local ref and def is that they’re always pointing back and forth in the same Spec-Up document — they look like:
[[def: term, alias, ..., alias ]]
[[ref: phrase]]
where phrase is one of term
or optional alias
es.
Basic domain checks
- characterset
- spaces
and - Uppercase versus lowercase
- Form Phrases | TBW |
Domain checks Spe-Up or github actions
- No abbrevs in the text of a term either in “()” or after “;”
- The system must warn for double aliases in one def
- The system must warn for double abbrevs in one def
- No duplicity in wording in term, abbrev and alias(ses)
- If term and abbrev are the same, discard abbrev
- If alias and term are the same, discard alias
- If abbrev and alias are the same, discard alias
| TBW What is ‘the same’ ? |
§ Business rules
Parser checks Spe-Up or github actions
- The system must warn for double aliases in more than one def
- The system must warn for double abbrevs in more than one def
- The system must report broken internal links, refs that don’t match term, abbrev nor aliasses.
§ xrefs
We need the capability for all ToIP specs to use xref
s to reference a common ToIP Glossary in addition to their own internal glossary. The common glossary will be referenced with title
.
- An
xref
tag to enhance Spec-Up code to support remote refs.
§ Features
§ Feature Title and title collections
It is possible to include references to terms from external spec-up generated specifications. To include a source you would like to pull references from include an external_specs array in your spec config. The value should be a key/value object where the key is used in the external reference below and the value is the URL of the external spec.
To include an external term reference within your spec use the following format [[xref: {title}, {term}]]
where {title}
is the title given to the spec in the specs.json
configuration file and {term}
is the term being used.
For example using the PE
spec given in this example:
{
"specs": [
{
...
"external_specs": [
{"PE": "https://identity.foundation/presentation-exchange"}
]
}
]
}
§ How to adopt a term “as is”?
Local preferable
[[ref: term]]
Or remote reference
[[xref: title, term]]
Where term
is either a term, abbreviation or alias.
§ Consistency pre-caution
Each xref
has an existing def
in the title
glossary.
Spec-Up code that detects dangling refs
and defs
in the collection of title
s. In other words, code that checks to see that:
a. any ref tag defined in a spec has a corresponding def tag for the glossary entry somewhere in the collection of titles
, and
b. every def tag defining a glossary entry in any of the title
s including the local one. has at least one ref tag in any of the title
s pointing to it.
§ Domain checks
see refs for applicable initial domain constraints; plus the following.
Remote references
[[xref: title, term]]
is a short unique tag assigned to the remote Spec-Up document containing the def for the term being referenced. So any Spec-Up document that uses remote refs would need to include a doctag section that looks something like this:
In specs.json:
"external_specs": [
{
"<title>": "<URL>"
}
example
"external_specs": [
{
"PE": "https://identity.foundation/presentation-exchange"
}
§ Business rules
Of course, this set of rules only works within an coherent community willing to follow them. We can’t control the use of terminology outside of the ToIP community.
It should check each ref
and xref
created in reference title
against any def
that you’re about to remove from a local file.
It should signal each ref
and xref
created in reference title
against any def
that you’re about to change in a local file.
§ Add context to adoption of a term
Adopting a term from a related scope (under the ToIP umbrella) or external SHOULD always be accompagnied with a possibility for the author, curator and maybe even other team members to add context to the definition adopted.
§ Features context and metadata
The following metadata MUST be registered:
term
, or (optional)alias
or (optional)abbreviation
of the term definition used to referenceurl
of the spec in which the term definition list is present and the name of the headercommit hash
of the term definition plus specification adoptedauthenticated github user
that adopts the term (create), changes it’s context (update) or deletes the context.
This metadata SHOULD be added:
title
of the group from which the term will be adoptedrole
of theauthenticated github user
in the current scope
You COULD add or remove:
context
which is a block of free text.
§ How to adopt a term with added or updated context?
Add:
[[def: term or abbreviation or alias]]
with in the text part of the definition
[[xref: title, term]]
Reference:
[[ref: term]]
Example
Where KE
is the title of KERI spec in spec-up format and TP
the title of the ToIP overall glossary in spec-up.
[[def: verification]]
~ Verification in Healthcare is in between the strict [[xref: KE, verification]]
and the more loose ToIP definition [[xref: TP, verification]]. However we have the same criteria as KERI
because our system will be KERI-based.
§ Consistency pre-caution
| TBW |
§ Business rules
The order in which these changes take place to a terminology definition, referencing and/or commenting SHOULD be registered.
Mind you: the adopter of a term SHOULD NOT delete, nor alter the original definition, present in another scope.
§ How to stop adding context to an adopted term?
Remove the local def
and change
[[ref: term]]
into [[xref: term]]
Now the term is again externally referenced “as is”.
§ Authentication and roles
It’s important to make explicit that somebody in a certain role added context to a remotely referenced term definition. Or he/she has chosen to refrain from that.
[[ref: title#phrase]]
phrase
MUST be one of term
in any of title
’s glossary.
For example, a specification that includes a ref
tag that looks like this: [[xref : TP, term]]
would reference a def tag defined in the ToIP Glossary. Similarly, a ref that looks like [[xref: hxwg, term]]
would reference a defined term in the (theoretical) HXWG glossary.
With the remote reference feature, all ToIP specifications (and any other deliverable written with Spec-Up) would be able to include linked glossary terms (including hover pop-up definitions), both from within its own glossary and from any referenced glossary in another document that also uses Spec-Up.
Mind you, this process touches group dynamics, consensus building and communication.
§ System feature functionality
The front-end functionality of the resulting github.io page can and must be altered to comply with various Reader allowances:
- Only so and so often a link to known term in the glossary
- Only so and so often an abbreviation of term added to the term in the core text
- Pop-ups consistenly showing definitions while hovering over the term
- Consensus tooling (kerific) as a browser extension
| TBW |
§ System feature layout
The front-end layout and pdf layout of the resulting github.io page can and must be altered to comply with various style-guide rules of external parties like IETF or ISO.
| TBW |
§ Integration
This is an informative section
Spec-Up, Spec-Up Glossary tool, TEv2 and the KERISSE-engine plus kerific tooling are gradually going to integrated for the sake of concept & terminology management in ToIP.
This section might why we anticipate with this Governance Guide on future development the way we’ve done in the previous sections.
§ Concerns
We share some concern raised over the first months in 2024.
§ Spec-Up and Specification Template
Current copy and paste strategy leading to merge horror “unrelated histories”.
How we should fork to stay in tune with each-other and easily accept improvements?
Noticed the differences?
- Through forking instead of copying we keep git histories compatible
- Through
fetch+merge
(orpull
when no conflicts expected) we not only keep DIF and ToIP synced, but also it is very straightforward to update all the gh-pages-based specification websites that use the Specification Template to:- sync functionality and data
- offer PRs from any of those installs
§ Roadmap to TEv2
As a TEv2 creator and frontman we share Rieks Joosten’s viewpoint on this proposal for using Spec-Up refs and defs.
He explained that the same features being discussed here were also added to TEv2.
There is always tension between adding a lot of features and taking a long time, or keeping things very minimal. He pointed out that creating glossaries based on cherry-picking glossary entries based on personal preferences can be problematic because it doesn’t actually establish shared understanding and criteria for defining terms.
The larger the group involved, and the more varied their cultural backgrounds, the more problematic that can become. However, that doesn’t mean we shouldn’t start with tools that are actually working right now. Riek’s personal preference is to use terminology that expresses the author’s intentions clearly. For example, in reading the Spec-Up documentation, it was challenging for Rieks to understand it without more context.
Rieks would like to have several more sessions on TEv2 so we can still look at how we can use it for our terminology. He’s not opposed to enhancing Spec-Up for these features, but at the same time keeping TEv2 tooling in progress.
Rieks Joosten concluded that we need to see what tools are actually needed by both authors and readers to help them comprehend the terms they use. He can also explore how TEv2 tooling can be used to produce Spec-Up definitions.
Rieks Joosten was in favor of proceeding with changes to Spec-Up, but also to continue the work on TEv2 to tackle larger issues of terminology management.
§ TEv2 Explanation
§ Current structure
§ Docusaurus example CURRENT
§ SpecUp example CURRENT
§ Internal Scope
§ External Scopes and internal scope
§ Full architecture
§ Always archive never delete
Darrell O’Donnell clarified that technical maintainers we will not delete any ToIP repos, but will only archive them.
| TBW |
§ Annex
§ Comparison Spec-Up 2023 and TEv2 by Rieks Joosten, Jan 2024
This specification has used the following insights to write the Guidelines, most notably in the Roles section and the Normative section.
§ Spec-Up
I have had a look at the latest spec-up draft, specifically that relating to terminology. The text tells you about features it has, but (as often) you need to see the source of that text (in RAW format) to figure out how to do things if you’re new to this. Here’s my understanding: Spec-up term definition syntax is as follows:
- <text that is used as the description/definition of ‘term’>
where
If you want to specify aliases (what TEv2 calls ‘form phrases’), you say:
- <text that is used as the description/definition of ‘term’ (and its aliases)>
where
§ TEv2 definitions appear in different forms:
As a set of a (curated) text files (markdown), one for each term. They contain (YAML) frontmatter in which there are fields for (a) the term, (b) the aliases (called ‘form phrases’) and © the text line (called ‘glossaryTexts’). In their body, they contain more documentation related to the term. as an entry in a machine-readable glossary (YAML). Every entry basically consists of not only the frontmatter of the curated text file, but also some other fields that (third party) tools can use to find the curated text file, or a rendered version thereof. as a set of Wiki files, that will (soon?) be ingestable (turned into curated text files).
Spec-up use of term references within markdown:
where
where
TEv2 has additional syntax for using terms that refer to stuff
other than concepts (such as mental models, e.g.,
Also, TEv2 has mechanisms where users can define/configure their own syntax for termrefs, and also mechanisms for specifying what a termref (when found) should be converted into. Spec-up glossaries are a rendered version of the list of spec-up definitions, which requires them to all be specified in that same one location. When a user clicks on a termref (in the rendered version), it is taken to the location where the term is defined. I haven’t seen any documentation of whether/how that would work with multiple files. TEv2 glossaries come in two forms: machine readable glossaries (MRGs) and human readable glossaries (HRGs). TEv2 sees a HRG as a rendered reference to a particular MRG, so (like TermRefs) users can specify a so-called ‘MRG-Ref’ in their markdown, and when that is processed, a HRG is generated at that location from the designated MRG, in a format, and using contents that the user specifies. Here is an example of various HRGs generated in a single page.
§ Discussion
Spec-up is quite different from TEv2. Most notably, By design, spec-up is (very) simple to use, and has the basic features you need when writing (simple) specifications. When things become more complex, or you want to explicitly position a spec in a context where other specs also live, my guess is that you run into its limitations. But then, that’s not what spec-up was designed to do. TEv2 on the other hand is not simple when viewed from a single-context-perspective. But you can use and build on terminologies of others. Another source of perceived complexity may be caused by its flexibility, e.g., it allows users to specify syntaxes (for TermRefs and MRGRefs), as well as the (html, markdown or other constructs) that the can be converted into.
So the basic question seems to be whether or not there is an actual need for spec-up and/or TEv2 within ToIP, which I think we can ponder about by understanding what either can, or cannot do.
tno-terminology-design.github.io
Glossary Generation Demo | TNO Terminology Design
This page is evidence that an HRG can be generated for every MRG that is available within the scope. It also shows that HRGs can be generated in different formats.
Regarding the roles (specification author, curator, end-user/reader), some thoughts:
Authors come in different flavors. An author that writes specs has different capabilities (e.g., be precise and so) than an author that writes learning stuff (things for Muggles and so). Darrell can do git and markdown, but I recall that Nicky (and others) thought that to be too cumbersome. The minimalistic use-cases would differ for the different author sub-roles, so we should give some thought which sub-roles exist within ToIP.
When we were talking about the ‘term communities’, we also had the role of ‘contributor’, which is the role a person performs as (s)he helps draft criteria (for definitions), mental models and other stuff that we envisaged could be needed in a particular WG, TF (scope). Do we still think that way?
Apart from having the minimalistic use-cases, I think it would be helpful if, for every activity or product from the CTWG, we know who would actually be using it, and what they would need to be able to do with that so that we can make sure that they can use it and do with it what they need to. And IMHO that is far from trivial, we we should give that some attention.
§ Brief history to the Guide
In 2021 TrustoverIP published the Specification for Creating and Using Terms
In the years to follow the guide to create Term wikis has been established. It gives extensive instructions on how to create wikis, use markdown and hyperlinks, etc.
As the number of implementations grew, maintenance of the wikis became out of sync, the number of broken links increased, duplicate definitions of terms and deviations from the structure and governance offered.
Darrell O’donnell: As I am deep in a rabbit hole looking at definitions a thought occured to me. We may end up with “over-defined” terms - meaning the definition exists in multiple places. Have you considered that case? I believe that a ToIP Master : ToIP Specification conflict should be avoided. If a spec needs a different term than is in the Master glossary, then the conflict should be resolved: adjust Master Glossary; or create new term in Spec BUT where we end up looking at terms that are managed even further afield, this gets really hard. Just curious if this is a condition you’ve thought of. I see the following possibilities:
- multiple def: in single document (this is just sloppy work - but easy to do, for me at least)
- duplicated def: - say in Spec and ToIP Master Glossary
Check quickly out how we take on these concerns
Some of these developments are part of the natural evolution of concepts and terminologies within an umbrella organisation like ToIP. Others could be more streamlined.
This specification intends to offer a Guide. A Guide has little or no normative statements as it describes an advise on how to create a specific terminology by sticking to guidance and certain rules to know how to write or adopt definitions, how to reference them and where to store and manage them:
- reuse the specification template and how to do this in a sustainable manner
- reuse the ToIP over-arching glossary where possible
- avoid breaking links in the future
- use the full power of def, refs and aliases in individual documents based on Spec-Up (which is behind specification template as of 202?)
- be able to generate your documents in a few leading style-guides like ToIP, ISO, etc.
- Last but not least: any group with a certain scope will need to source manage their own definitions or views on definition, which means that we need to ear mark creation and updates with time & author.