JSON-LD 上下文与压缩

PurRDF 有三种显式的 JSON-LD/YAML-LD 序列化模式：

• expanded 保留逐字节冻结的空 @context 表示；
• context 把调用方的前缀映射或本地 JSON-LD 1.1 上下文编译一次，并应用规范性的压缩；
• derived 仅依据数据集中的绝对 IRI，以确定性方式分配中性的 ns0、ns1、… 别名。它从不发明词汇表，也从不推断 @vocab。

RDF 数据集不保留来自 Turtle、JSON-LD 或其他源语法的前缀声明。当这些声明属于应用策略时，请显式提供它们。所有可配置的接口都消费同一个封闭的 version-1 JSON 文档，并在输出之前拒绝重复成员、未知字段、无效上下文、只能经网络获取的上下文引用、环以及超出资源上限的情况。

{
  "version": 1,
  "mode": "context",
  "prefixes": {
    "ex": "https://example.org/",
    "schema": "https://schema.org/"
  },
  "yaml_schema_url": "https://example.org/purrdf.schema.json"
}

Rust

#![allow(unused)]
fn main() {
use purrdf::{
    JsonLdSerializeOptions, SerializeGraph, parse_dataset, serialize_dataset,
    serialize_dataset_to_jsonld_with_options,
};

let dataset = parse_dataset(
    b"<https://example.org/alice> <https://schema.org/name> \"Alice\" .",
    "application/n-triples",
    None,
)?;
let options = JsonLdSerializeOptions::prefixes([
    ("ex", "https://example.org/"),
    ("schema", "https://schema.org/"),
])?;
let jsonld = serialize_dataset_to_jsonld_with_options(&dataset, &options)?;
assert!(jsonld.contains("\"schema:name\""));
let reopened = parse_dataset(jsonld.as_bytes(), "application/ld+json", None)?;
assert_eq!(
    serialize_dataset(&reopened, "application/n-quads", SerializeGraph::Dataset)?,
    serialize_dataset(&dataset, "application/n-quads", SerializeGraph::Dataset)?,
);
Ok::<(), purrdf::RdfDiagnostic>(())
}

当同一个应用上下文用于许多数据集时，请保留一个 CompiledJsonLdContext（或 JsonLdSerializeOptions::compiled）。JsonLdContextRegistry 只从调用方提供的不可变本地文档中解析上下文 IRI 与 @import；PurRDF 从不经由网络加载上下文。

CLI

把带版本的文档写入文件，然后把它传给任何产生 RDF 的 CLI 路径：

purrdf --jsonld-options context.json convert --from turtle --to jsonld input.ttl output.jsonld

对于非 JSON-LD/YAML-LD 输出、规范化输出、非图形式的 SPARQL 结果以及载体投影，该选项会被拒绝，而不是被忽略。

Python

import json
import purrdf

options = json.dumps({
    "version": 1,
    "mode": "context",
    "prefixes": {"ex": "https://example.org/"},
})
context = purrdf.CompiledJsonLdContext(options)
text = purrdf.serialize_jsonld(
    nquads,
    format=purrdf.RdfFormat.N_QUADS,
    output_format="jsonld",
    context=context,
)

Store.dump、MutableDataset.dump、不可变的 RdfDataset 以及 RDFLib 兼容层的 Graph.serialize 接口都接受同一配置。在兼容层图上显式绑定的前缀，会成为其调用方上下文。

JavaScript 与 WebAssembly

const options = JSON.stringify({
  version: 1,
  mode: "context",
  prefixes: { ex: "https://example.org/" },
});
const context = new CompiledJsonLdContext(options);
const text = dataset.serializeWithContext("jsonld", context);

一次性请求请使用 serializeConfigured。QueryEngine 为 CONSTRUCT 与 DESCRIBE 图结果提供对应的可配置方法，playground 的 worker 在其序列化路径上也接受同一份选项文档。

C

用 purrdf_jsonld_context_compile 编译选项，用 purrdf_serialize_jsonld_configured 复用返回的 PurrdfJsonLdContext，然后用 purrdf_jsonld_context_free 释放它。序列化器只接受恰好一个选项字节切片或一个已编译句柄。缓冲区与错误仍遵循 libpurrdf 通常的所有权规则。

YAML-LD 使用同一个上下文透镜（context lens）。其可选的模式 URL 只改变确定性的 YAML 语言服务器头部；它不改变 RDF 语义。