Omittable
1.0.0indexedTiny library introducing an Omittable type for distinguishing between absent and null values, enhancing API efficiency and semantic clarity in data transfer objects.
20
Stars
—
Used by
dependents
—
Health
/ 100
Omittable
A tiny Kotlin Multiplatform library that provides an Omittable type to be used in cases where the absence of a value is semantically different from a null value.
Why?
When developing RESTful APIs, it is often necessary to distinguish between the absence of a value and a null value to support partial updates properly.
Consider a user profile with an integer ID, a name, and a birthday. Imagine a user wants to update their name, but not their birthday. This could be implemented by updating the entire profile:
curl -X PUT https://api.example.com/users/123 \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe",
"birthday": "2005-07-11T10:34:47+00:00"
}'
In this case, the birthday is sent as well, even though it should not be changed. Not only this is inefficient, but it also obscures the intent of the user which makes it harder for the server to authorize the request.
A more practical and scalable approach is to use partial updates:
curl -X PATCH https://api.example.com/users/123 \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe"
}'
Here, the birthday field is omitted to indicate that the server should not
change the birthday. Similarly, if the user wants to remove their birthday from
their profile, they could explicitly set it to null:
curl -X PATCH https://api.example.com/users/123 \
-H "Content-Type: application/json" \
-d '{
"birthday": null
}'
While this is a common pattern that makes for a clean API, it is tricky to
translate this into DTOs in most languages since there is typically no
difference between null and the absence of a value. The Omittable type
solves this by (re-)introducing a semantic distinction between the two.
Omittable vs. Optional
Omittable is similar to Java's Optional in that is a container type for
value. Like Optional, an should never be set to . However,
while is primarily useful as a replacement for that enabled
operator chaining without language modifications, can be used to
wrap values (including s) to create a semantic distinction between absence
of a value and a value that is explicitly set to .
Usage with Kotlin
A typical DTO written in Kotlin could look like this:
@Serializable
data class UserDto(
val name: Omittable<String> = Omittable.absent(),
val birthday: Omittable<Instant> = Omittable.absent()
)
Such a DTO can be used with kotlinx.serialization:
val dto = TestDto(name = Omittable.of("John Doe"))
val result = json.encodeToString(TestDto.serializer(), dto)
assertEquals(
"""
{
"name": "John Doe"
}
""".trimIndent(),
result
)
assertEquals(dto, json.decodeFromString<TestDto>(result))
Usage with Java
While Omittable is written in Kotlin, it does not require Kotlin and is designed to work smoothly with Java as well.
A typical DTO written in Java could look like this:
public record UserDto(
Omittable<String> name,
Omittable<Instant> birthday
) {}
Omittable supports Java's pattern matching:
public void process(UserDto user) {
// Omittable is designed to work seamlessly with Java's pattern matching and
// can be used with type patterns in instanceof...
if (user.name() instanceof Omittable.Present(String name)) {
System.out.println( + name);
} {
System.out.println();
}
(user.birthday()) {
Omittable.Present(Instant birthday) -> System.out.println( + birthday);
-> System.out.println();
}
}
Integrations
There are several support libraries providing integrations for omittable types in third-party libraries and frameworks. These live in their own repositories:
- Omittable - Jackson Integration
- Omittable - Spring Boot Integration
- Omittable - Spring Framework Integration
- Omittable - Swagger Core Integration
Building from source
Setup
This project uses Gradle's toolchain support to detect and select the JDKs required to run the build. Please refer to the build scripts to find out which toolchains are requested.
An installed JDK 24 (or later) is required to use Gradle.
Building
Once the setup is complete, invoke the respective Gradle tasks using the following command on Unix/macOS:
./gradlew <tasks>
or the following command on Windows:
gradlew <tasks>
Important Gradle tasks to remember are:
clean- clean build resultsbuild- assemble and test the projectpublishToMavenLocal- build and install all public artifacts to the local maven repository
Additionally tasks may be used to print a list of all available tasks.
License
Copyright 2025 Leon Linhart
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance the License.
You may obtain a copy of the License at
https:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.