@ effect/schema-org (帮助)

schema.org作为 Effect Schema 类:构建一个 JSON-LD 图形,将其安全地序列化为 <script> 元素,并对照 schema.org 自己的词汇下线. effect 是唯一的对等依赖, 并且根本没有运行时间的依赖性 —— 词汇以生成的 TypeScript 来销售, 所以这里没有到达网络 .

预1.0.0。 。 。 . 此软件包是 @effected/* 在稳定基础上建造的工具包 效应v4(effect ~4.1.0) 并仍在 0.x 发展。 稳定效果 制作一个工具箱 1.0.0 可能,不是自动的。 为了保持你的 effect 财务报告和审定财务报表 @effect/* 该工具包在线上构建和测试、安装 @effected/pnpm-plugin-effected。 。 。 .

稳定:不稳定. 此软件包的 API 表面尚未考虑 完成并可能改变 0.x 释放 定一个确切的版本——甚至 标记软件包 稳定 在此之前 1.0.0 可以引入突破性更改 和精确的针 变成一个类型检查错误 而不是一个 跑步时间惊喜。 完全政策: 释放策略。 。 。 .

为什么

结构化数据通常以对象字面形式组装,并投入模板 JSON.stringify,它得到两件事 错误同时。 第一个是安全错误: JSON.stringify 无法逃脱 <因此,有一个描述包含文字 </script> 提前关闭 JSON-LD 块, 并在页面中注入任何后续内容 。 第二个是更安静的——schema.org有一个词汇,你的对象字面上没有,词汇上没有定义的假象属性,只是被每个消费者忽略,在任何地方都没有出错.

这个包在源头都修好了. toScriptBody() 是唯一的文本序列器,它是被逃脱的,所以无法通过选择错误的函数来到达注射大小写。 词汇船卖出,所以一个建造步骤可以拒绝一个错误的地产离线,在CI,没有网络呼叫和爬行者往返.

安装

npm install @effected/schema-org effect

pnpm add @effected/schema-org effect

需要节点.js~~24.11.0.

全体 @effected/* 软件包仅为无害环境管理:只公布出口地图 import 条件,所以 require() 包括解析 CJS 模式的工具 —— 与节点失败 ERR_PACKAGE_PATH_NOT_EXPORTED 而不是装入不存在的 CJS 建筑。 从ES模块导入.

快开始

将节点组合成图表,然后序列化:

import { JsonLdDocument, NodeRef, SoftwareSourceCode, TechArticle } from "@effected/schema-org";
import { Result } from "effect";

const built = JsonLdDocument.buildResult([
  SoftwareSourceCode.make({ "@id": "https://example.com/pkg#source", name: "example", version: "1.2.3" }),
  TechArticle.make({
    "@id": "https://example.com/pkg/docs#intro",
    headline: "Getting started </script>",
    isPartOf: [NodeRef.to("https://example.com/pkg#source")],
  }),
]);

console.log(Result.getOrThrow(built).toScriptBody());
// {"@context":"https://schema.org","@graph":[{"@id":"https://example.com/pkg#source","@type":"SoftwareSourceCode","name":"example","version":"1.2.3"},{"@id":"https://example.com/pkg/docs#intro","@type":"TechArticle","isPartOf":[{"@id":"https://example.com/pkg#source"}],"headline":"Getting started </script>"}]}

然后逐字地将身体嵌入:

<script type="application/ld+json">BODY</script>

buildResult 是切入点,而不是 make数字 : Schema.Class 储备金 make 它的原始结构构造器, 它没有进行身份检查. JsonLdDocument.build 这是 Effect 双 buildResult,从它衍生出来——同步形式是原始的,所以静态站点的建筑从不需要构造出跑时.

三件事都失败了 全部都是呼叫器错误 而不是要向用户报告的东西:一个畸形 @id (单位:千美元)InvalidNodeIdError),两个节点声称一个 @id (单位:千美元)DuplicateNodeIdError),以及一个囊括所有密钥与打字场相撞(ConflictingTermErrorA级 轻而易举的引用是合法的 ——指向另一页描述的节点是正确的JSON-LD——所以读作 danglingReferences 自己决定你的图表是否应该关闭.

连载器才是重点

你图中的每个字符串都来自别人写的散文 包含文字的描述 </script> 提前关闭 JSON- LD 块并插入标记到您的页面,以及 JSON.stringify 不能逃脱它.

toScriptBody() 逃脱 <, (中文(简体) ), > 财务报告和审定财务报表 & 字符串后。 所有三个都是有效的 JSON 字符串逃出,所以一个解析器可以看到原始字符;没有 < 在体内,也没有 </script 也没有 <!-- ,元素不能从内部关闭。 这个 & 在文档作为 XHTML 服务时,另将输出保存良好。 出逃是"一能",所以第二次通过输出是安全的,而不是"双能".

故意没有未脱逃的文本序列器 . 所逃出的产出并不是一种受限制的形式——对于任何描述它的人来说,它是完全相同的,那就是每一个人——所以第二个切入点只能被错误地选择.

toJsonLd() 返回电线窗体为纯值,用于串行 JSON-LD 本身的框架. 如果您正在生成文本, 请不要使用 —— 说 JSON.stringify(doc.toJsonLd()) 重新引入此软件包的准确错误来防止 .

校验离线

import { Conformance, Vocabulary } from "@effected/schema-org/validate";

console.log(Vocabulary.version);
// 30.0

for (const issue of Conformance.check(doc)) {
  console.error(issue._tag, issue.message);
}
// PropertyNotOnType https://example.com/pkg#source: schema.org does not define "softwareVersion" on SoftwareSourceCode

Conformance.check 完全——它从不失败,从不扔出,因为报告不是一个失败模式. Conformance.validateResult 是建在它的上方的大门, 返回图表或一个 NonConformantGraphError 携带每期 Conformance.validate 这是它的 Effect 双胞胎 默认只关闭大门的结构类型; ConformanceOptions 拓宽其范围,以贬低和忽略引用.

词汇被卖出,所以大门会断线运行,在CI中没有网络呼叫. 它抓住了实际发生的失败——不是JSON的畸形,但一个可信的地产schema.org没有定义该类型. softwareVersion 编号 SoftwareSourceCode 是犬科的例子: 它的读取正确,序列化精细,在下游被默默地忽略. (财产是: version. ) (中文(简体) )

合法性通过全面解决 rdfs:subClassOf 祖先封闭,所以继承的财产被接受—— license 仅公布于 CreativeWork,这是合法的 SoftwareSourceCode 因为那个链子.

从中导入 ./validate 子路径. 词汇表是只使用图表的消费者所避免的全部:导入 @effected/schema-org 装入节点类和序列器. ./validate 重新导出节点类 只类型,用于标注签字——通过签字达到某种价值,例如: NodeRef.to,以“只提及类型”失败。 从根导入值 .

符合标准不是谷歌富收资格. Google要求属性schema.org没有,并按自己的时间表改变其政策. 这告诉你schema.org定义了这个术语;它不会给你带来丰富的结果.

此软件包没有做什么

• 薄荷 @id编号. 它们是您命名空间中的IRI; 软件包无法了解您的基址, 也永远不会获得一个 .
• 将您的域映射到节点上 . 那幅地图是你的.
• 解码 JSON-LD 回打出节点. 编码方向是本出品中被支持的方向,而测试会把不对称的分出来,这样它就不能意外地开始半工半读.
• 模拟所有 schema.org. 6个节点类型,加一个开口 additional 涵盖任何术语——验证人随后检查.

特征

• SoftwareSourceCode, (中文(简体) ), TechArticle, (中文(简体) ), APIReference, (中文(简体) ), Person, (中文(简体) ), Organization, (中文(简体) ), CreativeWork ——六个节点类. 每个节点都需要 @id 其它所有领域都是可选的,可以当作 undefined,在序列化时放弃.
• ThingFields, (中文(简体) ), CreativeWorkFields, (中文(简体) ), TechArticleFields ——共享字段记录节点类组装自来,为消费楼出品,此套件不作型号的节点.
• NodeRef - 指另一个节点,由 @id,与 to (未检查,在构建时验证),同步 toCheckedResult 联 合 国 Effect 双向 toChecked,则 isValidId 上观相. 节点价值的财产持有 NodeRef从来没有嵌入式节点.
• JsonLdDocument ——图: buildResult 编号 : build 收集并检查身份, nodeIds 财务报告和审定财务报表 danglingReferences 检查, toScriptBody() 要序列化页面 toJsonLd() 一个将JSON-LD本身序列化的框架.
• Vocabulary 阅读API version, (中文(简体) ), hasType, (中文(简体) ), hasProperty, (中文(简体) ), ancestorsOf, (中文(简体) ), propertiesOf, (中文(简体) ), isPropertyOn 财务报告和审定财务报表 supersededBy,可自行使用,用于从未构建图表的工具.
• Conformance ——离线合规检查,报告 UnknownTerm, (中文(简体) ), PropertyNotOnType, (中文(简体) ), DeprecatedType, (中文(简体) ), DeprecatedProperty 财务报告和审定财务报表 DanglingReference 每个问题都有一行 message。 。 。 .
• 重复的属性总是一个数组, 即使是长度为一的- 包括 license,因为 MIT AND Apache-2.0 这是一种真正的双重许可证 并且崩溃 这将是沉默的数据损失.

许可证

麻省理工学院