Permalinks to the ToIP Glossary

Owned by Drummond Reed
Last updated: May 27, 2024
3 min read

Introduction

In the spring of 2024, the CTWG begin publishing the ToIP Glossary as a ToIP specification based on the Spec-Up utility hosted by the Decentralized Identity Foundation. To reference terms defined in the ToIP Glossary, we need to provide permalinks. There are two primary usages for these permalinks:

  1. Any Web document can create a standard Web link directly to the ToIP Glossary as a whole or to any specific term within it.
  2. Any other Spec-Up-based specification can create an xref (external reference) to a term. An xref is more than just a link—it enables the Web version of the document to display a pop-up definition of the term when you hover the link with your mouse cursor.

ToIP Glossary Permalink Requirements

The challenge with permalinks to the ToIP Glossary is that it is a living document. Definitions of terms may evolve over time. After much discussion, the CTWG concluded that this means two classes of permalinks must be supported:

  1. Permalinks to the current (living) version of the ToIP Glossary or any term within it.
  2. Permalinks to any previous version of the ToIP Glossary—or any term within it—based on one of two criteria:
    1. A specified date.
    2. A specified version number.

Permalinks to the Current Version of the ToIP Glossary

The proposed permalink for the current version of the ToIP Glossary is:

https://trustoverip.github.io/glossary/

The permalink template for the current definition of any term within the current version of the ToIP Glossary is:

https://trustoverip.github.io/glossary#term

Where “term” is a case-insensitive match for the term in which any spaces have been replaced by en-dashes. For example, a link to the term “self-certifying identifier” would be:

https://trustoverip.github.io/glossary#self-certifiying-identifier

Permalinks to Dated Versions of the ToIP Glossary

The proposed permalink template for a previous version of the ToIP Glossary by date is:

https://trustoverip.github.io/glossary/yyyymmdd

Where yyyymmdd is the date string consisting of the year—and optionally the month and day—of the version following these rules:

  1. The yyyy string MUST be present.
  2. The yyyy string MAY OPTIONALLY be followed by EITHER a mmdd string OR a mm string.

The returned version of the ToIP Glossary MUST be the union of the definitions of all terms that existed in the living ToIP Glossary as of the last datetime equal to or earlier than the date string.

The permalink template for the definition of any term within a dated version of the ToIP Glossary is:

https://trustoverip.github.io/glossary/yyyymmdd#term

The returned version of the definition must be the definition for that term that existed in the living ToIP Glossary as of the last datetime equal to or earlier than the date string.

Permalinks to Tagged Versions of the ToIP Glossary

The proposed permalink template for a link to a previous version of the ToIP Glossary by version tag is:

https://trustoverip.github.io/glossary/vxx

Where xx is the version number of the version following these rules:

  1. The xx string MUST be present.
  2. The xx string MUST be a positive integer.
  3. The xx string MUST NOT have leading zeros, e.g., it must start at 1.
  4. The xx string MUST be incremented by one for each new version tag, e.g., v1, v2, v3…v439.

The returned version of the ToIP Glossary MUST be the union of all terms in the ToIP Glossary tagged with that version tag.

The permalink template for the definition of any term within a dated version of the ToIP Glossary is:

https://trustoverip.github.io/glossary/vxx#term

The returned version of the definition must be the definition for that term in the version of the ToIP Glossary tagged with that version tag.

Virtual Versions of the ToIP Glossary

The CTWG is currently (May/June 2024) evaluating how it can produce “virtual versions” of the ToIP Glossary as required by these permalink templates. The ideal design will not need to create any actual copies of glossary data (as Spec-Up does when producing different version of a specification document). Instead, it would generate “virtual versions” dynamically from individual term definition files that use standard GitHub git commit tags for versioning. Updates will be posted to this page as soon as we have a conclusion.