OpenCms Documentation

JSON support

 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 10.5 Valid for OpenCms: 11.0.0

This feature allows you to convert sections of a rendered page's HTML to JSON for use by external appications.


This feature allows you to convert parts of a page's HTML to JSON. Which parts of a page are converted to JSON can be controlled by use of the <cms:jsonpart> tag (from the OpenCms tag library) in your templates or formatters (or any other JSPs used for rendering a page).

This can be useful for reusing parts of the HTML of an OpenCms page in external applications.


This following  assumes that in your JSPs, you include the penCms tag library as follows:

<%@ taglib prefix="cms" uri=""%>


When the URL of an incoming request contains the request parameter "__json=true", JSON conversion is activated for this request. This means that instead of rendering the page normally, OpenCms produces JSON output that contains selected sections of the page's HTML as JSON values.

The <cms;jsonpart> tag can be used to control which parts of the JSP output should be used as JSON values, and the element attribute of the tag is used to control the JSON key for the value produced from the tag's body.

For example, the output of the JSP code:


<%@ taglib prefix="cms" uri=""%>

lorem ipsum
<cms:jsonpart element="part1">this is the first part</cms:jsonpart>

lorem ipsum

<cms:jsonpart element="part2">this is the second part</cms:jsonpart>

will, when in JSON conversion mode, be converted to the (approximate) JSON output:


"part1": "this is the first part",

"part2": "this is the second part",

"parts": ["part1", "part2"]


(Note that spacing/newlines have been adjusted in this example to increase readability. The actual output will look more messy.)

When not in JSON conversion mode, the <cms:jsonpart> tag will leave its content's output unchanged, i.e. the output will be the same as if the tags weren't there.

In JSON conversion mode, everything except the parts of the page enclosed by these tags is thrown away, and the response text will consist of a single JSON object  with the key-value pairs described above.

An additional key-value pair with the key "parts" is added to this object, which contains an array of the other key names, in the order they were processed while rendering the original page.

<cms:jsonpart> tags may not be nested either directly in the same JSP file, or indirectly, i.e. by including a JSP file using <cms:jsonpart> inside the body of another <cms:jsonpart> tag.

Note that the tag does not require that the output of its content is valid HTML; it is your responsibility as a developer to ensure this if the application consuming the JSON output requires valid HTML as JSON values.

Detecting JSON requests

In some cases, it might be useful to detect in your JSP whether the current request is running in JSON mode or not. This can be checked by using the attribute "isJSONRequest" on the CmsJspStandardContextBean instance commonly available in EL expressions under the name "cms":

<c:if test="${cms.isJSONRequest}">
this is a JSON request

Error handling

If a page, when requested, would produce an HTTP status code which is not 200, then the response when requesting the same page in JSON mode will not, in general, be usable JSON.

If, while in JSON conversion mode, an exception is thrown and not caught while inside the body of a <cms:jsonpart> tag, but caught before escaping the top-level JSP, then valid JSON will be returned in the response, but the value corresponding to the <cms:jsonpart> tag from which the exception originated will be truncated and contain only the output which was printed before the exception was thrown.

Filter configuration

The functionality described above relies on a special servlet filter, which is enabled by default on a freshly set up OpenCms instance.
If you are using an OpenCms instance which was updated from an earlier version and haven't replaced your web.xml file, you may need to configure this filter manually.  

Ensure that your WEB-INF/web.xml contains the following entries:


If the OpenCmsUrlServletFilter is configured in your web.xml, take care to place the <filter-mapping> for the CmsJsonPartFilter after the <filter-mapping> for the OpenCmsUrlServletFilter.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.