protobuf/docs/design/editions/edition-zero-json-handling.md

# Edition Zero: JSON Handling

**Author:** [@mkruskal-google](https://github.com/mkruskal-google)

**Approved:** 2023-05-10

## Background

Today, proto3 fully validates JSON mappings for uniqueness during parsing, while
proto2 takes a best-effort approach and allows cases that don't have a 1:1
mapping. This is laid out in more detail by *JSON Field Name Conflicts* (not
available externally). While we had hoped to unify these before
[Protobuf editions](what-are-protobuf-editions.md) launched, we ended up blocked
by some internal use-cases. This issue is now blocking the editions launch,
since we can't represent this behavior with the current set of
[Edition Zero features](edition-zero-features.md).

## Overview

Today, by default, we transform each field name to a CamelCase name that will
always be valid, but not necessarily unique in JSON. We also support a
`json_name` field option to override this for JSON parsing/serialization. This
allows conflicts to potentially arise where many proto fields map to the same
JSON field. Our JSON handling has the following behaviors:

*   All proto messages can be serialized to JSON
    *   Conflicting mappings will produce JSON with duplicate keys
*   All proto messages can be parsed from JSON
    *   Conflicting mappings lead to undefined behavior. While the behavior is
        deterministic in all of the cases we've encountered, it's inconsistent
        across runtimes and unexpected.
*   The Protobuf compiler will fail to parse any proto3 files if any JSON
    conflicts are detected by default
    *   Disabled by `deprecated_legacy_json_field_conflicts` option
*   Proto2 files will only fail to parse if both of the conflicts fields have
    `json_name` set
    *   We will still warn for default json mapping conflicts if
        `deprecated_legacy_json_field_conflicts` isn't set

The goal here is to unify these behaviors into a future-facing feature as part
of edition zero.

## Recommendation

We recommend adding a new `json_format` feature as part of
[Edition Zero features](edition-zero-features.md). The doc will be updated to
reflect the following details.

JSON format can have three possible states:

*   `ALLOW` - By default, fields will be fully validated during proto parsing.
    Any conflicting JSON mappings will trigger protoc errors, guaranteeing
    uniqueness. This will be consistent with the current proto3 behavior. No
    runtime changes are needed, since we allow JSON parsing/serialization.
*   `DISALLOW` - Alternatively, we will ban JSON encoding and disable all
    validation related to JSON mappings. All runtimes will fail to parse or
    serialize any messages to/from JSON when this feature is set on the
    top-level messages. This is a new mode which provides an alternative to
    `LEGACY_BEST_EFFORT` that doesn't involve any schema changes.
*   `LEGACY_BEST_EFFORT` - Fields will be validated for correctness, but not for
    uniqueness. Any conflicting JSON mappings will trigger protoc warnings, but
    no errors. This will be consistent with the current proto2 behavior, or
    proto3 where `deprecated_legacy_json_field_conflicts` is set. Since this is
    undefined behavior we want to get rid of, a parallel effort will attempt to
    remove this later. No runtime changes are needed, since we allow JSON
    parsing/serialization.

Long-term, we want JSON support to be specified at the proto level. For the
migration from proto2/proto3, we will just migrate everything to `ALLOW` and
`LEGACY_BEST_EFFORT` depending on the `syntax` and the value of
`deprecated_legacy_json_field_conflicts`.

We will additionally ban any `ALLOW` message from containing a `DISALLOW` type
anywhere in its tree (including extensions, which will fail to compile).
Attempting to add this will result in a compiler error. This has the following
benefits:

*   The implementation is a lot simpler, since most of the work is done in
    protoc and parsers only need to check the top level message
*   Runtime failures aren't dependent on the contents of the message being
    serialized/parsed
*   Avoids messy blurring of ownership. If a bug occurs because a `DISALLOW`
    field is sometimes set, is the owner of the child type required to change it
    to `ALLOW`? Or is the owner of the parent type responsible because they
    added the dependency?

    `LEGACY_BEST_EFFORT` will continue to allow serialization/parsing of types
    with `DISALLOW` set.

This feature will target messages and enums, but we will also provide it at the
file level for convenience.

Example use-cases for `DISALLOW`:

*   https://github.com/protocolbuffers/protobuf/issues/12525
*   Some projects generate proto descriptors at runtime and uses underscores to
    disambiguate field names. They never use JSON format with these protos, but
    currently have to work around our conflict checks

## Alternatives

### Dual State

Instead of a tri-state feature, we could have a simple allow/disallow feature
for JSON format.

#### Pros

*   Simpler conceptually

#### Cons

*   We would end up blocked by many of the protos that we were unable to migrate
    as part of *JSON Field Name Conflicts* (not available externally). While
    some of them could be migrated to `DISALLOW`, others are actually
    **depending** on our current behavior under JSON mapping conflicts (as a
    hack around some limitations in JSON customization).

### Default to DISALLOW

Instead of defaulting to `ALLOW`, we could default to `DISALLOW`.

#### Pros

The majority of internal Google protos are used for binary/text encoding and
don't care about JSON, so this would:

*   Be less noisy for teams who forget to explicitly set `DISALLOW` and may have
    fields with conflicting JSON mappings
*   Decrease our support surface

#### Cons

*   We would need to figure out where `DISALLOW` can be added

### Do Nothing

#### Pros

*   Short-term it saves some trouble and keeps edition zero simpler

#### Cons

*   We'll eventually hit the same issues we hit in *JSON Field Name Conflicts*
    (not available externally)
*   The current proto2/proto3 behaviors are mutually exclusive. There's nothing
    we can migrate to in today's edition zero that won't risk breaking one of
    them.