null Is Valid JSON, undefined Is Not — And the Difference Matters

RFC 8259, the specification that defines JSON, enumerates exactly six types of values: strings, numbers, the boolean literals true and false, arrays, objects, and the literal null. The word undefined appears nowhere in the RFC because undefined is a JavaScript language concept, not a data interchange concept. When the JSON specification was designed, it drew inspiration from JavaScript's object literal syntax but intentionally excluded language-specific runtime values that have no portable representation.

Null in JSON is a first-class value written as the four-character literal null without any quotes. It means precisely what the specification says: a JSON value that intentionally represents the absence or emptiness of a meaningful value. A field set to null signals to the consumer that the field exists as a concept in the data model but currently has no value. This is semantically different from a field that is not present at all, though both are valid JSON and parsers accept both.

Undefined, by contrast, is a JavaScript runtime value that has no equivalent representation in any other language or data format. It exists in JavaScript to represent the state of a variable that has been declared but not assigned, a function parameter that was not passed, or a property accessed on an object that does not have that property. Because undefined carries meaning only within a JavaScript runtime context, it cannot be meaningfully transmitted to another system, which is why the JSON specification excludes it.

The JSON.stringify function enforces this boundary by applying different rules depending on where an undefined value appears. When undefined appears as the value of an object property, JSON.stringify removes the entire key-value pair from the output without warning. When undefined appears as an element in an array, JSON.stringify converts it to null, preserving the array's length and the positional meaning of remaining elements. When JSON.stringify is called with undefined as the top-level value, it returns the JavaScript value undefined rather than a string, which is a subtle signal that the result should not be used as a JSON string.

Understanding these rules is essential for building reliable APIs. A backend that sets fields to undefined rather than null before serializing will produce JSON that omits those fields entirely, which clients will interpret as the field not being part of the data model at all. If the client then makes a decision based on whether the field is present, it will behave differently than if the field had been explicitly set to null, even though the developer's intent was the same in both cases.

The most direct way to discover undefined-related data loss is to compare the original JavaScript object with the JSON.stringify output. If the counts of keys differ between the original object and the parsed result of stringifying and reparsing it, some keys were dropped. A simple diagnostic function can traverse the object and collect all paths where the value is undefined, giving a clear list of which fields will be lost.

Another useful diagnostic is to call JSON.stringify with a replacer function that logs every key-value pair it processes. The replacer receives each key and value before the value is serialized. If you log every call where the value is undefined, you will see exactly which fields are being silently dropped. This approach works well during debugging sessions but should be removed in production code for performance reasons.

TypeScript can help catch undefined-related serialization issues at compile time if types are defined carefully. Declaring a field as string | null tells TypeScript that null is a valid value for that field and will appear in the JSON output. Declaring it as string | undefined tells TypeScript that the field may be absent, which is correct from a JavaScript perspective but misleading for JSON serialization because it implies the field will be omitted from the output rather than set to null. Adding a custom ESLint rule or a type-level transform that maps TypeScript's optional properties to null before serialization can prevent these issues from reaching production.

For debugging API responses, comparing the request payload that your code generates against what the server actually receives is often the most efficient approach. Many HTTP debugging tools like curl with verbose output, the Network tab in browser DevTools, or a local HTTP proxy like mitmproxy will show the raw JSON string that was sent. If you see fewer fields in the wire format than you expected to send, undefined-dropping is a likely cause. Checking the size of the JSON string against an estimate based on the number of fields is another quick heuristic: if the string is significantly shorter than expected, fields are missing.

The most controlled fix is to normalize the object before calling JSON.stringify, converting every undefined value to null. This makes the intent explicit: fields that have no value will appear in the JSON output as null rather than disappearing. The transformation can be applied with a recursive function that walks the object tree, or more concisely using JSON.stringify's replacer function parameter.

Using the replacer function approach, you pass a function as the second argument to JSON.stringify. The replacer receives the key and value for every entry it visits, including nested objects. If the value is undefined, return null instead. For all other values, return the value unchanged. This approach handles arbitrary nesting without requiring a separate recursive traversal function.

If you want to omit fields entirely rather than include them as null, the replacer can return undefined explicitly for those fields, which signals to JSON.stringify to skip them. This is the default behavior for undefined values, but making it explicit in a replacer function at least documents the intent rather than relying on implicit behavior. The distinction matters for API design: omitting a field entirely versus setting it to null communicates different semantics to the consumer.

For TypeScript projects, a common pattern is to define two separate types: a domain type that uses undefined for optional fields because that matches JavaScript's native representation of optional object properties, and a serialization type that uses null instead of undefined and omits certain internal fields. A transformation function converts from the domain type to the serialization type before calling JSON.stringify. This approach keeps the JavaScript code idiomatic while ensuring the JSON output is consistent and explicit.

In frameworks that use class-based serialization, such as NestJS with class-transformer, you can use the Transform decorator to convert undefined values to null at the class property level. The serialization library handles the conversion automatically when transforming class instances to plain objects before JSON serialization. This approach centralizes the undefined-to-null conversion in the data model definition rather than scattering it throughout the codebase.

TypeScript treats null and undefined as distinct types, and the distinction affects how optional properties and nullable properties are modeled in type definitions. When strict null checks are enabled in tsconfig.json, which is the default in modern TypeScript projects, null and undefined are separate types that must be explicitly included in a union if they are allowed as values for a property.

A property typed as name: string | null expresses that name will always be present in the object but may be null. This maps cleanly to JSON because null is a valid JSON value. When serialized, the field will appear in the JSON output either as a JSON string or as the literal null. Consumers of the JSON can rely on the field always being present and always being either a string or null.

A property typed as name?: string, which is shorthand for name: string | undefined, expresses that the property may not exist on the object at all. In JavaScript this is useful, but in JSON serialization it creates ambiguity: will the JSON output contain the field set to null, will it omit the field entirely, or will the serialization behavior depend on whether the JavaScript object had the property at all? The answer depends on how the object was created and whether any normalization step converted undefined to null before serialization.

A property typed as name?: string | null combines both optional (may not exist) and nullable (may be null if it exists). This is the most permissive type and the most ambiguous for serialization, because it allows three distinct states: the property is absent, the property exists and is null, or the property exists and has a string value. JSON serialization must decide which of these three states to represent as which JSON output, and without explicit normalization the implicit JSON.stringify behavior may not match the developer's intent.

When designing TypeScript types for JSON API contracts, prefer string | null over string | undefined for fields that should always appear in the serialized output. Reserve undefined for fields that should be omitted from the JSON entirely, and handle that omission explicitly in a serialization layer rather than relying on JSON.stringify's implicit dropping behavior.

API design conventions around null versus field omission are not universally agreed upon, but there are two coherent schools of thought that both work well when applied consistently. The first convention is to always include every documented field in the response, setting it to null when the field has no value. This makes the API schema stable and predictable: consumers always receive the same set of keys in every response and can validate the response structure without accounting for optional fields that may or may not appear. GraphQL APIs generally follow this convention.

The second convention is to omit fields when they have no value, treating a missing field and null as equivalent signals for absence. This produces smaller JSON responses because empty fields consume no space, and it avoids the philosophical question of whether null and missing-field mean the same thing. REST APIs using this convention often document that absent fields should be treated as null by consumers. The risk is that consumers cannot distinguish between an intentionally null field and a field that does not exist in the current API version.

The most problematic API design is inconsistency: sometimes returning null for absent fields and sometimes omitting them, with no documented rule for which behavior applies where. Consumers must then write defensive code that checks both for null and for property absence on every optional field, doubling the conditional logic for handling nullable data. Code that was written to handle one convention will produce subtle bugs when encountering responses that follow the other convention.

For frontend code consuming an API, using optional chaining with a null coalescing fallback handles both conventions gracefully: apiResponse.user?.deletedAt ?? null will return null whether deletedAt was explicitly null or was absent from the response object. This defensive coding style lets the frontend tolerate both JSON conventions without requiring the API design to be perfectly consistent, which is practical for real-world projects where APIs evolve over time and consistency is not always maintained.

JSON Schema provides a formal way to document whether a field can be null and whether a field is required to be present in a JSON document. These two concerns are separate in JSON Schema, and confusing them leads to schemas that allow invalid data or reject valid data. Defining them explicitly prevents the null-versus-undefined confusion from spreading from JavaScript code into the API contract.

In JSON Schema draft-07, a field that can be either a string or null is typed as { "type": ["string", "null"] }. An alternative notation using oneOf with one branch being { "type": "null" } achieves the same validation but is more verbose. The required array on an object schema determines which fields must be present. A field can be required and nullable, meaning it must appear in the JSON but its value can be null. A field can be optional and nullable, meaning it may be absent or present as null. A field can be required and non-nullable, meaning it must appear and must be a non-null string.

Draft 2019-09 and 2020-12 introduced the explicit nullable approach of using a oneOf with null, which is more expressive and aligns better with how validators process schemas. OpenAPI 3.0 uses a separate nullable: true attribute alongside the type definition, which is specific to OpenAPI's subset of JSON Schema. OpenAPI 3.1 adopts the full JSON Schema 2020-12 approach, using type arrays to express nullability, making the schemas more standard and interoperable.

When documenting an API, making the null-versus-omission convention explicit in the schema prevents consumer confusion. If a field will always appear in the response but may be null, mark it as required in the JSON Schema with a nullable type. If a field may be absent entirely, mark it as not required and document whether absence is equivalent to null or has distinct semantics. If the API follows the omit-when-null convention, document this as a global convention so consumers do not need to check each field's individual documentation.

Code generation tools like openapi-generator and quicktype read JSON Schema and generate TypeScript types from it. If the schema uses nullable types correctly, the generated types will use string | null rather than string | undefined for nullable fields, which propagates the correct serialization behavior throughout the frontend codebase automatically without requiring manual type annotations.