bcherny/json-schema-to-typescript

Possible to keep both local and type comments?

Open

#334 opened on Aug 18, 2020

View on GitHub
 (4 comments) (2 reactions) (0 assignees)TypeScript (449 forks)github user discovery
buggood first issuehelp wanted

Repository metrics

Stars
 (3,302 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

Forgive me if this is a duplicate of https://github.com/bcherny/json-schema-to-typescript/issues/132 or another issue; I searched by didn't find anything.

I was hoping to be able to have both a comment about a property and

Input

{
  "title": "App",
  "type": "object",
  "properties": {
    "version": {
      "description": "A version identifier for your code.",
      "$ref": "#/definitions/VersionSchema"
    },
    "platformVersion": {
      "description": "A version identifier for the Zapier execution environment.",
      "$ref": "#/definitions/VersionSchema"
    }
  },
  "definitions": {
    "VersionSchema": {
      "$id": "#VersionSchema",
      "description": "Represents a simplified semver string, from `0.0.0` to `999.999.999`.",
      "type": "string",
      "pattern": "^[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}$"
    }
  }
}

Desired Output

/**
 * Represents a simplified semver string, from `0.0.0` to `999.999.999`.
 *
 * This interface was referenced by `App`'s JSON-Schema
 * via the `definition` "VersionSchema".
 */
export type VersionSchema = string;

export interface App {
  /**
   * A version identifier for your code.
   */
  version?: VersionSchema;
  /**
   * A version identifier for the Zapier execution environment.
   */
  platformVersion?: VersionSchema;
}

Actual Output

export interface App {
  /**
   * A version identifier for your code.
   */
  version?: string;
  /**
   * A version identifier for the Zapier execution environment.
   */
  platformVersion?: string;
}

While this is technically correct, it's a bummer to lose the helpful info that each property should be a simple semver string. But, it's also nice to be able to describe version and platformVersion inline.

I noticed that small tweaks to the input changed output in interesting ways. I've tried changing $id to id, which yields:

/**
 * A version identifier for your code.
 */
export type VersionSchema = string;
/**
 * A version identifier for the Zapier execution environment.
 */
export type VersionSchema1 = string;

export interface App {
  version?: VersionSchema;
  platformVersion?: VersionSchema1;
}

(which already has an open issue)

where the doc about 0.0.0 is removed and the inline comments are moved to the created types instead. Same result if I give VersionSchema a title.

Interestingly, there seems to be a difference between {"$ref": "something"} and {"$ref": "something", "description": "Very cool"}.

Given that there's a lot of levers to pull, it's very possible I'm missing something obvious.

Thanks a bunch for this awesome tool!

Contributor guide