> Markdown version of [Type Nullability](https://vaadin.com/docs/next/flow/react-views/browser-callable-services/type-nullability). Section index: [llms.txt](https://vaadin.com/docs/next/flow/llms.txt)

# Type Nullability

In the generated TypeScript code, a type either allows `undefined` or it doesn’t. Vaadin decides this for each type from the Java type and its nullability annotations. A nullable parameter or return value has a type such as `string | undefined`. A nullable property is optional in its interface, such as `name?: string`.

## <a id="defaults"></a>Defaults

Without nullability annotations, the types are as follows:

- Primitive types, such as `int` and `boolean`, are non-nullable.

- All other types are nullable. This includes the items of collections and the values of maps.

- `Optional<T>` is always nullable, whatever its annotations.

For example:

```java
public class Person {
    public long id;
    public String name;
    public List<String> tags;
    public int[] scores;
}
```

```typescript
interface Person {
  id: number;
  name?: string;
  tags?: Array<string | undefined>;
  scores?: Array<number>;
}
```

## <a id="null-marked"></a>Non-Nullable Packages

To make the types non-nullable by default, annotate the packages of your services and data classes with the [JSpecify](https://jspecify.dev/) `@NullMarked` annotation, in `package-info.java`:

`package-info.java`

```java
@NullMarked
package com.example.application;

import org.jspecify.annotations.NullMarked;
```

The types in the package are then non-nullable, including the items of collections and the values of maps. Mark the exceptions with `@Nullable`:

```java
public record Person(String name, @Nullable String nickname, List<String> tags,
        List<@Nullable String> notes) {
}
```

```typescript
interface Person {
  name: string;
  nickname?: string;
  tags: Array<string>;
  notes: Array<string | undefined>;
}
```

The annotation of the package that contains a service applies to the methods of the service. The annotation of the package that contains a bean or a record applies to its properties.

Vaadin reads `@NullMarked` only on packages. It ignores the annotation on classes and modules. The annotation of a package doesn’t apply to its sub-packages, so each package needs a `package-info.java` of its own.

The fields of JPA entities that are annotated with `@Id` or `@Version` stay nullable, because a new entity doesn’t have them yet.

## <a id="annotations"></a>Annotations

To change the nullability of a single type, annotate the parameter, the method, the field, or the type argument with `@NonNull` or `@Nullable`. An annotation on the type overrides the default of the package. For example, in a package without `@NullMarked`:

```java
public @NonNull List<@NonNull String> findTags(@NonNull String category) {
    // ...
}
```

The generated function takes a `category` of the type `string`, and returns a `Promise<Array<string>>`.

Vaadin recognizes these annotations:

| Effect               | Annotations                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Non-nullable         | `org.jspecify.annotations.NonNull`, `jakarta.annotation.Nonnull`, `javax.annotation.Nonnull`, `org.springframework.lang.NonNull` |
| Nullable             | `org.jspecify.annotations.Nullable`, `jakarta.annotation.Nullable`, `org.springframework.lang.Nullable`                          |
| Non-nullable package | `org.jspecify.annotations.NullMarked`, `org.springframework.lang.NonNullApi`                                                     |

Use the JSpecify annotations. Spring has deprecated its own nullability annotations in favor of them.

In Kotlin, Vaadin uses the nullable types of Kotlin, when `kotlin-reflect` is on the class path.

## <a id="runtime"></a>Null Values at Runtime

The types only describe the values. When a value doesn’t match its type, the following happens:

- Arguments

  A view must pass every argument, also for a nullable parameter. To pass `null`, pass `undefined`. The server doesn’t check the arguments against their nullability. A method can get `null` for a non-nullable parameter, for example from a call that doesn’t use the generated function. To reject such calls, add a `@NotNull` constraint, as described in [Parameter Validation](https://vaadin.com/docs/next/flow/react-views/browser-callable-services.md#validation).

- Return values

  When the return type of a method is non-nullable, the server checks the return value. When the value is `null`, the call fails with an `EndpointResponseError` with the status 500. The server also checks the items of collections and arrays, the values of maps, and the properties of beans that have getters. It doesn’t check the components of records. The check of the items ignores annotations on type arguments, so a `null` item fails the call, even when the item type is `@Nullable`.
