Add JSON schema struct generation

[SferaDev]

All structs matched well except for PrimaryKey which we mapped differently, I've refactored it to Pk as it doesn't seem to support different names for go and JSON

[andrew-farries]

Looks good 👍

• I think we should also add a Makefile with a rule to regenerate these types.
• The docs could be updated to include a reference to this JSON schema in the operations reference section

[SferaDev]

@andrew-farries Updated!

• Updated to latest JSON Schema draft
• When doing go get for the dependency, it updated other versions in the mod/sum files.
• Added a Makefile with a generate step
• Fixed the license check in the Makefile step
• Updated all objects to include descriptions

Proposed follow-ups:

• Add linter/formatter to the Makefile
• Add a github workflow to run make generate and check the generated file wasn't manually edited
• Update docs and use the JSON schema to generate API reference

[andrew-farries]

This looks good, just a few more suggestions.

[andrew-farries]

What's the purpose of allOf here? The same types are still generated successfully if I remove this line.

[SferaDev]

Some tooling fails to parse $ref in the top level. The allOf is a workaround that makes it work.

I think we could also move PgRollMigration definition top level instead of a $ref, not sure what you'd prefer. It's the only definition we actually don't really need in the types.go file.

[andrew-farries]

The PgRollMigration type actually duplicates a type we define here:

https://github.com/xataio/pgroll/blob/main/pkg/migrations/migrations.go#L46-L53

So it could probably be removed entirely.

[SferaDev]

I missed those. What about I create: Migration, Operation and Operations definitions and keep the allOf with $ref top level?

I kind of like having at least the Operation one as a definition as it will be the one we document outside the pgroll context.

I can get it done tomorrow so it's ready for a final review.

[SferaDev]

After checking today, it might not be possible to generate these and re-use them.

1. The Operation in pgroll it's not just an struct, it's an interface with methods.
2. The library hasn't added support for anyOf yet, they have a PR open but stale

I think it's fine as-is leaving the top level allOf: { $ref } to reference the definition of PgRollMigration that doesn't clash with the internal Migration one.

I've subscribed to that PR, once they merge support for anyOf maybe we can accomodate both and fully re-use Migration, Operations and Operation.

WDYT?

[andrew-farries]

Thats fine from my POV. The main benefit we get from this is being able to generate the types for the different operations.

Is this PR good to go from your side now?

[SferaDev]

Yes, can be merged when you're good with it

[andrew-farries]

Update docs and use the JSON schema to generate API reference

Do you have an idea in mind for how to generate documentation from the JSON schema?

[SferaDev]

Update docs and use the JSON schema to generate API reference

Do you have an idea in mind for how to generate documentation from the JSON schema?

There are different tools to read JSON schemas and generate docs. Cloudflare has doca although doesn't seem maintained, Adobe has a markdown generator and there might be a few more.

In any case, I was thinking of doing something a little bit more tailored for xata.io/docs. I think we will likely have 2 documentation sites: pgroll open source repo (and maybe even website in a future), and xata.io website for documenting the schema migrations in-product. It would be great if we make both share a single source of truth like the JSON Schema.