> For the complete documentation index, see [llms.txt](https://framework.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://framework.aic.io/technical-guidelines-code-standards-and-tech-stack/c-code-standards/nullable-reference-types.md).

# Nullable Reference Types

## Purpose

Null-related defects are common and avoidable. AIC uses nullable reference types to make null handling explicit.

## Mandatory Rules

* Production projects MUST enable nullable reference types.
* Do not suppress nullable warnings without a clear reason.
* Do not use `!` to silence warnings unless the invariant is proven and documented.
* Public APIs must express nullable behaviour accurately.
* Database nullability, DTO nullability and validation rules must align.

## Project Setting

```xml
<Nullable>enable</Nullable>
```

## Good Example

```csharp
public sealed class UserProfile
{
    public required string DisplayName { get; init; }
    public string? MobileNumber { get; init; }
}
```

## Bad Example

```csharp
public string Name { get; set; } = null!;
```

This is acceptable only when required by a serializer or framework and should be isolated.

## API Contract Example

```csharp
public sealed record UpdateUserRequest(
    string DisplayName,
    string? MobileNumber);
```

The nullable annotation tells clients and validators that `MobileNumber` is optional but `DisplayName` is required.

## EF Core Considerations

Ensure C# nullability aligns with database schema:

```csharp
builder.Property(x => x.DisplayName)
    .IsRequired()
    .HasMaxLength(200);
```

## Review Checklist

* Are nullable warnings resolved?
* Are `?` annotations accurate?
* Are required properties validated?
* Are null object states impossible or handled?
* Are DTOs aligned with API documentation?
* Are EF Core required/optional mappings consistent?