Should we translate `x-nullable` to `| null` for Azure services?

[MaryGao]

Background

This is a case during service linker migration. We migrate the x-nullable in swagger to | null in typespec. I'd like to clarify the interception on nullable in TypeSpec for Azure services.

• optional nullable property: https://github.com/Azure/azure-rest-api-specs/blob/main/specification/servicelinker/resource-manager/Microsoft.ServiceLinker/preview/2024-07-01-preview/servicelinker.json#L1489
• required nullble property: https://github.com/azure/azure-rest-api-specs/blob/main/specification/search/data-plane/Azure.Search/preview/2025-05-01-preview/searchservice.json#L11278-L11286

Optional vs nullable in Azure

At the REST/service API layer, nullable and optional are distinct and independent concepts. Optional indicates that the property (key/value pair) does not need to be included in the payload. Nullable means that the property’s value may explicitly be set to null.

But. Semantically, for Azure services treat a missing field and a field with a value of null as identical. Also offline confirmed with @johanste - autorest never distinguished between the two. Azure services almost universally (with the exception for json-merge-patch payloads which are sent from the client and never received by the client), are not allowed to have semantically meaningful null values. Which means that the inability to distinguish between null and no value ends up not being relevant.

Azure Guideline - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#json-null-resquest-values

DO NOT send JSON fields with a null value from the service to the client. Instead, the service should just not send this field at all (this reduces payload size). 

Semantically, Azure services treat a missing field and a field with a value of null as identical.

Open questions

I'd like to clarify followings:

• Should we tranlate x-nullable to | null in typespec? Do we distinguish optionality and nullable in typespec?
• We have no-nullable linter do we expect to translate x-nullable property to optional one in typespec to bypass this linter?

- ❌Do not use: prop: string | null;
- ✅ Do use: prop?: string;

[MaryGao]

I'd like to first collect the facts on how the languages respect x-nullable in autorest areas, @tadelesh @msyyc @weidongxu-microsoft @ArcturusZhang Could you help me understand if your languges respect this or not? Is it possible for customers to set null value on the wire?

[tadelesh]

Go does not honor x-nullable in swagger, so for TypeSpec, Go only use the inner type for nullable type.

[weidongxu-microsoft]

Java would ignore x-nullable or | null (it could make the property optional, though)

• for data-plane, json-merge-patch would automatically be treated as "all property is nullable" when used in the PATCH op, by emitter
• for mgmt-plane, service behavior is not well documented for resource PATCH (RPaaS vs non-RPaaS may handle the "merge" differently), there is a Java-specific option to mark that a property "can be serialized as null"

[msyyc]

Each property of Python SDK model could accept azure.core.serialization.NULL no matter typespec define | null or swagger define x-nullable or not.

[ArcturusZhang]

.Net behavior:

Public API

.Net has reference types and value types.
When a property has x-nullable: true and its type is a reference type, such as genrerated models, string, IPAddress, etc, the generated type would be the same as x-nullable: false.
When a property has x-nullable: true and its type is a value type, such as int, float, Guid, etc, the generated type of this property will be the corresponding nullable types, aka int?, float? or Guid?.

Serialization

In .Net, when a property is not assigned, its value will be its default value - for reference types, the default value is null, for value types, the default value is the zero-value of that type, for nullable value types, the default value is null.
When there is no x-nullable or x-nullable: false, we will ignore the null value during serialization.
When the property is specified as x-nullable: true, we will write null value into the payload if its value is null.

For instance, if we have:

model Foo {
i: int32 | null;
j: int32;
k?: int32;
}

and in .Net code we have this:

var foo = new Foo(null, default); // null is the value for `i`, `default` is the value for `j` because they are both required

in the payload we would see:

{
"i": null,
"j": 0
}

Deserialization

We will always honor the nullability of the property's type regardless if in the payload there is a null value.
We expect no exception should be thrown during the exception unless there is a scenario that we cannot handle.

[lmazuel]

If you come back to what x-nullable is about:
https://github.com/Azure/autorest/blob/main/docs/extensions/readme.md#x-nullable

Set "x-nullable": true on a schema to indicate that a null is a legal value.

Which is precisely what TypeSpec does with | null, it specificizes that null is a valid value.

The fact that Azure has guidelines around the usage of nullable shouldn't matter here. The TypeSpec describes what the RestAPI does, so if the RestAPI accepts null, then it's x-nullable and | null.

I believe we should convert x-nullable to | null, since it represents the same thing. Optionality is represented by required in Swagger, and ? in TypeSpec. Converting x-nullable to ? does not convert the Swagger apples to apples.

[markcowl]

Are there cases where a property is nullable outside of PATCH requests?

If this is regarding PATCH requests, I think we want to promote abiding by MergePatch guidelines, and not specifically calling out those properties that are nullable (in MergePatch, this is every property, and in the semantics of MergePatch where some properties are required, it is all optional properties).

Where possible, and certainly for REST APIs, we want to get out of the business of declaring certain properties as nullable under merge patch, and instead, having an agreed semantics over MergePatch for a resource type, and a mechanism for opting out for specific properties.

For cases outside of PATCH requests that require 'nullable', I agree that | null is the correct representation in TypeSpec.

[MaryGao]

Discussed in typespec meeting, we agreed with current translation from x-nullable to null and also we would put this as one refinement item in post-migration.

[lmazuel]

Closing, as I think we reached conclusion. Thanks!