@typespec/json-schema 0.46.0-dev.10 → 0.46.0-dev.12

package/README.md

@@ -0,0 +1,87 @@
+# TypeSpec JSON Schema Emitter
+
+This package provides [TypeSpec](https://github.com/microsoft/TypeSpec) support for emitting JSON Schema version `2020-12` from TypeSpec definitions. It also provides [decorators for adding JSON Schema constraints](https://microsoft.github.io/typespec/standard-library/json-schema/reference/decorators). The emitter supports either YAML or JSON output and can be configured to emit one file per schema or bundle all schemas in to a single file.
+
+## Installation
+
+```bash
+npm install @typespec/json-schema
+```
+
+## Usage
+
+Add the `@jsonSchema` decorator to any types or namespaces you want to emit as JSON Schema.
+
+```TypeSpec
+import "@typespec/json-schema";
+
+using TypeSpec.JsonSchema;
+
+@jsonSchema
+namespace Example;
+
+model Car {
+  make: string;
+  model: string;
+}
+```
+
+To emit JSON Schema, use either of the following:
+
+1. Via the command line
+
+```bash
+tsp compile . --emit @typespec/json-schema
+```
+
+2. Via the config
+
+Add the following to the `tspconfig.yaml` file.
+
+```yaml
+emitters:
+  @typespec/json-schema: true
+```
+
+For more information, consult the [JSON Schema documentation](https://microsoft.github.io/typespec/standard-library/json-schema/reference).
+
+## 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.
+
+## See also
+
+- [Json Schema Emitter Documentation](https://microsoft.github.io/typespec/standard-library/json-schema/reference)
+- [TypeSpec Getting Started](https://github.com/microsoft/typespec#getting-started)
+- [TypeSpec Website](https://microsoft.github.io/typespec)

package/lib/main.tsp

@@ -96,7 +96,7 @@ extern dec prefixItems(target: unknown[] | Reflection.ModelProperty, value: unkn
 /**
  * Specify the content type of content stored in a string.
  *
- * @param the media type of the string contents
+ * @param value the media type of the string contents
  *
  */
 extern dec contentMediaType(target: string | Reflection.ModelProperty, value: valueof string);
@@ -117,10 +117,13 @@ extern dec contentSchema(target: string | Reflection.ModelProperty, value: unkno
  * emit the raw JSON code `{x: "value"}`.
  *
  * @param key the name of the keyword of vendor extension, e.g. `x-custom`.
- * @param value the value of the keyword. Will be converted to a schema unless wrapped in Json<T>.
+ * @param value the value of the keyword. Will be converted to a schema unless wrapped in `Json<T>`.
  */
 extern dec extension(target: unknown, key: valueof string, value: unknown);
 
+/**
+ * Well-known JSON Schema formats.
+ */
 enum Format {
   dateTime: "date-time",
   date: "date",
@@ -148,6 +151,8 @@ enum Format {
  * `@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"}`.
+ *
+ * @template T the type to convert to raw JSON
  */
 @Private.validatesRawJson(T)
 model Json<T> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typespec/json-schema",
-  "version": "0.46.0-dev.10",
+  "version": "0.46.0-dev.12",
   "author": "Microsoft Corporation",
   "description": "TypeSpec library for emitting TypeSpec to JSON Schema and converting JSON Schema to TypeSpec",
   "homepage": "https://github.com/microsoft/typespec",