V1—2022-03-20
Introduction
Two decades of Web standards work has taught us there are good reasons to adopt a uniform convention for constructing the URLs for ToIP Approved Deliverables before they are posted on the ToIP website:
- The link for a specific deliverable can be known in advance of it being posted. This is critical when two or more deliverables that have links to each other need to be prepared at the same time. (Otherwise the editors are stuck in a Catch-22 of needing links before they can post and needing to post before they can link.)
- It is easier to identify a specific deliverable just from the URL. You can read it right out of the link itself.
- Well-constructed links tend to live longer and get better SEO. They are easier for the Web-crawling spiders to digest.
ToIP Deliverable File Name Construction Algorithm
All ToIP Approved Deliverables MUST follow this file naming algorithm:
Name-of-Deliverable-V1.0-YYYY-MM-DD.ext
Rules:
- The filename MUST include a version number and date (even if only one version is planned).
- The V prefix for the version name MUST be in UPPERCASE.
- The entire filename MUST NOT contain any spaces.
- Wherever a space would be used, it MUST be replaced with a hyphen (NOT an en-dash or an em-dash).
- The filename MUST end in an extension prefixed by a period.
The rules for each variable in magenta are defined in this table:
Variable | Rules |
Name-of-Deliverable | MUST either begin with “ToIP” or include “ToIP” someplace in the name. MUST (except for spaces and punctuation) match the exact name of the deliverable as it appears on the title page, including the case (uppercase or lowercase) of each word. MUST replace all spaces with hyphens. MUST drop any other punctuation. |
1 | MUST be the major version number of the deliverable. MUST be a sequential integer for each major version. MUST begin with 1 for the first version. |
0 | MUST be the minor version number. MUST be a sequential integer for each minor version. MUST begin with 0 for the first version. |
YYYY | MUST be the year of the ToIP SC approval date on the title page. |
MM | MUST be the month of the ToIP SC approval date on the title page. |
DD | MUST be the day of the ToIP SC approval date on the title page. |
ext | MUST be the media type string for the file format as defined in the IANA Media Type Registry. MUST be in lowercase. |
Examples
ALERT
An inadvertent error was made in the construction of four of the five example filenames below—the year for all of them should have been 2021. However these filenames were subsequently published as permalinks so they will remain as written for these documents.
The following are actual names of ToIP Approved Deliverables in PDF format that follow this convention.
Introduction-to-ToIP-V2.0-2021-11-17.pdf
Design-Principles-for-the-ToIP-Stack-V1.0-2022-11-17.pdf
ToIP-Governance-Architecture-Specification-V1.0-2022-12-21.pdf
ToIP-Governance-Metamodel-Specification-V1.0-2022-12-21.pdf
ToIP-Governance-Metamodel-Specification-Companion-Guide-V1.0-2022-12-21.pdf
If the same deliverables were also published as Microsoft Word files, these would be the filenames:
Introduction-to-ToIP-V2.0-2021-11-17.docx
Design-Principles-for-the-ToIP-Stack-V1.0-2022-11-17.docx
ToIP-Governance-Architecture-Specification-V1.0-2022-12-21.docx
ToIP-Governance-Metamodel-Specification-V1.0-2022-12-21.docx
ToIP-Governance-Metamodel-Specification-Companion-Guide-V1.0-2022-12-21.docx
URL Construction Algorithm
It is very important for all ToIP Approved Deliverables to have URLs that function as permalinks, i.e., links that will remain stable for a very long time. Thus the algorithm for constructing the URL for a ToIP Approved Deliverable is very simple:
https://trustoverip.org/permalink/filename
Rules:
- The directory https://trustoverip.org/permalink/:
- MUST remain stable for the lifetime of the ToIP Foundation.
- MUST NOT be used for any purpose other than storing permalinks.
- The filename MUST be the exact string constructed following the ToIP Deliverable Filename Construction Algorithm specified above.
Examples
ALERT
An inadvertent error was made in the construction of four of the five example permalinks below—the year for all of them should have been 2021. However these permalinks were subsequently published so they will remain as written for these documents.
The following are the URLs of ToIP Approved Deliverables in PDF format that follow these rules.
https://trustoverip.org/permalink/Introduction-to-ToIP-V2.0-2021-11-17.pdf
https://trustoverip.org/permalink/Design-Principles-for-the-ToIP-Stack-V1.0-2022-11-17.pdf
https://trustoverip.org/permalink/ToIP-Governance-Architecture-Specification-V1.0-2022-12-21.pdf
https://trustoverip.org/permalink/ToIP-Governance-Metamodel-Specification-V1.0-2022-12-21.pdf
Feedback
Please post a comment to this page and/or the #communication-committee channel on Slack if you have questions or feedback about these conventions.