Better JSON macros
Nobody has claimed this yet.
- Dominant language
- C++
- Stars
- 876
- Forks
- 260
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 157
Description
There's a few issues with our current JSON macros:
- Forces conflation of serialisation and deserialisation. A field is either required (always present in serialisations, must be present to deserialise), or optional (may be omitted when serialising, allowed to be missing when deserialising). This misses the behaviour we'd actually like for most new fields added to existing types, which is that they are _always_ serialised to new JSON objects, but may be missing from old JSON objects. This in turn leads to the confusing interplay between `std::optional` wrappers and `OPTIONAL` macro declarations.
- Repetition of optionality. To add an optional field to a type which previously only had required fields, you must add a `DECLARE_JSON_OPTIONAL_FIELDS` line and _also_ change the original declaration from `DECLARE_JSON_TYPE` to `DECLARE_JSON_TYPE_WITH_OPTIONAL_FIELDS`. This is a complex, non-obvious change, and is a hard-to-debug runtime weirdness if you forget the latter.
- Compile-time complexity. The implementation of these macros combines overloaded ADL dispatched functions and some template specializations, producing a large amount of code for the compiler to churn through.
- Maintenance complexity. I barely understand it, and I wrote it. Adding new features is tricky, and likely to increase the matrix of initial declaration macros.
I think we can and should do better on all of these. These are primarily issues for framework developers rather than application developers, so not an immediate priority, but they are exposed for application developers to use so their API must be correctly exposed.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
The issue does not name any files, tests, or entry points. Start by locating the current JSON macro declarations and their serialization and deserialization implementations, then compare the optional-field behavior and compile-time complexity described here. Done would require an agreed redesign and corresponding implementation and tests, but the scope is not specified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- backend-api-design
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100