Possible to keep both local and type comments?

[xavdid]

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!

[xavdid]

Interestingly, wrapping my desired type in a single oneOf wrapper works perfectly:

{
  "title": "App",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "version": {
      "description": "A version string",
      "oneOf": [
        {
          "$ref": "#/definitions/VersionSchema"
        }
      ]
    },
    "platformVersion": {
      "description": "A version identifier for the Zapier execution environment.",
      "oneOf": [
        {
          "$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}$"
    }
  }
}

It's probably not feasible for our project (the actual schema is much bigger) but that's an interesting data point for a difference in how types are resolved!

[xavdid]

Actually, wrapping everything in oneOf is fixing a lot of other weird bugs I was hitting (like a bunch of duplicate comments instead of actual references), if that's helpful at all

[zomars]

Hey @xavdid, did you succeed in getting those Zapier definitions right? Would you mind sharing them or give a north on how did you achieve it?

[xavdid]

I didn't get it quite there, but mostly for reasons unrelated to this lib specifically. We can discuss further in https://github.com/zapier/zapier-platform/issues/8.