microsoft / microsoft/CCF

Better JSON macros

Open
#4,091 4 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.