Add a @Required annotation for fields

[grishka]

This is a long-requested feature (#61).

I'm not sure if this is the best way to do this, especially the Set<String> part to keep track of required fields that were found in the input, but I haven't come up with anything better. I'm also not sure if this annotation should affect serialization — maybe it should also throw an exception when attempting to serialize a required field that is null?

[google-cla]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[grishka]

@googlebot I signed it!

[Marcono1234]

Looks reasonable, but maybe two things which have to be considered:

1. In some use cases an explicit JSON null is considered a value, so maybe the annotation should have an allowNull (or similar) annotation element with default value false to support that use case.
2. Instead of tracking which field names have been deserialized you should probably track the Field (needs some refactoring). Otherwise this won't work for @SerializedName with alternate, e.g.:

   class Test {
       @SerializedName(value = "a", alternate = "b")
       String s;
   }

   For the exception listing missing required fields it might be reasonable to report the 'main' name, i.e. either the field name or @SerializedName#value, otherwise the exception message might be confusing.

Note that I am not a member of this project, so these are only suggestions.

[Marcono1234]

or is not of a type assignable to this field.

That is the default behavior for fields anyways, isn't it? I don't think this is worth mentioning here then, otherwise it might cause confusion whether this does / does not apply to optional fields.

[grishka]

Well, if you try to parse something that has an object where you expect a string, the string will be null. The idea behind this annotation is to guarantee that a required field will never, under any circumstances, be null.

[Marcono1234]

Well, if you try to parse something that has an object where you expect a string, the string will be null.

Are you sure? The following throws an exception:

public class GsonParsingTest {
    static class Test {
        String s;
    }
    
    public static void main(String[] args) {
        new Gson().fromJson("{\"s\":{}}", Test.class);
    }
}

Maybe there are custom type adapters which return null for non-null JSON in case of type mismatch, but we cannot generally assume that. Not every type adapter which returns null must have encountered wrong JSON data.

[lyubomyr-shaydariv]

@Required sounds like a twin of JSR-303 @NotNull and does not seem to make it extensible. I would not create a doubling annotation, but rather would think of implementing a generic method to apply any kind of post-processing at least at DTO class level (probably by extending ReflectiveTypeAdapterFactory that makes a lot of things hard to accompilsh being not extensible). Validation is only a particular case of such a generic thing. This all seems to be pretty achievable using post-processing mechanisms like RuntimeTypeAdapterFactory from the Gson Extras demo:

• it's possible to do anything with a deserialized object, including validation (entire JSON document must be consumed though);
• it's possible to incorporate any strategy (including JSR-303 validation as a Jackson-like module that can be built on top of type adapter factories) right into type adapter factories, so that any ReflectiveTypeAdapterFactory.Adapter-derived type adapter could invoke the strategy and quick-validate the just-deserialized object (subobjects revalidated every time a super object is completed to be serialized, so it may be time expensive -- but it sounds like it can be optimized greatly).

Any other thoughts on making Gson deserialization-only, but extensible on user demand only, tool?

---

UPD1 (just not to spawn another comment): JSR-303 annotations are runtime-visible and have nothing to do to static code analysis and Android/JetBrains at all.

[grishka]

but rather would think of implementing a generic method to apply any kind of post-processing

The problem with the post-processing approach is that it, in case of a field of a primitive type, it won't let you tell the difference between the lack of that field in the json and its presence with its default value (0/false). Yes, boxed types can kinda awkwardly solve this by allowing those fields to be null. But you won't want to use boxed types in all your objects just so you could validate them in a post-processing step. You really want to do this in a place where you have access to the JSON.

JSR-303 @NotNull

This is the first time I've seen this after more than 10 years writing Java. I do know about @NotNull/@Nullable commonly used in many places these days, but these usually either come from a JetBrains library for Java SE or an AndroidX library for Android. And — I just looked — their retention is "class", so not visible at runtime.