TypeSpec JSON Schema Emitter 使用指南调用方式与全部 Emitter 配置项详解【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec本指南完整讲解typespec/json-schemaEmitter 的两种调用方式命令行与tspconfig.yaml配置以及全部 8 个 Emitter 选项的语义、默认值与使用场景并结合本仓库源码说明每个选项在底层是如何生效的。读完本文你将能独立完成「TypeSpec 模型 → JSON SchemaJSON/YAML」的编译配置并针对 64 位整数、多态模型、Schema 打包等常见场景做出正确的选项决策。准备工作安装与最小示例typespec/json-schema是 TypeSpec 官方的 JSON Schema 生成器其包描述位于 packages/json-schema/package.json安装方式npm install typespec/json-schema生成 Schema 前需要先用jsonSchema装饰器标记要输出的声明。装饰器定义在 packages/json-schema/lib/main.tsp加在命名空间上会输出该命名空间内的所有模型加在某个声明上则只输出该声明可选参数baseUri/id。一个最小可编译示例import typespec/json-schema; using JsonSchema; jsonSchema namespace Example; model Car { make: string; modelName: string; }一、两种调用方式1. 命令行方式在包含main.tsp的目录下执行tsp compile . --emittypespec/json-schematsp compile会读取当前目录的 TypeSpec 入口文件编译后仅调用typespec/json-schema这一个 Emitter。命令行的优势是适合快速验证无需维护配置文件。2. 配置文件方式在tspconfig.yaml中声明启用该 Emitteremit: - typespec/json-schema此时执行不带--emit的tsp compile .即可生效。配置文件方式便于把 Emitter 及选项固化到项目中团队共享同一套输出行为。3. 在配置中扩展选项emit下列出启用的 Emitteroptions下以 Emitter 包名为键、以键值对形式给出该 Emitter 的选项emit: - typespec/json-schema options: typespec/json-schema: option: value将option: value替换为下文任一实际选项即可例如file-type: json。二、Emitter 选项总览所有选项均定义在 packages/json-schema/src/lib.ts 的JSONSchemaEmitterOptions接口与EmitterOptionsSchema中编译时会据此做类型校验additionalProperties: false即未知选项会被拒绝。汇总如下选项类型默认值作用emitter-output-dirabsolutePath{output-dir}/typespec/json-schema输出目录file-typeyaml \| json由输出文件扩展名推断序列化格式int64-strategystring \| number未显式指定时按string处理64 位整数在 Schema 中的表示bundleIdstring无将全部 Schema 打包进单个文档emitAllModelsbooleanfalse忽略jsonSchema输出所有模型emitAllRefsbooleanfalse输出所有被引用类型的 Schemaseal-object-schemasbooleanfalse默认封闭对象 Schemapolymorphic-models-strategyignore \| oneOf \| anyOfignore带discriminator模型的多态输出策略下面逐项展开。三、逐项详解emitter-output-dir类型absolutePath作用指定 Emitter 的输出目录。默认值为{output-dir}/typespec/json-schema即编译器输出目录下的typespec/json-schema子目录output-dir本身由编译器的输出目录配置决定可在tspconfig.yaml顶层通过output-dir设置。显式配置示例options: typespec/json-schema: emitter-output-dir: ./schemas从源码看输出目录同时决定了 Schema 默认$id的生成基准json-schema-emitter.ts 中#getDeclId会取emitterOutputDir与当前源文件路径的相对关系来构造$id因此调整输出目录会直接反映到生成的 Schema ID 上。file-type类型yaml | json作用选择 Schema 的序列化格式。设置为json时输出.json文件否则输出.yaml文件。序列化逻辑位于 json-schema-emitter.ts 的#serializeSourceFileContentJSON 使用 4 空格缩进的JSON.stringifyYAML 使用yaml库序列化并显式关闭aliasDuplicateObjects、设置lineWidth: 0避免长行被折行。文件扩展名同样由该选项决定#fileExtension见同文件 L1181-L1183。options: typespec/json-schema: file-type: jsonint64-strategy类型string | number作用决定 64 位整数在「线上传输」时的表示方式string序列化为字符串。JavaScript 的number无法精确表示全部 int64/uint64 取值范围字符串形式跨语言互操作性最好是推荐选择number序列化为数字。直观但可能丢失精度互操作性差。底层实现在 json-schema-emitter.ts 的#getSchemaForStdScalarsint64/uint64在string策略下输出{ type: string }在number策略下输出{ type: integer }——代码注释明确说明之所以不附带minimum/maximum是因为这些边界值无法在不损失精度的情况下写成字面量。注意int8~int32、uint8~uint32等小整数始终输出为带精确minimum/maximum的integer不受此选项影响。options: typespec/json-schema: int64-strategy: stringbundleId类型string作用提供bundleId后所有应输出的 Schema 不再各自生成文件而是被打包进单个JSON Schema 文档各 Schema 挂到根文档的$defs下bundleId同时作为根文档的$id和输出文件名。打包实现在 json-schema-emitter.ts 的writeOutput遍历所有shouldEmit的源文件构造{ $schema, $id: bundleId, $defs }结构再写入{emitterOutputDir}/{bundleId}。被引用但自身不作为根 Schema 输出的类型也会通过bundledRefs机制递归并入$defs见 L1041-L1058避免引用悬空。相关打包测试可参考 packages/json-schema/test/bundling.test.ts。options: typespec/json-schema: bundleId: schemas.jsonemitAllModels类型boolean作用为true时所有模型声明都会输出为 JSON Schema无需再逐个添加jsonSchema装饰器。适合「整个规范全部转 Schema」的场景。该选项在 Emitter 入口处直接改变遍历策略packages/json-schema/src/on-emit.ts 的$onEmit中当emitAllModels为真时调用emitter.emitProgram({ emitTypeSpecNamespace: false })走全程序发射路径否则仅对getJsonSchemaTypes()从 decorators.ts 收集的、被jsonSchema标记的命名空间/声明逐个emitType。同时#shouldEmitRootSchemajson-schema-emitter.ts也会把emitAllModels作为判定「是否作为根 Schema 输出」的条件之一。options: typespec/json-schema: emitAllModels: trueemitAllRefs类型boolean作用为true时所有被引用的类型都会作为独立 JSON Schema 文件输出即使该类型没有jsonSchema装饰器、也不处于带jsonSchema的命名空间内。即把引用链上的每一个类型都「提升」为可独立寻址的 Schema 文档。与emitAllModels相同它也会在#shouldEmitRootSchema中参与根 Schema 判定json-schema-emitter.ts。区别在于emitAllModels关注「声明本身是否输出」emitAllRefs关注「被引用者是否也输出」。seal-object-schemas类型boolean默认值false作用为true时以对象 Schema 输出的模型若未显式指定会默认加上unevaluatedProperties: { not: {} }即「除声明属性外不允许额外属性」实现 Schema 封闭。实现位于 json-schema-emitter.ts 的#applyModelIndexer如果模型有 indexer如Record...会优先把 indexer 值类型发射为unevaluatedProperties否则在seal-object-schemas开启且模型没有派生模型时才写入{ not: {} }——注意「有派生模型时不封闭」这一细节避免封闭后破坏继承体系。对象字面量modelLiteral同样会应用该逻辑。options: typespec/json-schema: seal-object-schemas: truepolymorphic-models-strategy类型ignore | oneOf | anyOf默认值ignore作用决定带discriminator装饰器多态基类的模型如何发射ignore默认作为普通对象 Schema 发射派生模型通过allOf引用基类继承关系由allOf表达oneOf发射一个oneOf联合引用所有派生模型闭合联合anyOf发射一个anyOf联合引用所有派生模型开放联合。关键行为使用oneOf或anyOf时派生模型会把基类的全部属性内联而非allOf引用从而避免「基类通过 oneOf/anyOf 引用派生类、派生类又通过 allOf 引用基类」造成的循环引用。相关实现见 json-schema-emitter.tsmodelDeclaration中的策略分支与#isBaseUsingDiscriminatedUnion以及 L805-L953#createDiscriminatedUnionDeclaration、属性内联#getAllModelProperties/#getAllRequiredModelProperties。另外若判别属性类型包含string开放判别器发射器还会自动追加一个「兜底变体」匹配未知判别值见#isOpenDiscriminator与#createCatchAllVariant。相关测试可参考 packages/json-schema/test/discriminator.test.ts。options: typespec/json-schema: polymorphic-models-strategy: oneOf四、与装饰器生态的配合Emitter 选项解决「怎么输出」而「输出什么」由装饰器决定。除jsonSchema外lib/main.tsp 还提供baseUri、id控制 Schema ID、oneOf联合强制用oneOf、multipleOf、contains/minContains/maxContains、uniqueItems、minProperties/maxProperties、contentEncoding/contentMediaType/contentSchema、prefixItems、extension注入自定义关键字等约束由 json-schema-emitter.ts 的#applyConstraints统一映射为 JSON Schema 关键字如minLength、pattern、format、deprecated等文档、示例与标准标量类型int8~int64、decimal、plainDate、utcDateTime、bytes等的 Schema 映射也都在该文件中可作为深入阅读的入口。五、常见组合示例一个覆盖多种选项的完整tspconfig.yamlemit: - typespec/json-schema options: typespec/json-schema: file-type: json int64-strategy: string seal-object-schemas: true polymorphic-models-strategy: oneOf bundleId: bundle.json六、小结用tsp compile . --emittypespec/json-schema或tspconfig.yaml的emit即可启用选项统一写在options[typespec/json-schema]下。8 个选项各司其职file-type/emitter-output-dir控制输出形态int64-strategy处理大整数精度bundleId/emitAllModels/emitAllRefs控制发射范围与打包方式seal-object-schemas控制 Schema 封闭性polymorphic-models-strategy控制多态模型的联合表达。所有选项都在 packages/json-schema/src/lib.ts 有声明式校验在 packages/json-schema/src/json-schema-emitter.ts 有对应实现可在排查输出异常时对照源码定位。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
TypeSpec JSON Schema Emitter 使用指南：调用方式与全部 Emitter 配置项详解
TypeSpec JSON Schema Emitter 使用指南调用方式与全部 Emitter 配置项详解【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec本指南完整讲解typespec/json-schemaEmitter 的两种调用方式命令行与tspconfig.yaml配置以及全部 8 个 Emitter 选项的语义、默认值与使用场景并结合本仓库源码说明每个选项在底层是如何生效的。读完本文你将能独立完成「TypeSpec 模型 → JSON SchemaJSON/YAML」的编译配置并针对 64 位整数、多态模型、Schema 打包等常见场景做出正确的选项决策。准备工作安装与最小示例typespec/json-schema是 TypeSpec 官方的 JSON Schema 生成器其包描述位于 packages/json-schema/package.json安装方式npm install typespec/json-schema生成 Schema 前需要先用jsonSchema装饰器标记要输出的声明。装饰器定义在 packages/json-schema/lib/main.tsp加在命名空间上会输出该命名空间内的所有模型加在某个声明上则只输出该声明可选参数baseUri/id。一个最小可编译示例import typespec/json-schema; using JsonSchema; jsonSchema namespace Example; model Car { make: string; modelName: string; }一、两种调用方式1. 命令行方式在包含main.tsp的目录下执行tsp compile . --emittypespec/json-schematsp compile会读取当前目录的 TypeSpec 入口文件编译后仅调用typespec/json-schema这一个 Emitter。命令行的优势是适合快速验证无需维护配置文件。2. 配置文件方式在tspconfig.yaml中声明启用该 Emitteremit: - typespec/json-schema此时执行不带--emit的tsp compile .即可生效。配置文件方式便于把 Emitter 及选项固化到项目中团队共享同一套输出行为。3. 在配置中扩展选项emit下列出启用的 Emitteroptions下以 Emitter 包名为键、以键值对形式给出该 Emitter 的选项emit: - typespec/json-schema options: typespec/json-schema: option: value将option: value替换为下文任一实际选项即可例如file-type: json。二、Emitter 选项总览所有选项均定义在 packages/json-schema/src/lib.ts 的JSONSchemaEmitterOptions接口与EmitterOptionsSchema中编译时会据此做类型校验additionalProperties: false即未知选项会被拒绝。汇总如下选项类型默认值作用emitter-output-dirabsolutePath{output-dir}/typespec/json-schema输出目录file-typeyaml \| json由输出文件扩展名推断序列化格式int64-strategystring \| number未显式指定时按string处理64 位整数在 Schema 中的表示bundleIdstring无将全部 Schema 打包进单个文档emitAllModelsbooleanfalse忽略jsonSchema输出所有模型emitAllRefsbooleanfalse输出所有被引用类型的 Schemaseal-object-schemasbooleanfalse默认封闭对象 Schemapolymorphic-models-strategyignore \| oneOf \| anyOfignore带discriminator模型的多态输出策略下面逐项展开。三、逐项详解emitter-output-dir类型absolutePath作用指定 Emitter 的输出目录。默认值为{output-dir}/typespec/json-schema即编译器输出目录下的typespec/json-schema子目录output-dir本身由编译器的输出目录配置决定可在tspconfig.yaml顶层通过output-dir设置。显式配置示例options: typespec/json-schema: emitter-output-dir: ./schemas从源码看输出目录同时决定了 Schema 默认$id的生成基准json-schema-emitter.ts 中#getDeclId会取emitterOutputDir与当前源文件路径的相对关系来构造$id因此调整输出目录会直接反映到生成的 Schema ID 上。file-type类型yaml | json作用选择 Schema 的序列化格式。设置为json时输出.json文件否则输出.yaml文件。序列化逻辑位于 json-schema-emitter.ts 的#serializeSourceFileContentJSON 使用 4 空格缩进的JSON.stringifyYAML 使用yaml库序列化并显式关闭aliasDuplicateObjects、设置lineWidth: 0避免长行被折行。文件扩展名同样由该选项决定#fileExtension见同文件 L1181-L1183。options: typespec/json-schema: file-type: jsonint64-strategy类型string | number作用决定 64 位整数在「线上传输」时的表示方式string序列化为字符串。JavaScript 的number无法精确表示全部 int64/uint64 取值范围字符串形式跨语言互操作性最好是推荐选择number序列化为数字。直观但可能丢失精度互操作性差。底层实现在 json-schema-emitter.ts 的#getSchemaForStdScalarsint64/uint64在string策略下输出{ type: string }在number策略下输出{ type: integer }——代码注释明确说明之所以不附带minimum/maximum是因为这些边界值无法在不损失精度的情况下写成字面量。注意int8~int32、uint8~uint32等小整数始终输出为带精确minimum/maximum的integer不受此选项影响。options: typespec/json-schema: int64-strategy: stringbundleId类型string作用提供bundleId后所有应输出的 Schema 不再各自生成文件而是被打包进单个JSON Schema 文档各 Schema 挂到根文档的$defs下bundleId同时作为根文档的$id和输出文件名。打包实现在 json-schema-emitter.ts 的writeOutput遍历所有shouldEmit的源文件构造{ $schema, $id: bundleId, $defs }结构再写入{emitterOutputDir}/{bundleId}。被引用但自身不作为根 Schema 输出的类型也会通过bundledRefs机制递归并入$defs见 L1041-L1058避免引用悬空。相关打包测试可参考 packages/json-schema/test/bundling.test.ts。options: typespec/json-schema: bundleId: schemas.jsonemitAllModels类型boolean作用为true时所有模型声明都会输出为 JSON Schema无需再逐个添加jsonSchema装饰器。适合「整个规范全部转 Schema」的场景。该选项在 Emitter 入口处直接改变遍历策略packages/json-schema/src/on-emit.ts 的$onEmit中当emitAllModels为真时调用emitter.emitProgram({ emitTypeSpecNamespace: false })走全程序发射路径否则仅对getJsonSchemaTypes()从 decorators.ts 收集的、被jsonSchema标记的命名空间/声明逐个emitType。同时#shouldEmitRootSchemajson-schema-emitter.ts也会把emitAllModels作为判定「是否作为根 Schema 输出」的条件之一。options: typespec/json-schema: emitAllModels: trueemitAllRefs类型boolean作用为true时所有被引用的类型都会作为独立 JSON Schema 文件输出即使该类型没有jsonSchema装饰器、也不处于带jsonSchema的命名空间内。即把引用链上的每一个类型都「提升」为可独立寻址的 Schema 文档。与emitAllModels相同它也会在#shouldEmitRootSchema中参与根 Schema 判定json-schema-emitter.ts。区别在于emitAllModels关注「声明本身是否输出」emitAllRefs关注「被引用者是否也输出」。seal-object-schemas类型boolean默认值false作用为true时以对象 Schema 输出的模型若未显式指定会默认加上unevaluatedProperties: { not: {} }即「除声明属性外不允许额外属性」实现 Schema 封闭。实现位于 json-schema-emitter.ts 的#applyModelIndexer如果模型有 indexer如Record...会优先把 indexer 值类型发射为unevaluatedProperties否则在seal-object-schemas开启且模型没有派生模型时才写入{ not: {} }——注意「有派生模型时不封闭」这一细节避免封闭后破坏继承体系。对象字面量modelLiteral同样会应用该逻辑。options: typespec/json-schema: seal-object-schemas: truepolymorphic-models-strategy类型ignore | oneOf | anyOf默认值ignore作用决定带discriminator装饰器多态基类的模型如何发射ignore默认作为普通对象 Schema 发射派生模型通过allOf引用基类继承关系由allOf表达oneOf发射一个oneOf联合引用所有派生模型闭合联合anyOf发射一个anyOf联合引用所有派生模型开放联合。关键行为使用oneOf或anyOf时派生模型会把基类的全部属性内联而非allOf引用从而避免「基类通过 oneOf/anyOf 引用派生类、派生类又通过 allOf 引用基类」造成的循环引用。相关实现见 json-schema-emitter.tsmodelDeclaration中的策略分支与#isBaseUsingDiscriminatedUnion以及 L805-L953#createDiscriminatedUnionDeclaration、属性内联#getAllModelProperties/#getAllRequiredModelProperties。另外若判别属性类型包含string开放判别器发射器还会自动追加一个「兜底变体」匹配未知判别值见#isOpenDiscriminator与#createCatchAllVariant。相关测试可参考 packages/json-schema/test/discriminator.test.ts。options: typespec/json-schema: polymorphic-models-strategy: oneOf四、与装饰器生态的配合Emitter 选项解决「怎么输出」而「输出什么」由装饰器决定。除jsonSchema外lib/main.tsp 还提供baseUri、id控制 Schema ID、oneOf联合强制用oneOf、multipleOf、contains/minContains/maxContains、uniqueItems、minProperties/maxProperties、contentEncoding/contentMediaType/contentSchema、prefixItems、extension注入自定义关键字等约束由 json-schema-emitter.ts 的#applyConstraints统一映射为 JSON Schema 关键字如minLength、pattern、format、deprecated等文档、示例与标准标量类型int8~int64、decimal、plainDate、utcDateTime、bytes等的 Schema 映射也都在该文件中可作为深入阅读的入口。五、常见组合示例一个覆盖多种选项的完整tspconfig.yamlemit: - typespec/json-schema options: typespec/json-schema: file-type: json int64-strategy: string seal-object-schemas: true polymorphic-models-strategy: oneOf bundleId: bundle.json六、小结用tsp compile . --emittypespec/json-schema或tspconfig.yaml的emit即可启用选项统一写在options[typespec/json-schema]下。8 个选项各司其职file-type/emitter-output-dir控制输出形态int64-strategy处理大整数精度bundleId/emitAllModels/emitAllRefs控制发射范围与打包方式seal-object-schemas控制 Schema 封闭性polymorphic-models-strategy控制多态模型的联合表达。所有选项都在 packages/json-schema/src/lib.ts 有声明式校验在 packages/json-schema/src/json-schema-emitter.ts 有对应实现可在排查输出异常时对照源码定位。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
