CSV-LD：基于CSV的链接数据序列化

逗号分隔值（CSV）是一种有用的数据序列化和共享格式。本文档介绍了CSV-LD的概念，作为一种基于CSV的格式来序列化链接数据，类似于JSON-LD作为一种基于JSON的格式来序列化链接数据。“CSV”这里包括任何使用不同分隔符的方言，例如制表符分隔值（TSV）。

CSV-LD的语法设计旨在轻松集成到已经使用CSV的部署系统中，并提供了从CSV到CSV-LD的平滑升级路径。它主要旨在作为一种使用链接数据作为基于电子表格的数据输入方式；通过使用CSV on the Web (CSVW)元数据促进数据验证、显示以及将CSV转换为其他格式的转换；以及构建FAIR数据服务。

“CSV-LD”一词之前被用来描述现在已过时的前身，即CSVW规范；两种方法都需要一个额外的文件，即与CSV文件一起共享的JSON-LD模板文档。然而，本文档中描述的方法只需要一个CSV文件，该文件包含指向CSVW元数据的链接。

数据生产者

数据生产者需要在其CSV文件中添加两行标题以使其成为CSV-LD：一个是“key-spec”行，另一个是“column-spec”行。这反映了JSON可以通过添加“@context”键值对以最小程度地成为JSON-LD的方式。CSV生产者通常会在标题行中包含列名，并且可以看到带有额外标题行的CSV文件（headerRowCount是CSVW词汇表的一部分）。

键规范行

最顶部的行，即键规范行的最重要任务与指定键无关。相反，它的作用是向数据消费者传达这个文件在某些方面是特殊的——最左边的单元格必须包含一个URL，并且希望从未见过CSV-LD的人会点击链接。

链接是http://example.org/csv-ld/2021/01/inKey（实际上并不是这样，但我会很快更改它——我已经注册了csv-ld.org，目前将其指向CSVW词汇表页面），并提供对CSV-LD的友好介绍。该文件可以通过在inKey之前使用不同的前缀来表明它使用CSV-LD的不同版本，这将链接到该版本的页面。

该页面还将解释，inKey标记一个CSV列是唯一标识行的一部分。CSV表可以有一个单一的键，如ID列，或者一个复合键，如年份和学期（例如，“秋季”，“春季”）唯一标识每一行作为一个学术学期。所有键列必须是连续的，并从左侧开始——这（1）使链接对于不熟悉CSV-LD的人来说更容易找到，并且（2）使数据消费者/管理员实现CSV-LD处理器更容易。

在键规范行中（在键列之后）的单元格值（包含inKey链接的列）只有一个要求：它们不能与键列单元格的inKey-链接值相同。它们可以是空的、注释，或者任何其他内容。

因此，总结一下，键规范行（1）传达了文件是CSV-LD文件，并且（2）传达了（可能是复合的）唯一标识行的键。

列规范行

列规范行的任务是对每个列进行明确的标记。在列规范行下方有标题行，展示常用的标题行做法，即使用简短的名字（如“x”，“y”等）作为列标签，这是完全正常的。

对于数据生产者来说，这项任务应该是使用由数据管理员编写、为感兴趣的每个列提供URL的模板或参考指南的一个简单过程。例如，可能会提供以下表格来记录收集的生物样品的环境元数据

这些都不是真正的URL（但我会最终更新这个例子使其成为真实的）。数据管理员还可能为数据生产者提供命名空间，例如http://example.org/nmdc/team42/，生产者可以使用这些命名空间来前缀后来通过数据管理员的努力解析为有效URL的自定义术语。

术语URL应该解析到解释值应如何格式的页面。例如，http://example.org/nmdc/lat_lon可以解释值为度数的纬度，一个空格，然后是度数的经度。这种解释可以由CSVW元数据（由数据管理员编写）自动生成，CSVW元数据也将由CSV-LD处理器用于验证数据。例如，此字段的CSVW元数据可能看起来像

{
  "@context": {"@vocab": "http://www.w3.org/ns/csvw#"},
  "name": "lat_long",
  "separator": " ",
  "ordered": true,
  "datatype": {
    "base": "number",
    "minimum": "-180",
    "maximum": "180"
  }
}

数据消费者

CSV-LD文件仍然只是一个CSV文件，所以数据消费者可以简单地忽略“额外”的标题行。每个“额外”的标题行都以“#”和一个空格开头，这样流行的解析器就可以将这些行识别为“注释”行，并跳到“真实”的标题行，例如对于流行的Python pandas数据处理库，可以使用pandas.read_csv(..., comment="#")。他们也可以点击列规范标题中的任何链接来了解如何解释该列中的数据。如果他们有权访问CSV-LD处理器，他们可以使用它来验证数据或将其转换为其他格式，如JSON（即JSON-LD）。

数据管理员

数据管理员关注数据完整性。他们可以为csvw:Column实体编写JSON-LD元数据，如上面http://example.org/nmdc/lat_lon的示例所示，并从用于列的URL下载该元数据。

CSV-LD处理器将使用表示偏好JSON-LD响应的HTTP Accept头来请求http://example.org/nmdc/lat_lon，而人类在浏览器中加载http://example.org/nmdc/lat_lon将得到数据管理员生成的网页（HTML）响应。

因此，数据管理员需要知道如何提供网络内容，或者需要与能够做到这一点的人合作。我希望能在这个存储库中提供一个参考服务器实现，用Python编写。

CSV-LD处理器实现者

CSV-LD世界的最终利益相关者是CSV-LD处理器的实现者。将提供更详细的规范，但我将尝试遵循“更糟的是更好的”方法，该方法优先考虑实现的简单性。此外，这个存储库将托管一个参考CSV-LD处理器实现，用Python编写。也许参考实现对于大多数人来说已经足够好了。

需要注意的是，数据生产者的任务是聚合一组具有明确定义字段（列）的记录（行）。记录是什么或应该是，即其类型或类，以及例如哪些列是必需的，留给了数据消费者，取决于应用程序。

验证整个记录很重要，CSVW元数据规范可以帮助完成这项任务。我预计稍后会详细介绍如何确切地调用CSV-LD处理器，例如

csvld --entity "http://example.org/nmdc/BioSample" --out data.json data.csv

以验证CSV-LD的每一行，以及独立验证每个列值。