API usability: defaultNumPartitions validation is too strict for non-partitioned topic type

[Shawyeok]

Problem Description

When setting autoTopicCreation on namespace policy, the API validation prevents setting defaultNumPartitions when the topic type is non-partitioned. This limitation makes the API harder to use and less flexible.

Current behavior:

• Setting defaultNumPartitions with topicType="non-partitioned" results in a validation error: "[defaultNumPartitions] is not allowed to be set when the type is non-partition."

Code location: https://github.com/apache/pulsar/blob/53162ff745f3381ad97afeebd613c291e7b4bd2e/pulsar-client-admin-api/src/main/java/org/apache/pulsar/common/policies/data/impl/AutoTopicCreationOverrideImpl.java#L54-L59

Use Cases Affected

1. Configuration management: Users managing configurations programmatically or via infrastructure-as-code tools may want to set a default value even for non-partitioned topics, especially if they plan to switch to partitioned topics later.

2. API consistency: The validation requires users to conditionally include/exclude the defaultNumPartitions field based on topic type, making the API less consistent and more error-prone.

3. Configuration templates: Shared configuration templates or defaults become harder to maintain when they need to conditionally exclude fields.

Proposed Solution

Consider relaxing this validation to allow defaultNumPartitions to be set (but ignored) when topicType="non-partitioned". This would:

• Make the API more user-friendly
• Allow for more flexible configuration management
• Maintain backward compatibility (non-partitioned topics would still be created correctly)
• Simplify client code that doesn't need to conditionally set fields

Alternatively, if there's a technical reason this field must not be set, it would be helpful to document this clearly and potentially provide a clearer error message explaining why.

Question

Is this limitation necessary from a technical standpoint, or could it be relaxed to improve API usability?

Environment

• Pulsar version: 3.x, 4.x
• Component: Admin API / Namespace Policy

[Shawyeok]

Note: This issue was organized and created with the assistance of AI to help identify and document API usability concerns.