Inconsistency in `Specification.unrestricted()` semantics

[peteraisher]

Summary

The semantics of Specification.unrestricted() are inconsistent across different logical operator methods (or, and, not, etc.), leading to confusion and potentially incorrect assumptions when composing specifications.

Background

The documentation describes Specification.unrestricted() as:

Simple static factory method to create a specification matching all objects.

This suggests a mental model akin to:

return (root, query, builder) -> builder.conjunction(); // i.e., always true

However, the actual implementation is:

return (root, query, builder) -> null;

And per the specification contract:

Specifications returning null are considered to not contribute to the overall predicate and their result is not considered in the final predicate.

This leads to two competing interpretations:

• Interpretation A: unrestricted() behaves like true
• Interpretation B: unrestricted() behaves like SQL NULL or the Unknown state in three-valued logic.

Observed Behaviour

In practice, unrestricted() behaves like NULL in most logical operators:

Predicate predicate = ... ;
Specification other = (r, q, cb) -> predicate;

assertThat(unrestricted().or(other).toPredicate(root, query, builder))
        .isSameAs(predicate);
assertThat(unrestricted().and(other).toPredicate(root, query, builder))
        .isSameAs(predicate);
assertThat(allOf(unrestricted(), other).toPredicate(root, query, builder))
        .isSameAs(predicate);
assertThat(anyOf(unrestricted(), other).toPredicate(root, query, builder))
        .isSameAs(predicate);

This implies that unrestricted() is ignored in composition, consistent with the null return value.

However, Specification.not(..) behaves differently:

assertThat(not(unrestricted()).toPredicate(root, query, builder)).isNull(); // fails

Instead of returning null, it returns builder.disjunction() (i.e., false), based on reasoning from #3849 (emphasis mine):

In the current semantics, if specification.toPredicate() returns null, it means no condition—which logically translates to an Expression true.

Thus, in the not() method, we can return criteriaBuilder.disjunction() to represent false, because:
not(true) → false

This implies that unrestricted() is treated as true in the context of not(), breaking consistency.

Consequences

This inconsistency breaks logical equivalences. For example:

Specification a = Specification.unrestricted();
Specification b = ...;

Specification c = not(a.or(b));
Specification d = not(a).and(not(b));

Logically, c and d should be equivalent (!(a || b) == !a && !b), but:

• c becomes not(b)
• d becomes false

Proposed Solutions

Option 1: Document the inconsistency

Clarify in the documentation that Specification.unrestricted() behaves like NULL in most logical operations, but is treated as true in not(). This avoids breaking changes but requires users to be cautious when composing specifications.

Option 2: Make not(unrestricted()) return unrestricted()

This would make unrestricted() consistently behave like NULL, preserving logical equivalences. However, it breaks existing behaviour where not(unrestricted()) is expected to match no results.

Option 3: Make or() and anyOf() treat unrestricted() as true

This aligns with the idea that unrestricted() matches all objects. It would make unrestricted().or(other) behave like true || other, but introduces broader breaking changes.

Request for Feedback

Would the maintainers prefer Option 1 (document), Option 2 (change not()), Option 3 (change or()/anyOf()), or another approach?
Happy to submit a PR based on the preferred direction.

[mp911de]

The desired functionality of unrestricted() is to not participate in the predicate chain (and therefore mapping to be invisible) in the actual evaluation. While it would be possible to think about it as being always true, it's rather representing an empty state that isn't involved in forming the final query predicate.

You are however right, that we've got some inconsistency that we've introduced with #3849 in .not(…).

For all other cases:

unrestricted().and(other) // consider only "other"
unrestricted().and(other).and(another) // consider "other" and "another" predicates

unrestricted().or(other) // consider only "other"
unrestricted().or(other).or(another) // consider "other" and (via `OR`) "another" predicates

not(unrestricted()).or(other) // render only the predicate of other
not(unrestricted()).and(other) // render only the predicate of other
not(unrestricted()).and(other).or(unrestricted()) // render only the predicate of other

With the idea from above, unrestricted() would never render into an actual predicate.

There's also the purely boolean way of thinking, considering unrestricted() as being always true with dramatically different outcomes. In the boolean way of thinking, not(unrestricted()).and(other).or(unrestricted()) would yield always true (as in !true && other || true) instead of only considering other.

For the start I think fixing not behavior and refining the documentation to consider unrestricted() a null-object should help. Let me know what you think.

[peteraisher]

Thanks for the thoughtful response. I'll go ahead and fix the not behaviour and see if I can refine the documentation on unrestricted().

[peteraisher]

When running ./mvnw clean test locally on the main branch, I'm getting some compiler errors during testCompile:

spring-data-jpa/src/test/java/org/springframework/data/jpa/repository/aot/TestJpaAotRepositoryContext.java:[52,8] org.springframework.data.jpa.repository.aot.TestJpaAotRepositoryContext is not abstract and does not override abstract method contributeTypeConfigurations(org.springframework.aot.generate.GenerationContext) in org.springframework.data.aot.AotContext
spring-data-jpa/src/test/java/org/springframework/data/jpa/repository/config/JpaRepositoryRegistrationAotProcessorUnitTests.java:[264,17] method does not override or implement a method from a supertype
spring-data-jpa/src/test/java/org/springframework/data/jpa/repository/config/JpaRepositoryRegistrationAotProcessorUnitTests.java:[294,17] method does not override or implement a method from a supertype
spring-data-jpa/src/test/java/org/springframework/data/jpa/repository/config/JpaRepositoryRegistrationAotProcessorUnitTests.java:[215,16] org.springframework.data.jpa.repository.config.JpaRepositoryRegistrationAotProcessorUnitTests.DummyAotRepositoryContext is not abstract and does not override abstract method contributeTypeConfigurations(org.springframework.aot.generate.GenerationContext) in org.springframework.data.aot.AotContext
spring-data-jpa/src/test/java/org/springframework/data/jpa/repository/config/JpaRepositoryRegistrationAotProcessorUnitTests.java:[264,17] method does not override or implement a method from a supertype
spring-data-jpa/src/test/java/org/springframework/data/jpa/repository/config/JpaRepositoryRegistrationAotProcessorUnitTests.java:[294,17] method does not override or implement a method from a supertype

I'm assuming there's something I've missed.
Is there a guide for building locally?

[mp911de]

Seems your repo is outdated, a5b5c2e is the latest commit that aligns with Spring Data Commons changes. In doubt, force snapshot dependency refresh with -U.