diff --git a/FAQ.md b/FAQ.md index 34beed0138..c4634e91dc 100644 --- a/FAQ.md +++ b/FAQ.md @@ -82,7 +82,7 @@ Check out the "Language" and "Other" tabs in the options panel. What you're look Screenshot showing the options panel -If it isn't, then depending on your coding skills, you might be able to [customize the output](https://blog.quicktype.io/customizing-quicktype/). +If it isn't, then depending on your coding skills, you might be able to [customize the output](doc/CustomRenderer.md). ## Am I allowed to use the generated code in my software? @@ -108,7 +108,7 @@ The [JSON Schema homepage](http://json-schema.org) contains many links and resou ## I'd like to customize the output for my particular application. -We have [a blog post](https://blog.quicktype.io/customizing-quicktype/) on that very topic. +Check out our guide on [customizing output](doc/CustomRenderer.md). ## How can I control the property order in JSON Schema? diff --git a/README.md b/README.md index 7cb3513fce..a908e53f6d 100644 --- a/README.md +++ b/README.md @@ -187,7 +187,7 @@ async function main() { main(); ``` -The argument to `quicktype` is a complex object with many optional properties. [Explore its definition](https://github.com/quicktype/quicktype/blob/master/packages/quicktype-core/src/Run.ts#L637) to understand what options are allowed. +The argument to `quicktype` is a complex object with many optional properties. [Explore its definition](https://github.com/quicktype/quicktype/blob/master/packages/quicktype-core/src/Run.ts#L126) to understand what options are allowed. For a full mapping of CLI flags to JavaScript properties, please refer to our [Options Mapping Guide](docs/options-mapping.md). #### TypeScript: the `lang` option is a `LanguageName`, not a `string` diff --git a/doc/CustomRenderer.md b/doc/CustomRenderer.md index 42040e393d..52dfb627cb 100644 --- a/doc/CustomRenderer.md +++ b/doc/CustomRenderer.md @@ -30,7 +30,7 @@ export class MyCustomRenderer extends CSharpRenderer { } return undefined; } - // See: http://blog.quicktype.io/customizing-quicktype/ for more context + // See the documentation above for how to override renderer methods } ``` @@ -142,4 +142,4 @@ export class BrandNewRenderer extends ConvenienceRenderer { ## Links -Blog post with an older example: http://blog.quicktype.io/customizing-quicktype/ +*Note: The legacy blog post on customizing quicktype has been deprecated. Please refer to this document for renderer customization details.* diff --git a/docs/options-mapping.md b/docs/options-mapping.md new file mode 100644 index 0000000000..82e5918fb4 --- /dev/null +++ b/docs/options-mapping.md @@ -0,0 +1,77 @@ +# Quicktype Options Mapping Guide + +This document maps `quicktype` command-line interface (CLI) flags to their corresponding programmatic options in JavaScript and TypeScript. + +When using `quicktype` programmatically via the `quicktype()` or `quicktypeMultiFile()` functions in Node.js/TypeScript, options are supplied through the `Options` object (exported from `quicktype-core`). Target-language-specific CLI flags are passed inside the `rendererOptions` dictionary property. + +--- + +## Core & General Options + +| CLI Flag | JS/TS Property | Description | +| --- | --- | --- | +| `-o, --out ` | `outputFilename` | Name of the output file. Determines target language and top-level type name if not explicitly specified. | +| `-l, --lang ` | `lang` | The target programming language (e.g., `ts`, `csharp`, `go`, `swift`, `python`, `java`, `rust`, etc.). | +| `-t, --top-level ` | `topLevel` | Top-level type name generated for the root input object. | +| `-s, --src-lang ` | `srcLang` | Input source format (`json`, `schema`, `graphql`, `postman`, `typescript`). Defaults to `json`. | +| `--src ` | `inputData` | Input files, URLs, or directories containing sample JSON or schema definitions. | +| `--src-urls ` | `srcUrls` | Path to a Tracery grammar file describing URLs to crawl for data samples. | +| `--alphabetize-properties` | `alphabetizeProperties` | Put class and interface properties in alphabetical order instead of original JSON order. | +| `--all-properties-optional` | `allPropertiesOptional` | Make all properties in generated classes/interfaces optional (`undefined` / nullable). | +| `--no-render` | `noRender` | Do not render final code output. Useful for performance benchmarking or validation. | + +--- + +## Type Inference Flags + +`quicktype` performs smart type inference on JSON sample data by default. The CLI provides `--no-*` flags to disable specific inference behaviors. In the JS/TS API, these correspond to boolean properties that default to `true`. + +| CLI Flag | JS/TS Property | Description | +| --- | --- | --- | +| `--no-maps` | `inferMaps` (default: `true`) | Prevent inferring map/dictionary types from JSON objects; always generate explicit classes/structs. | +| `--no-enums` | `inferEnums` (default: `true`) | Prevent inferring enum types from repeated string field values; keep them as plain strings. | +| `--no-uuids` | `inferUuids` (default: `true`) | Prevent converting UUID-formatted strings to native UUID/GUID types. | +| `--no-date-times` | `inferDateTimes` (default: `true`) | Prevent inferring ISO date/time types from date-formatted string values. | +| `--no-integer-strings` | `inferIntegerStrings` (default: `true`) | Prevent automatically parsing numeric strings (e.g., `"123"`) as integer types. | +| `--no-boolean-strings` | `inferBooleanStrings` (default: `true`) | Prevent automatically parsing boolean strings (e.g., `"true"`, `"false"`) as boolean types. | +| `--no-combine-classes` | `combineClasses` (default: `true`) | Prevent combining structurally similar inferred classes into a shared class type. | +| `--no-ignore-json-refs` | `ignoreJsonRefs` (default: `true`) | Treat `$ref` properties as schema references inside JSON input files. | + +--- + +## Schema & GraphQL Options + +| CLI Flag | JS/TS Property | Description | +| --- | --- | --- | +| `-S, --additional-schema ` | `additionalSchema` | Register `$id` URIs of additional JSON Schema files for resolving cross-schema references. | +| `--graphql-schema ` | `graphqlSchema` | Path to a GraphQL schema file or saved GraphQL introspection result. | +| `--graphql-introspect ` | `graphqlIntrospect` | Server endpoint URL to run a GraphQL introspection query against. | +| `--http-method ` | `httpMethod` | HTTP method (e.g., `POST`, `GET`) to use for GraphQL introspection requests. | +| `--http-header
` | `httpHeader` | Custom HTTP headers (in `Header: Value` format) for remote HTTP/GraphQL requests. | + +--- + +## Target Language Renderer Options + +Target language-specific flags are passed in JS/TS using the `rendererOptions` key-value object inside the main `Options` payload. + +| CLI Flag | JS/TS Property | Description | +| --- | --- | --- | +| `--just-types` | `rendererOptions["just-types"]` | Generate plain type definitions/interfaces only, excluding serialization and deserialization helpers. | +| `--acronym-style