翻译者：码农宋襄公
原文链接：https://iiif.io/api/annex/notes/jsonld/

目录

介绍
JSON-LD1.1
语义版本控制
格式和语言
术语扩展/压缩问题
URI方案的意外扩展
术语的贪婪压缩
框架
图像API框架
展示API框架
样本使用

介绍

IIIF规范是使用JSON-LD实现的，JSON-LD是RDF的JSON序列化模式。JSON-LD的优点是，同时具有开发人员可读性和可处理性，并且是关联数据。这允许轻松扩展，而不必担心术语冲突，因为所有内容都映射到一个全局唯一的URI，并且能够作为全局信息图的一部分链接到其他系统。这样做的成本很低，主要是定义和引用每个JSON文档中的上下文文档。
然而，使用JSON-LD有一些副作用，实现者应该知道。其中一些问题是由于RDF模型引起的，另一些问题是JSON-LD特有的。

JSON-LD 1.1

截至2018年，新规范和对现有规范的更新将采用JSON-LD 1.1，而不是JSON-LD 1.0。这带来了许多好处，包括能够更精确地确定上下文定义的作用范围，以及对确切的JSON序列化进行额外控制。

语义版本控制

IIIF过程不考虑JSON映射到所选择的RDF本体术语，以由语义版本控制（译者注：也就是JSON的键值不受Schema校验，但结构与路径是受校验的）。它们是为关联数据实现者提供的便利，而不是所有IIIF采用者的要求。JSON结构和键的名称由语义版本控制控制，因为更改它们会破坏与典型的基于JSON的客户端的兼容性。
如果围绕IIIF构建了大量基于关键数据的客户端，则该决策可能会在未来发生变化。任何此类发展都应在iiif讨论中公布，以便社区了解。
下面描述的JSON-LD框架也不被视为受语义版本控制的框架，而是为方便实现者而提供的。

格式和语言

在JSON-LD中，可以使用带有两个键@language和@value的对象将语言与文字相关联，如展示API中所述。还可以使用@type描述文本的格式。但是，由于RDF1.1中的限制，不可能同时使用这两个特性来声明格式和语言的文本。

在设计展示 API 2.0版的过程中，确定正确的解决方案是明确语言，因为它不能通过启发式方式确定，并且提供了使HTML检测尽可能容易的要求。将来，如果RDF提供了一种方法，使格式和语言都与同一个文本相关联，那么这些限制将被取消。对其他选项进行了评估，包括拥有一个具有值、语言和格式键的资源，与常规JSON的外观相比，该资源被确定为过于侵入性，以及使用带有xml:lang属性和rdf:HTML数据类型的HTML，然而，这使得语言的选择更加复杂，因为值需要用HTML解析器解析，而不是使用JSON结构。由于值的国际化是一个主要用例，所以选择当前方法作为解决方案。

在展示API的3.0版中，采用了一种称为“语言映射”的模式。这允许将该语言的代码用作JSON对象中的键，并将该语言中的字符串列表用作该键的值。这降低了语言结构的复杂性，并进一步巩固了推广语言而非格式的决定。

术语扩展/压缩问题

URI方案的意外扩展

大多数JSON-LD库实现的JSON-LD术语扩展算法无法区分上下文中定义了名称空间的术语和实际URI方案。例如，如果上下文文档定义了从http到http://www.tracker.com/，大多数JSON-LD库将扩展http://iiif.io/ 到http://www.tracker.com///iiif.io/ 只需在值中替换http:。只有在上下文中定义了URI方案名称时，才会出现此问题。

对于服务条目，所有IIIF API都会受到此问题的影响，这与打印机主要使用的服务URI方案相冲突。对于注释中的资源条目，表示和搜索API也会受到此问题的影响，这与临时资源URI方案冲突。建议实现者在描述IIIF资源时不要将URI与这些方案一起使用。

此python代码将检查上下文文档中的冲突。

术语的贪婪压缩

JSON-LD中的术语压缩是获取完整URI和上下文，并尝试为序列化创建适当的压缩形式的过程。例如，如果URI是http://example.com/ns/term，并且上下文具有从eg到的映射http://example.com/ns/，则URI将压缩为eg:term。大多数JSON-LD库使用一种算法，该算法试图在JSON序列化中创建最短的术语，但是当有术语恰好是其他术语的截断形式时，这会产生意外的副作用，因为算法无法区分为创建名称空间而添加的映射和为定义JSON格式的键而添加的映射。

在版本2.1发布之前，IIIF图像API的尺寸特性一直受到此问题的影响。特别是，iiif:size对尺寸有一个定义，与尺寸相关的特性是根据模式iiif:sizeByX命名的，因此，如果不是有意的话，size:ByX是最短的合法压缩。对于版本2.1，iif:size重命名为iif:hasSize以避免此问题。另请参见下面关于语义版本控制和JSON LD的说明。

框架

JSON-LD框架是一种确定JSON-LD序列化布局的方法，特别是确定哪个资源应该位于JSON结构的根，以及是否应该将有关资源的信息嵌入特定位置。这对于IIIF规范具有实际应用，尤其是对于IIIF展示API，例如确保清单资源位于JSON文件的根目录，并且画布作为序列的一部分而不是在范围内序列化，等等。
关于JSON-LD框架的更多信息可以在JSON-LD站点上找到。

图像 API 框架

IIIF 图像 API 信息响应的最小框架

manifest = json.load(urllib.urlopen(“http://iiif.io/api/presentation/3.0/example/fixtures/1/manifest.json“)) pprint.pprint( compact( frame(manifest, “http://iiif.io/api/presentation/3/manifest_frame.json“), “http://iiif.io/api/presentation/3/context.json“) )

```