Request for Comments: Add new package "pandoc-codecs"

[tarleb]

This is exploratory work, aimed at improving the situation around JSON schemas (#9384) and command line options (#10163). It would include a good bit of busywork, so my intention is to gathering feedback with this PR before doing any of that.

The idea is to use autodocodec to define schemas for pandoc data types. These could then be reused in various places, e.g., to define a JSON schema, thus allowing us to keep all important definitions in one place. Or at least in fewer places, because we'd still be duplicating part of the ToJSON/FromJSON instances from Text.Pandoc.Definition, unless we decide to go all-in on autodocodec.

I've put the code in a new package as to avoid an additional dependency in pandoc. Consistency checks for JSON encodings could happen via QuickCheck.

If this whole plan gets a tentative thumbs up, then my next step would be to write a autodocodec-hslua package that can use Codec definitions to do Lua marshaling.

[tarleb]

The documentation for autodocodec is a bit sparse, but @sshine wrote a nice post that explains it a bit better: https://dev.to/sshine/json-schema-in-haskell-using-autodocodec-35cg

[jgm]

Possibly related: #10914 (comment)
though I don't think autodocodecs covers XML schemas!

I'm not sure what I think about this. Duplicating pandoc-types stuff in a separate package seems a bad idea. If autodocodecs can simultaneously generate the To/FromJSON instances and the schemas and docs, then maybe it could be integrated in pandoc-types. (But, one worries about the dependency tree and stability.)

[jgm]

I see, looking now at the changes, that this is not (yet anyway) about the Pandoc type, but about the types used for Options etc.

Can you say more about what this gets us? How would it simplify our lives?

It doesn't look like the dependency footprint is too bad. If there is utility in this, maybe it would be better the schema documentation in the same modules as the types themselves, rather than in a separate package -- which you'd have to remember to update independently on any changes to the types