If you’re building headless APIs with REST Builder on Liferay 2025.Q3 or newer, there’s one small configuration detail that can cause big headaches if you miss it.

In your rest-config.yaml, you must declare that your API should use the Jakarta namespace.

If you don’t, REST Builder defaults to javax, and the generated code won’t match the runtime environment—leading to confusing deployment errors that are annoying to track down.

This setting is easy to overlook… but essential.

The Important Bit

REST Builder includes a field called javaEEPackage:

javaEEPackage: the namespace to use for code generation. This namespace 
must match the Liferay version on which you’re deploying your APIs. By 
default, REST Builder generates code using the Java EE namespace (javax). 
If you use a recent version of Liferay that’s moved to Jakarta, set the 
value to jakarta.

If you’re on Liferay 2025.Q3+, you want:

javaEEPackage: "jakarta"

Example rest-config.yaml (Based on the Learn Site, Updated for Jakarta)

apiDir: "../headless-r3b2-api/src/main/java"
apiPackagePath: "com.acme.headless.r3b2"

application:
  baseURI: "/headless-r3b2"
  className: "HeadlessR3B2Application"
  name: "Liferay.Headless.R3B2"

author: "Jonah the son of Amittai"

clientDir: "../headless-r3b2-client/src/main/java"
testDir: "../headless-r3b2-test/src/testIntegration/java"

# 👇 Add this for Liferay 2025.Q3+
javaEEPackage: "jakarta"

That’s it. One line saves you a whole lot of deployment failure messages.

Full Documentation

If you want the complete explanation of all supported fields, see:

https://learn.liferay.com/w/dxp/integration/rest-builder/producing-and-implementing-apis-with-rest-builder#yaml-configuration

Need Help?

If you run into issues or have questions, just post them on https://discuss.liferay.com we’re always happy to help.