Add `codegen` Support to Studio

[RitoG09]

Generating TypeScript types directly from JSON Schema improves developer experience, supporting codegen would provide a natural extension of existing features.

[jviotti]

Maybe, though would it be supporting the right flow? If you would do it with the VS Code extension, you would be essentially promoting users to copy paste the TypeScript code from there? Which you probably shouldn't. If any, they should integrate into some sort of build configuration, potentially powered by jsonschema codegen directly.

[RitoG09]

Thanks for the clarification. I spent some time looking at how other tools like Prisma handle this ->

e.g., Prisma doesn’t rely on an editor driven flow for code generation. The schema.prisma is the main file and users run prisma generate via cli. That command is typically integrated into package.json scripts (e.g., postinstall, prebuild, etc.) making the process reproducible and CI friendly.

Following the same philosophy, instead of Studio directly generating TypeScript types for manual use, what we can do ->

• Detect the schema file
• Ask for output path and optional type prefix
• Add a jsonschema codegen script to package.json, e.g.

{
  "scripts": {
    "generate:types": "jsonschema codegen schema.json --target typescript --name Person > src/generated/types.ts"
  }
}

• Create the output directory and ensure the generated file is clearly marked as auto-generated.

Now one more thing is, do we really need Studio to implement this, or should this remain purely a CLI-level concern?
Eager to know your thoughts on this @jviotti

[jviotti]

I think it should be purely on the CLI. I don't think there is value in the extension integrating with this in any way without encouraging bad practices

[RitoG09]

Are there areas around the codegen functionality in the CLI where contributions would be particularly valuable? I’d be happy to explore improvements there instead.

[jviotti]

@RitoG09 As per https://github.com/sourcemeta/jsonschema/blob/main/docs/codegen.markdown, we consider the codegen experimental. I think a huge area of help would be filling issues for minimal reproducible examples of valid schemas that codegen fails with, or that it generates suboptimal types. Testing is probably 95% of it at this point. Once we surface the key patterns that fail, we can prioritise and fix them.

For example, you might find that 50 schemas fail, but they all come back to some specific common scenario i.e. with allOf. Finding those minimal cases is most of the battle!

As a hint, try to use AI for this. It can be very good at fuzzing the tool, collecting examples, finding the shared common problems, etc.

[RitoG09]

I’ve been systematically testing allOf with various constraints to identify minimal reproducible failures. Here is the summary->
After testing required properties additionalProperties minProperties and maxProperties the behavior appears consistent:

• allOf between two "type": "object" schemas:

  1. If object constraints are structurally identical -> succeeds
  2. If object constraints differ -> fails with unnecessary_allof_wrapper

• Examples that fail:

  1. required ∧ required (different required sets)
  2. minProperties ∧ minProperties (different values)
  3. maxProperties ∧ maxProperties (different values)
  4. required ∧ object
  5. required ∧ additionalProperties

• Examples that succeed:

  1. object ∧ object (no constraints)
  2. Identical constraints on both sides
  3. Primitive intersections (e.g., string ∧ string)

• Minimal reproducible example:

{
  "allOf": [
    { "type": "object", <constraint A> },
    { "type": "object", <constraint B> }
  ]
}

I think as per sourcemeta/jsonschema#619 the main logic of these cases lies under the canonicaliser.
@jviotti is this analyze ok? if it aligns then i can further move with other keywords.

[jviotti]

Yes! allOf is a known one, which is great to compile more examples for. If you find others for other keywords, awesome too. Also try across dialects of JSON Schema. And finally, for any you find, please report them in https://github.com/sourcemeta/core, as that's where the canonicaliser lives!