JSTL Formatting

The fmt library is the Jakarta Tags library whose URI is jakarta.tags.fmt (conventionally the prefix fmt). Its actions fall in two groups: the i18n actions (fmt:setLocale, fmt:bundle, fmt:setBundle, fmt:message, fmt:param and fmt:requestEncoding, covered by the character encoding page) and the formatting actions below. The two groups share one locale mechanism, which is why this page keeps referring to the other one. The library is current: Tags 3.0 is the version of Jakarta EE 10 and 11, and nothing in the Jakarta EE 12 plan removes it.

Source: Jakarta Standard Tag Library 3.0 — 9. Formatting Actions

Every action is usable without a body except fmt:timeZone, and formatNumber, parseNumber and parseDate accept their value as the trimmed body instead of the value attribute (examples below). The type, pattern, var and scope attributes work the same way across the actions, and scope without var is a translation-time error. The actions format with java.text classes (DecimalFormat, SimpleDateFormat, DateFormat), so everything the Java SE documentation says about those classes, including how locale data is chosen, applies to the output.

The taglib directive is the one that every page of this section uses, with the jakarta.tags.* URI. The old http://java.sun.com/jsp/jstl/fmt URI is not a link to anything any more (the Tags 3.0 release page says only that the old URIs may still be used as identifiers), and the specification and every tool of the Jakarta era use the new one.

Source: Jakarta Standard Tag Library 3.0 — tag documentation

All the examples are files of one Maven WAR, g5jstlformatting.war, deployed under the context path /g5jstlformatting on Tomcat 11.0.26. Its dependencies are those of the Getting Started page of this section (provided Servlet, Pages and EL APIs, plus the Jakarta Tags API and its implementation, which Tomcat does not include). One servlet puts a Book record and a list holding it in the request, plus a fixed now so that every output is repeatable, and forwards to /WEB-INF/views/<name>.jsp (the views live under WEB-INF, as everywhere in this section).

The price is deliberately a BigDecimal (money is never a double), the rating is a double between 0 and 1 so that it can be shown as a percentage, and the publication date is stored as the instant of midnight UTC, as many databases and importers do. The released field holds the same day as a LocalDate, to show what the tags cannot yet do with it. Unless a section says otherwise, web.xml contains two context parameters, the default time zone and the fallback locale, which are explained in the configuration section:

Source: Jakarta Standard Tag Library 3.0 — 9.11 Configuration Settings

A word on reading the outputs. Java 21 uses the Unicode CLDR locale data, and CLDR separates numbers from their symbols with no-break characters: U+00A0 (no-break space) before € or % in Spanish and German, and U+202F (narrow no-break space) as the thousands separator in French and before AM and PM in English times. They look like spaces, they are not spaces, and the output blocks below show them as ordinary spaces. A comparison or a parse that types a normal space fails, which is a pitfall in its own right (see the pitfalls table).

Before the tags themselves, the two rules that explain most of the output. An action never "has" a locale; it finds one every time it runs, following the algorithm of specification section 9.2 and 9.3.

The steps in the diagram, in order:

Source: Jakarta Standard Tag Library 3.0 — 9.2 Formatting Locale

Source: Jakarta Standard Tag Library 3.0 — 9.3.3 Formatting Locale Lookup Algorithm

The last step is not theoretical. These are the same page, the same tags and the same data, requested with three different headers, on a JVM whose default locale is es_ES and with no fallbackLocale configured:

The first request has no Accept-Language header, so the tags see no preferred locale (the Servlet API’s request.getLocale() still answers en_US there, which is why ${pageContext.request.locale} is a poor proxy for what the tags will do) and print the raw values. The third has a header that names a locale Java does not know. Browsers always send the header, curl, health checks, tests and many API clients do not, and that is why a "formatting" page can look correct in the browser and print 1234.5 in a script. The fix is to configure a fallbackLocale, or to call fmt:setLocale from the page or from a filter. With the context parameter above the same two requests print 1.234,50 € and 8 de octubre de 2026.

A locale that is available but incomplete is the other trap. Accept-Language: sw (Swahili, language only) matches the available locale sw, which has no country and therefore no currency, so the currency format prints the generic currency sign ¤ (observed: ¤ 1,234.50). A fallback locale should therefore name a country too: es_ES printed 1.234,50 €, while the language-only es printed 1.234,50 ¤ in the same test.

Source: Jakarta Standard Tag Library 3.0 — 9.3 Establishing a Formatting Locale

Source: Jakarta Standard Tag Library 3.0 — 8.11.2 Fallback Locale

The time zone has a shorter chain, used by fmt:formatDate and by fmt:parseDate for text that carries no zone of its own:

Source: Jakarta Standard Tag Library 3.0 — 9.4 Time Zone

The locale and the time zone are independent: a Spanish user can see Tokyo time, and a Japanese user can see Madrid time. The browser tells the server nothing about the time zone, so unless the application records it (a profile setting, a cookie set by JavaScript, an offset sent with a form) the container’s zone is what every user sees. The number and currency formatting does not depend on the time zone.

fmt:formatNumber formats a number according to the formatting locale (type) or to a custom pattern (pattern), and fine-tunes the result with the digit and grouping attributes.

Source: Jakarta Standard Tag Library 3.0 — 9.7 fmt:formatNumber

Source: Jakarta Standard Tag Library 3.0 — tag documentation, fmt:formatNumber

fmt:parseNumber is the inverse: it reads text written with the conventions of a locale (or a pattern) and produces a Number.

Source: Jakarta Standard Tag Library 3.0 — 9.8 fmt:parseNumber

Source: Jakarta Standard Tag Library 3.0 — tag documentation, fmt:parseNumber

Parsing is where the conventions are strictest, because the same text means different numbers in different locales:

Source: Jakarta Standard Tag Library 3.0 — 9.1.1 Formatting Numbers, Currencies, and Percentages

The percent text of line 4 is 87,5 % with a no-break space (U+00A0) before the sign, which is what es_ES prints on Java 21 and therefore what the parser expects; the servlet put that string in the request attribute pctEs for the test. The result is the fraction 0.875, not 87.5: a percent is divided by 100 on the way in, as it was multiplied on the way out. The last line shows that without var the number goes to the page through Number.toString(), which is not locale-aware.

fmt:formatDate formats a java.util.Date (or a subclass such as java.sql.Timestamp; java.sql.Date was observed to work) as a date, a time, or both.

Source: Jakarta Standard Tag Library 3.0 — 9.9 fmt:formatDate

Source: Jakarta Standard Tag Library 3.0 — tag documentation, fmt:formatDate

type defaults to date, so a fmt:formatDate of an instant without a type prints no time at all, which is a frequent "where did the time go?" question. The styles run through every locale’s own conventions (the instant is 2026-10-08 14:30 UTC, the time zone of the application Madrid, which is CEST, UTC+2):

Source: Jakarta Standard Tag Library 3.0 — 9.1.2 Formatting Dates and Times

Source: Java SE 21 — DateFormat

The five styles of one locale (en_US, both date and time) show the ladder from terse to verbose:

Source: Jakarta Standard Tag Library 3.0 — 9.9 fmt:formatDate

A java.util.Date is an instant; the same instant is a different wall-clock time in each zone. fmt:timeZone sets the zone for every fmt:formatDate and fmt:parseDate in its body; fmt:setTimeZone stores a zone either as a variable or as the default for a scope. A zone is a TimeZone object or a string: a Java time-zone ID such as Asia/Tokyo (the tz database names), or a custom ID such as GMT+1:00.

Source: Jakarta Standard Tag Library 3.0 — 9.5 fmt:timeZone

Source: Jakarta Standard Tag Library 3.0 — 9.6 fmt:setTimeZone

The five ways to choose a zone, in the order of the precedence chain, in one page (the application default is Madrid):

Source: Jakarta Standard Tag Library 3.0 — 9.1.2 Formatting Dates and Times

Source: Java SE 21 — TimeZone, custom IDs

Reading the output: the context parameter is the default (line 4), fmt:setTimeZone with a scope replaces it for that scope (line 5), and a fmt:setTimeZone with var only creates a variable, so the line that follows it still shows Auckland (line 6); the variable becomes useful when it is passed as a timeZone attribute (line 7), the last line showing that an attribute beats everything. The fmt:setTimeZone with scope="session" is the way to remember a user’s zone for the whole visit; put it in the request that reads the profile. Three behaviours of the platform are worth remembering:

Source: Jakarta Standard Tag Library 3.0 — 9.4 Time Zone

fmt:parseDate takes text and a description of its shape, and produces a java.util.Date. It has the attributes of fmt:formatDate (type, dateStyle, timeStyle, pattern, timeZone, var, scope), a parseLocale like fmt:parseNumber, and a body as an alternative to value. The parse is non-lenient: a date that does not exist is an error, not the next valid day.

Source: Jakarta Standard Tag Library 3.0 — 9.10 fmt:parseDate

Source: Jakarta Standard Tag Library 3.0 — tag documentation, fmt:parseDate

Source: Jakarta Standard Tag Library 3.0 — 9.10 fmt:parseDate

p1 is the specification’s own example. p2 and p3 are the same text read in two zones: without timeZone the text is Madrid’s midnight (UTC+1 on that day of 1967, hence the hour of difference with UTC) and with it UTC’s midnight. p4 shows the zone attribute applied to the time of day, and p5 that parseLocale (not the page’s locale, en_US here) decides how the Spanish month names read. The p5 and p2 numbers are equal because both mean midnight in Madrid on the same day. Without var the parsed date is written with Date.toString(), in the container’s zone, which is almost never what a page wants.

A date that does not exist is rejected, and so is text that does not match the style exactly:

Source: Jakarta Standard Tag Library 3.0 — 9.10 fmt:parseDate

February 31st is rejected because the parse is non-lenient, as the specification requires. The second line is the Java 20 change in disguise: the en_US short style of Java 21 is 10/8/26, 4:30 PM with a comma after the date and a narrow no-break space before PM, so the text a person (or a Java 17 era test fixture) types, 10/8/26 2:30 PM, does not match and the parse fails. The third line, whose dtUs is the text with the comma and the U+202F, parses. Parsing text typed by a user with a style is therefore fragile across Java versions; prefer a pattern that you control, yyyy-MM-dd for text from a form or a feed, and the <input type="date"> of HTML, which always submits that format.

Source: Oracle — JDK 20 Release Notes, Issues (CLDR 42 and the narrow no-break space)

The value attribute of fmt:formatDate is typed java.util.Date, and Tags 3.0 knows nothing about java.time. A LocalDate, LocalDateTime, Instant or ZonedDateTime is rejected before the tag runs. A String is rejected too, because there is no editor that turns text into a Date:

Source: Jakarta Standard Tag Library 3.0 — 9.9 fmt:formatDate

The first error is the Expression Language’s attempt to coerce the attribute to the declared type; the second comes from the Jasper compiler for a literal that must become a Date. This is the single most common complaint about the library in modern projects, and the Jakarta Tags project has recorded it: issue 247, "Support java.time API in fmt:parseDate and fmt:formatDate", is the one feature planned for Tags 3.1 (Jakarta EE 12), which also raises the minimum Java to 21. Tags 3.1 is under development and available only as milestone builds, so a production page today needs one of these four workarounds, from the most to the least recommended:

Source: Jakarta Standard Tag Library 3.1 (under development)

Source: Java SE 21 — DateTimeFormatter

Source: Jakarta Tags issue 247 — Support java.time API in fmt:parseDate and fmt:formatDate

The workarounds, in prose:

A custom EL function or a tag file wrapping DateTimeFormatter is the clean way to reuse workaround 3; both are covered by the SimpleTag and TLDs and EL functions pages of this section. Until Tags 3.1 is final and the container ships it, none of this code needs to change when it arrives.

The formatting actions read four configuration variables, all in the jakarta.servlet.jsp.jstl.fmt. namespace (the 1.x and 2.x names began with javax.). The jakarta.servlet.jsp.jstl.core.Config class has a constant for each.

Source: Jakarta Standard Tag Library 3.0 — 9.11 Configuration Settings

Source: Jakarta Standard Tag Library 3.0 Javadoc — Config

The two forms of setting a variable are different animals. A tag (fmt:setLocale, fmt:setTimeZone, fmt:setBundle) sets the variable in the scope you name (page by default, then request, session or application), so it lives and dies with that scope; the implicit objects and scopes page explains the scopes. A context-param in web.xml sets it for the whole application and is the right place for the defaults: the zone of the business, the fallback locale. Setting the variable with c:set under the plain variable name, in request scope, had no effect in the test (observed with fallbackLocale: the page still printed 1234.5), because the library does not read a plain attribute of that name as a setting. Use the tags, Config.set in Java (from a filter that reads the user’s profile) or the context parameter.

A filter that sets the formatting configuration from a user profile is the usual way to make the whole application obey it without a tag on every page:

Source: Jakarta Standard Tag Library 3.0 — 9.11.1 TimeZone

The snippet was run in the test WAR (a servlet calling Config.set made the same page print ￥1,234 and 2026年10月8日 23:30:00 JST). Specification section 9.11.1 prints the constant as Config.FMT_TIMEZONE, which does not exist: the Javadoc constant is FMT_TIME_ZONE.

A page that combines everything above: a locale and a zone chosen by the application from two request parameters (a stand-in for a profile), a currency of the data (the books are sold in euros whatever the reader’s country), a percentage and two dates. The page has no scriptlet and no business logic; the data comes from the servlet.

Source: Jakarta Standard Tag Library 3.0 — 9. Formatting Actions

The first row has no zone parameter and prints 14:30 (UTC, the page’s default), the second 16:30 (Madrid in summer) and the third 23:30 (Tokyo). The currency attribute is the data’s, so the euro sign is printed in all three, but the third row shows the pitfall of the previous sections: the yen locale’s zero decimal places survive and 1234.5 becomes €1,234. A table of prices in a currency other than the reader’s needs minFractionDigits="2" maxFractionDigits="2". Two parameters that name a locale and a zone are untrusted input, which is why the page uses them only as the value attributes of the tags, which tolerate unknown ones (an invalid zone gives GMT and an unknown locale the fallback locale, both observed). Production code reads them from the user’s profile and checks them against a list.

The formatting tags do not write markup, so they are not an XSS vector by themselves: a number or a date formats to digits, the symbols of the locale data and spaces. The security issues are around them:

Source: Jakarta Standard Tag Library 3.0 — 9.8 fmt:parseNumber

Source: Jakarta Standard Tag Library 3.0 — 9. Formatting Actions

The tags did not change between Tags 1.1 and 3.0 in a way that affects their behaviour. What changed is the namespace of the library and, above all, the platform below it.

Source: Jakarta Standard Tag Library 3.0

Source: Jakarta Standard Tag Library 3.1 (under development)

Source: JEP 252 — Use CLDR Locale Data by Default

JSTL in Action (Manning, 2003, listed in the section bibliography) teaches JSTL 1.0 on JSP 1.2, and its chapters on formatting and internationalization are the origin of the vocabulary of this page (number and date formatting, parsing, time zones, locales). The concepts survived; the platform around them did not.

Source: Jakarta Standard Tag Library 3.0 — 9. Formatting Actions

Source: Manning — JSTL in Action