История

Timothee Guerin 49004b60d5 Update dependencies (#3948 ) New pr from this branch as it had some weird docusaurus issue not reproducable anywhere else and just changing branch fixes it somehow https://github.com/microsoft/typespec/pull/3934 Notable: - vitest: 2.x - prettier update that does a minor formatting change by adding parentheses in some ternary expression		2024-07-23 21:02:34 +00:00
..
.tspd/docs	Render README from refdoc (#2242 )	2023-08-07 22:24:56 +00:00
generated-defs	Add oneOf to JSON Schema (#3557 )	2024-06-11 17:11:53 +00:00
lib	Add oneOf to JSON Schema (#3557 )	2024-06-11 17:11:53 +00:00
src	Dependency updates July 2024 (#3718 )	2024-07-01 21:42:11 +00:00
test	Add oneOf to JSON Schema (#3557 )	2024-06-11 17:11:53 +00:00
CHANGELOG.json	Prepare Publish for January Release (#2816 )	2024-01-24 11:14:23 -08:00
CHANGELOG.md	Bump versions for release 0.57 (#3855 )	2024-07-17 00:10:54 +00:00
README.md	Add oneOf to JSON Schema (#3557 )	2024-06-11 17:11:53 +00:00
package.json	Update dependencies (#3948 )	2024-07-23 21:02:34 +00:00
tsconfig.config.json	Vitest improvements: vitest-ui, watch mode for deps, debug config (#2791 )	2024-01-22 09:56:55 -08:00
tsconfig.json	Generate TypeScript decorator signatures from `extern dec` (#2122 )	2024-03-19 23:08:59 +00:00
vitest.config.ts	Vitest improvements: vitest-ui, watch mode for deps, debug config (#2791 )	2024-01-22 09:56:55 -08:00

README.md

@typespec/json-schema

TypeSpec library for emitting TypeSpec to JSON Schema and converting JSON Schema to TypeSpec

Install

npm install @typespec/json-schema

Usage

Add the @jsonSchema decorator to any types or namespaces you want to emit as JSON Schema.

import "@typespec/json-schema";

using TypeSpec.JsonSchema;

@jsonSchema
namespace Example;

model Car {
  make: string;
  model: string;
}

Emitter

Usage

Via the command line

tsp compile . --emit=@typespec/json-schema

Via the config

emit:
  - "@typespec/json-schema"

Emitter options

`file-type`

Type: "yaml" | "json"

Serialize the schema as either yaml or json.

`int64-strategy`

Type: "string" | "number"

How to handle 64 bit integers on the wire. Options are:

string: serialize as a string (widely interoperable)
number: serialize as a number (not widely interoperable)

`bundleId`

Type: string

When provided, bundle all the schemas into a single json schema document with schemas under $defs. The provided id is the id of the root document and is also used for the file name.

`emitAllModels`

Type: boolean

When true, emit all model declarations to JSON Schema without requiring the @jsonSchema decorator.

`emitAllRefs`

Type: boolean

When true, emit all references as json schema files, even if the referenced type does not have the @jsonSchema decorator or is not within a namespace with the @jsonSchema decorator.

Decorators

TypeSpec.JsonSchema

@baseUri
@contains
@contentEncoding
@contentMediaType
@contentSchema
@extension
@id
@jsonSchema
@maxContains
@maxProperties
@minContains
@minProperties
@multipleOf
@oneOf
@prefixItems
@uniqueItems

`@baseUri`

Set the base URI for any schemas emitted from types within this namespace.

@TypeSpec.JsonSchema.baseUri(baseUri: valueof string)

Target

Namespace

Parameters

Name	Type	Description
baseUri	`valueof string`	the base URI. Schema IDs inside this namespace are relative to this URI.

`@contains`

Specify that the array must contain at least one instance of the provided type. Use @minContains and @maxContains to customize how many instances to expect.

@TypeSpec.JsonSchema.contains(value: unknown)

Target

unknown[] | ModelProperty

Parameters

Name	Type	Description
value	`unknown`	The type the array must contain.

`@contentEncoding`

Specify the encoding used for the contents of a string.

@TypeSpec.JsonSchema.contentEncoding(value: valueof string)

Target

string | ModelProperty

Parameters

Name	Type	Description
value	`valueof string`

`@contentMediaType`

Specify the content type of content stored in a string.

@TypeSpec.JsonSchema.contentMediaType(value: valueof string)

Target

string | ModelProperty

Parameters

Name	Type	Description
value	`valueof string`	the media type of the string contents

`@contentSchema`

Specify the schema for the contents of a string when interpreted according to the content's media type and encoding.

@TypeSpec.JsonSchema.contentSchema(value: unknown)

Target

string | ModelProperty

Parameters

Name	Type	Description
value	`unknown`	the schema of the string contents

`@extension`

Specify a custom property to add to the emitted schema. Useful for adding custom keywords and other vendor-specific extensions. The value will be converted to a schema unless the parameter is wrapped in the Json<Data> template. For example, @extension("x-schema", { x: "value" }) will emit a JSON schema value for x-schema, whereas @extension("x-schema", Json<{x: "value"}>) will emit the raw JSON code {x: "value"}.

@TypeSpec.JsonSchema.extension(key: valueof string, value: unknown)

Target

unknown

Parameters

Name	Type	Description
key	`valueof string`	the name of the keyword of vendor extension, e.g. `x-custom`.
value	`unknown`	the value of the keyword. Will be converted to a schema unless wrapped in `Json<Data>`.

`@id`

Specify the JSON Schema id. If this model or a parent namespace has a base URI, the provided ID will be relative to that base URI.

By default, the id will be constructed based on the declaration's name.

@TypeSpec.JsonSchema.id(id: valueof string)

Target

unknown

Parameters

Name	Type	Description
id	`valueof string`	the id of the JSON schema for this declaration.

`@jsonSchema`

Add to namespaces to emit models within that namespace to JSON schema. Add to another declaration to emit that declaration to JSON schema.

Optionally, for namespaces, you can provide a baseUri, and for other declarations, you can provide the id.

@TypeSpec.JsonSchema.jsonSchema(baseUri?: valueof string)

Target

unknown

Parameters

Name	Type	Description
baseUri	`valueof string`	Schema IDs are interpreted as relative to this URI.

`@maxContains`

Specify that the array must contain at most some number of the types provided by the contains decorator.

@TypeSpec.JsonSchema.maxContains(value: valueof int32)

Target

unknown[] | ModelProperty

Parameters

Name	Type	Description
value	`valueof int32`	The maximum number of instances the array must contain

`@maxProperties`

Specify the maximum number of properties this object can have.

@TypeSpec.JsonSchema.maxProperties(value: valueof int32)

Target

Record<unknown> | ModelProperty

Parameters

Name	Type	Description
value	`valueof int32`	The maximum number of properties this object can have.

`@minContains`

Specify that the array must contain at least some number of the types provided by the contains decorator.

@TypeSpec.JsonSchema.minContains(value: valueof int32)

Target

unknown[] | ModelProperty

Parameters

Name	Type	Description
value	`valueof int32`	The minimum number of instances the array must contain

`@minProperties`

Specify the minimum number of properties this object can have.

@TypeSpec.JsonSchema.minProperties(value: valueof int32)

Target

Record<unknown> | ModelProperty

Parameters

Name	Type	Description
value	`valueof int32`	The minimum number of properties this object can have.

`@multipleOf`

Specify that the numeric type must be a multiple of some numeric value.

@TypeSpec.JsonSchema.multipleOf(value: valueof numeric)

Target

numeric | ModelProperty

Parameters

Name	Type	Description
value	`valueof numeric`	The numeric type must be a multiple of this value.

`@oneOf`

Specify that oneOf should be used instead of anyOf for that union.

@TypeSpec.JsonSchema.oneOf

Target

Union | ModelProperty

Parameters

None

`@prefixItems`

Specify that the target array must begin with the provided types.

@TypeSpec.JsonSchema.prefixItems(value: unknown[])

Target

unknown[] | ModelProperty

Parameters

Name	Type	Description
value	`unknown[]`	a tuple containing the types that must be present at the start of the array

`@uniqueItems`

Specify that every item in the array must be unique.

@TypeSpec.JsonSchema.uniqueItems

Target

unknown[] | ModelProperty

Parameters

None