Suggestion
This is a high level idea that I didn't want to get lost in the aether.
We currently have a couple of instances of TypeScript type + JSONSchema, where the two are supposed to match up, but there's no particular validation that that is the case. This comes around from the need for validation at compile time, along with a portable runtime schema. We do use zod in a couple of places where we need validation at both runtime and compile time, but the difference there is that those usages do not require the schema to be portable.
The most notable example of portable runtime schema is Scaffolder actions, where there is a TypeScript type and JSON schema for each action. There may also be other places where we have a need for this portable schema + TypeScript definitions though, for example the permission system could likely benefit from that too in the shared rules declarations.
The overarching idea is to switch out the type + schema definition for a ts-schema + JSON schema transform. A concrete example of this would be to use zod to declare the TypeScript type, and then convert it to a portable schema using something like zod-to-json-schema. It doesn't have to be exactly this combination of libraries, but importantly my feeling is that doing the transform in this direction is a lot simpler than trying to convert JSON Schema to TypeScript, or to generate JSON Schema from TypeScript definitions.
A possible alternative could be to go down the route of TypeScript -> JSON Schema generation, but that is likely to require build tooling support to not have a big impact on DX, which then instead adds complexity.
As far as I can tell a big gap in the proposed solution is the omission of descriptions. We'd really want to find a way to still be able to define and include descriptions for the fields in the JSON Schema, as they tend to be very important for the end user experience.
Suggestion
This is a high level idea that I didn't want to get lost in the aether.
We currently have a couple of instances of TypeScript type + JSONSchema, where the two are supposed to match up, but there's no particular validation that that is the case. This comes around from the need for validation at compile time, along with a portable runtime schema. We do use zod in a couple of places where we need validation at both runtime and compile time, but the difference there is that those usages do not require the schema to be portable.
The most notable example of portable runtime schema is Scaffolder actions, where there is a TypeScript type and JSON schema for each action. There may also be other places where we have a need for this portable schema + TypeScript definitions though, for example the permission system could likely benefit from that too in the shared rules declarations.
The overarching idea is to switch out the type + schema definition for a ts-schema + JSON schema transform. A concrete example of this would be to use zod to declare the TypeScript type, and then convert it to a portable schema using something like zod-to-json-schema. It doesn't have to be exactly this combination of libraries, but importantly my feeling is that doing the transform in this direction is a lot simpler than trying to convert JSON Schema to TypeScript, or to generate JSON Schema from TypeScript definitions.
A possible alternative could be to go down the route of TypeScript -> JSON Schema generation, but that is likely to require build tooling support to not have a big impact on DX, which then instead adds complexity.
As far as I can tell a big gap in the proposed solution is the omission of descriptions. We'd really want to find a way to still be able to define and include descriptions for the fields in the JSON Schema, as they tend to be very important for the end user experience.