SoftWare Heritage持久ID标识符（SWHID）

版本1.6，上次修改时间2021-04-30

概述

您可以指向软件遗产 档案文件通过以下方式软件遗产持久ID标识符，或SWHID公司简而言之，这是有保证的随着时间的推移保持稳定（持久）。它们的语法、含义和用法是如下所述。请注意，它们是标识符，而不是URL，尽管基于URL解析器也可用于SWHID。

SWHID由两个单独的部分组成堆芯标识符可以指向软件遗产中可用的任何软件工件（或“对象”）存档和可选列表限定符允许指定指的是要看到对象并指向其子部分的上下文对象本身。

对象有不同的类型：

• 目录

• 目录

• 修订

• 发布

• 快照

每个对象都由一个特定于类型的内部对象标识符标识，该标识符嵌入其SWHID中，如下所述。嵌入的内部标识符在SWHID中，是在整个对象集上计算的强加密哈希属性。这些标识符一起构成Merkle构造特别是MerkleDAG公司.

请参阅软件遗产数据模型概述对象类型及其链接方式。请参见swh.模型.git_objects有关如何使用内部标识符的详细信息计算SWHID中嵌入的。

可选限定符有两种：

• 上下文限定符：携带有关给定上下文的信息物体是要被看见的。这一点尤其重要，因为对象可以在Merkle图中按不同的路径从不同节点开始（或锚)，它可能已被检索到来自不同的起源，可能会在不同的访问

• 片段限定符：允许精确定位对象的特定子部分

语法

从语法上讲，SWHID由<标识符>中的入口点以下语法：

<标识符> ::= <标识符_核心>[<限定符>] ;<标识符_核心> ::=“swh”“：”<方案_版本>":"<对象类型>":"<对象id>；<方案_版本> ::=“1”；<对象类型> ::=“snp”（*快照*）|“rel”（*发布*）|“版本”（*修订版*）|“目录”（*目录*）|“cnt”（*内容*）；<对象id> ::=40 *<六进制数字>;  （*内部对象id，作为十六进制编码的SHA1*）<十进制（_D）> ::="0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;<十六进制数字> ::= <十进制（_D）>|“a”|“b”|“c”|“d”|“e”|“f”；<限定符>:= ";"<限定符>[<限定符>] ;<限定符> ::=
    <上下文限定符>|<片段限定符>；<上下文限定符> ::=
    <原始_文本>|<访问ctxt>|<主持人_ ctxt>|<路径文本>；<原始_文本> ::=“原点”“=”<url转义>；<访问ctxt> ::=“访问”“=”<标识符_核心>；<主持人_ ctxt> ::=“锚”“=”<标识符_核心>；<路径_文本> ::=“路径”“=”<路径绝对覆盖>；<片段限定符> ::=“行”“=”<行号>["-"<行号（_N）>] ;<行号（_N）> ::= <十进制（_D）>+ ;<url转义> ::=（*RFC 3987 IRI*）<路径绝对覆盖> ::=（*RFC 3987绝对路径*）

哪里：

• <路径绝对值>是一个<ipath-absolute>从副本请求3987、和

• <url_escaped>是一个副本请求3987爱尔兰共和国

在任何一种情况下；（和%（根据RFC的要求）已按百分比编码（作为%3B公司和%25分别）。其他字符可以以百分比编码，例如提高可读性和/或SWHID在其他环境中的可嵌入性。

语义学

核心标识符

:用作核心标识符的逻辑部分之间的分隔符。这个瑞士法郎前缀明确表示这些标识符与软件遗产.1(<方案版本>)是此的当前版本标识符方案。未来版本可能会使用更高的版本号打破向后兼容性，但不破坏符合该方案先前版本的SWHID。

SWHID指向单个对象，其类型由显式捕获<对象类型>:

• snp公司到快照,

• 相对到发布,

• 转速到修订,

• 目录到目录,

• 碳纳米管到目录.

指向的实际对象由内部标识符标识<对象id>，它是十六进制编码的（使用小写ASCII字符）SHA1根据对象本身的内容和元数据计算，如下所示：

• 对于快照，内部标识符是根据计算的清单的SHA1哈希swh.模型.git_objects.snapshot_git_object（）

• 对于发布，根据swh.模型.git_objects.release_git_object（）产生与git发布哈希相同的结果

• 对于修订，根据swh.模型.git_objects.revision_git_object（）生成与git提交哈希相同的结果

• 对于目录，根据swh.模型.git_objects.directory_git_object（）生成与git树散列相同的结果

• 对于目录，内部标识符是沙吉特返回的哈希swh.hashutil。MultiHash.digest（），即字节的SHA1通过并列ASCII字符串获得的序列“blob”（没有引号）、空格、内容长度（十进制数字）、NULL字节、，以及文件的实际内容。

限定符

；用作核心标识符和可选限定符，以及限定符之间。每个限定符都指定为键/值对，使用=作为分隔符。

以下内容上下文限定符可用：

• 来源：这个软件来源发现或观察到物体的地方在野外，作为URI；

• 访问：的核心标识符快照对应于特定参观包含指定对象的存储库；

• 锚：一指定的节点在Merkle DAG中，相对于路径到对象指定为目录的核心标识符修订、发布或快照；

• 路径：这个绝对文件路径，来自根目录关联到这个锚节点对象；当锚表示目录或修订版，几乎每次发布时，根目录都是唯一确定；当锚表示快照时，根目录是被指的那个吗头部（可能是间接的），如果缺少此类参考；

以下内容片段限定符可用：

• 行数： 行号感兴趣，通常在内容对象中

我们建议配备标识符，以便与尽可能多的限定符共享可能。虽然限定符可以按任何顺序列出，但最好的做法是按上述顺序呈现，即。，起源,参观,锚,路径,线。应省略冗余信息：例如，如果这个参观存在，并且路径相对于指示的快照在那里，然后锚限定词是多余的；类似地，如果路径是空，可以省略。

互操作性

URI方案

这个瑞士法郎URI方案在IANA为SWHID注册。本文件构成了此类URI方案的方案规范。

Git兼容性

目前，内容、目录、修订和发布的SWHID，与兼容吉特方式计算标识符用于其对象。这个＜对象id＞内容对象的SWHID的一部分是Git blob具有相同内容的任何文件的标识符；对于修订，它是Git提交相同版本的标识符等快照标识符，因为Git没有相应的对象类型。

请注意，Git兼容性是偶然的，并不保证在该方案（或Git）的未来版本中维护。

自动修复无效的SWHID

用户界面可以修复无效的SWHID，方法是将<标识_核心>SWHID的一部分，如果它包含大写字母由于用户错误或软件显示SWHID的限制。

然而，显示或生成SWHID的实现不应依赖于并且必须仅在以下情况下显示或生成有效的SWHID技术上可行。

当发生这种自动修复时，用户界面应显示错误，因此，用户有机会在将SWHID粘贴到其他界面之前修复其SWHID这不会执行相同的更正。这也使得在区分案例时更容易理解问题限定符的外壳已更改。

示例

核心标识符

• swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2指向内容包含GPL3许可证全文的文件的

• swh:1：目录：d198bc9d7a6bcf6db04f476d29314f157507d505指向目录包含Darktable摄影应用程序的源代码2017年5月4日

• swh:1：版本：309cf2674ee7a0749978cf8265ab91a60aea0f7d指向提交Darktable的发展历史，日期为2017年1月16日掩码的撤消/重做支持

• swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f指向Darktable2.3.0版，2016年12月24日

• swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453指向快照2017年5月4日从GitHub获取的整个Darktable Git存储库的

带限定符的标识符

• 以下内容SWHID公司表示可以在绝对位置找到的文件内容的第9行到第15行路径/示例/SimpleFarm/SimpleFarm.ml从的根目录修订swh:1：版本：2db189928c94d62a3b4757b3eec68f0a4d4113f0那就是包含在快照中密码：1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9取自原产地https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git:

  瑞士法郎:1:碳纳米管:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b；
    起源=https（https）://滑稽的.组织/ocamlp3l基因/ocamlp3l_cvs.吉特；
    参观=瑞士法郎:1:snp公司:d7f1b9eb7ccb596c2622c4780febaa02549830f9；
    锚=瑞士法郎:1:转速:2数据库189928c94d62a3b4757b3eec68f0a4d4113f0；
    路径=/示例/SimpleFarm（简单农场）/单纯形.毫升；
    线=9-15
  

• 下面是一个示例SWHID公司文件路径需要百分比扫描：

  瑞士法郎:1:碳纳米管:f10371aa7b8ccabca8479196d6cd640676fd4a04；
    起源=https（https）://github.通用域名格式/网状物-平台-测验/湿性粉剂；
    参观=瑞士法郎:1:snp公司:b37d435721bbd450624165f334724e3585346499；
    锚=瑞士法郎:1:转速:259d0612af038d14f2cd889a14a3adb6c9e96d96；
    路径=/html格式/语义学/文件-元数据/这个-元-要素/杂注-指令/属性-元-http协议-相等的-刷新/支持/x个%三伯尔=foo公司/
  

实施

计算

任何SWHID的一个重要属性是其核心标识符为内在的:它可能是根据对象本身计算无需依赖任何第三方。允许在本地这样做的SWHID实现是swh标识工具，可从swh.型号GPL许可下的Python包。此软件包可以通过pip（点阵）有一个衬垫的包裹管理器管道3 安装 swh.模型在任何具有Python（至少3.7版）和pip（点阵）安装（在Debian或Ubuntu系统上，一个简单的恰当的 安装 蟒蛇3 python 3端口就够了，看一般说明对于其他平台）。

软件遗产也会自动计算所有存档的SWHID对象作为其存档活动的一部分，可以通过项目进行查找Web界面.

这具有多种实际意义：

• 当通过解析SWHID，很容易验证它是否正是预期的：只需从工件本身计算核心标识符，并检查它与SHWID的核心标识符部分相同

• 可以计算软件工件的核心标识符之前它的软件遗产档案

选择要使用的SWHID类型

swh:1：目录：SWHID是最健壮的SWHID，因为它们可以根据最简单的对象（文件系统上的目录结构），即使元数据丢失，而不依赖Software Heritage归档。

因此，我们建议实施者和用户更喜欢这种类型的SWHID结束swh:1：转速：和swh:1：相对值：引用源代码工件。

然而，由于保留元数据也很重要，您应该添加一个锚限定符到swh:1：目录：只要可能，SWHID就会存储元数据可以在需要时检索软件遗产档案中的。

这意味着，例如，您应该更喜欢swh:1：目录：a8eded6a2d062c998ba2dcc3dcb0ce68a4e15a58；锚=swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f结束swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f.

解析器

软件遗产解析程序

SWHID可以使用Software Heritage解决Web界面.特别是根端点 /可以获得SWHID，并将进入相应的对象，如下所示：https://archive.softwareheritage.org/<标识符>.

A类献身的 /解决 端点软件遗产Web API也可用于通过编程解决SWHID；请参见：GET（获取） /api/1/resolve/（swhid）/.

示例：

• https://archive.softwareheritage.org/swh:1:cnt:94a9ed024d3859793618152ea559a168bbbb5e2

• https://archive.softwareheritage.org/swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505

• https://archive.softwareheritage.org/api/1/resolve/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d

• https://archive.softwareheritage.org/api/1/resolve/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f

• https://archive.softwareheritage.org/api/1/resolve/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453

• https://archive.softwareheritage.org/swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b；原产地=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git；visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9；锚=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0；path=/Examples/SimpleFarm/SimpleFarm.ml；线=9-15

• https://archive.softwareheritage.org/swh:1:cnt:f10371aa7b8ccabca8479196d6cd640676fd4a04；原产地=https://github.com/web-platform-tests/wpt；访问=swh:1:snp:b37d435721bbdbd450624165f334724e3585346499；锚=swh:1：版本：259d0612af038d14f2cd889a14a3a3db6c9e96d96；path=/html/semantics/document-metadata/the-meta-element/pragma-directives/attr-meta-http-equiv-refresh/support/x%253Burl=foo/

第三方解析器

以下内容第三方解析器支持SWHID分辨率：

• 标识符.org; 请参见：http://identifiers.org/swh/（注册表标识符MIR:000000655).

• 名称到事物（N2T）

请注意，通过Identifiers.org进行的解析目前仅支持核心标识符由于限定符的语法不兼容.

示例：

• https://identifiers.org/swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2

• https://identifiers.org/swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505

• https://identifiers.org/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d

• https://n2t.net/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f

• https://n2t.net/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453

• https://n2t.net/swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b；原产地=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git；visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9；锚=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0；path=/Examples/SimpleFarm/SimpleFarm.ml；线=9-15

• https://n2t.net/swh:1:cnt:f10371aa7b8ccabca8479196d6cd640676fd4a04；原产地=https://github.com/web-platform-tests/wpt；访问=swh:1:snp:b37d435721bbdbd450624165f334724e3585346499；锚=swh:1：版本：259d0612af038d14f2cd889a14a3adb6c9e96d96；路径=/html/semantics/document metadata/the meta element/pragma directions/attr meta http equiv refresh/support/x%252553Burl=foo/

工具书类

• 罗伯特·迪·科斯莫（Roberto Di Cosmo）、莫兰·格伦彼得（Morane Gruenpeter）、斯特凡诺·扎奇罗利（Stefano Zacchiroli）。标识符数字对象：软件源代码保存案例.在iPRES公司2018：第15届国际数字会议保存，马萨诸塞州波士顿，美国，2018年9月，共9页。

• 罗伯特·迪·科斯莫（Roberto Di Cosmo）、莫兰·格伦彼得（Morane Gruenpeter）、斯特凡诺·扎奇罗利（Stefano Zacchiroli）。引用源代码工件：软件引用中的一个单独关注点在科学计算和工程，第22卷，第2期，第33-43页。ISSN 1521-9615，电气与电子工程师协会。2020年3月。