What is the reason for such hard restriction on workflow's name ?

[cvgaviao]

Hello,

I've tried to map one of the existing processes I have into OpenWorkflow doc, and then I got this error:

com.fasterxml.jackson.databind.JsonMappingException: name: must match "^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$" (through reference chain: io.serverlessworkflow.api.types.Workflow["document"])

So, we can't use underscores nor hyphens, and only allowed to have 64 chars for names.

what is the reason ?

[cdavernas]

This restriction exists because document.name is a machine identifier, not a display label. It is deliberately constrained to a DNS-label-compatible format so that the same workflow name can be safely reused across runtimes, registries, URLs, Kubernetes resources, service discovery, and other infrastructure without each implementation inventing its own escaping or normalization rules.

The 63-character limit comes from the DNS label limit defined by RFC 1035. Underscores are excluded because they are not valid in hostname-style DNS labels, while hyphens are allowed internally, but not as the first or last character. This avoids ambiguous transformations and collisions such as both payment_request and payment-request being normalized to the same value.

As with Kubernetes, rejecting invalid identifiers early guarantees portability and deterministic behavior. Human-readable names are not lost: Open Workflow provides document.title and document.summary for descriptive text, while document.name remains a stable technical identifier, just like document.namespace, which it is used in conjunction with.

[cvgaviao]

@cdavernas , thank you for you time and the answer.

if my POC were approved, I will create a transformation tool to normalize our Processes and Task names, since we use underscore everywhere.