Document Types and Metadata Sets API Basics

Liferay DXP 2025.Q1+

Liferay’s headless delivery application provides REST services for Documents and Media that add document types and metadata sets to sites or asset libraries, list their information, modify them, delete them, and more. You can call those services using cURL commands and Java classes.

Note

Liferay DXP 2024.Q4+/Portal GA129+ External Reference Codes (ERCs) are accessible for document entries, folders, types, metadata sets, and shortcuts, providing a consistent way to identify and access these elements across Liferay.

Start by setting up the environment and gathering the necessary information.

Set Up The Environment

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.120-ga120

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

When signed in, retrieve the site ID. Use this ID in several service calls. In this example, the site ID is 20117.

If you’re working with an Asset Library, you must retrieve the asset library ID.

If you create an asset library, the ID appears in the General tab after you create it.

If you already have one,

Open the Global Menu (), go to the Applications tab, and click Asset Libraries under Content.
Click Actions () for the asset library you want and select Edit. The ID appears in the General tab.

Then, download and unzip the example project:

curl https://resources.learn.liferay.com/dxp/latest/en/content-authoring-and-management/documents-and-media/developer-guide/liferay-r5b2.zip -O

unzip liferay-r5b2.zip

Now, start by posting a document’s metadata set.

Post a Metadata Set to a Site or Asset Library

Post metadata sets to sites or asset libraries.

In the terminal, run the DocumentMetadataSets_POST_ToSites.sh to post the metadata set to a site. Use the site-ID as parameter.

Note

The examples used here are intended for sites. Examples intended for asset libraries are included in the resource’s curl and java folders. Replace the site-ID for the asset-library-ID to test them.

./DocumentMetadataSets_POST_ToSites.sh [site-ID]

The terminal shows a similar output. Information about the metadata set is returned, including details about its fields.

{
   "actions" : {
      "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/document-metadata-sets/32215"
      }
   },
   "availableLanguages" : [ "en-US" ],
   "dataDefinitionFields" : [ {
      "customProperties" : {
         "hideField" : false,
         "tooltip" : {
         "en_US" : ""
         },
         "nativeField" : false,
         "fieldReference" : "employeeId",
         "placeholder" : {
         "en_US" : ""
         }
      },
      "defaultValue" : {
         "en_US" : ""
      },
      "fieldType" : "numeric",
      "indexType" : "keyword",
      "indexable" : true,
      "label" : {
         "en_US" : "Employee ID"
      },
      "localizable" : false,
      "name" : "Numeric51379672",
      "nestedDataDefinitionFields" : [ ],
      "readOnly" : false,
      "repeatable" : false,
      "required" : false,
      "showLabel" : true,
      "tip" : {
         "en_US" : ""
      }
   } ],
   "dateCreated" : "2025-01-22T17:29:13Z",
   "dateModified" : "2025-01-22T17:29:13Z",
   "description" : "",
   "description_i18n" : { },
   "externalReferenceCode" : "d325cda3-a1f7-67af-8066-20c99c84470f",
   "id" : 32215,
   "name" : "Metadata Set for Employee ID",
   "name_i18n" : {
      "en-US" : "Metadata Set for Employee ID"
   },
   "siteId" : 20117
}

To verify that the metadata set was created, open the Site Menu (), expand Content and Data, and go to Documents and Media → Select the Metadata Sets tab to confirm that the Metadata Set for Employee ID appears there.

Next, use a Java class to post a metadata set.

Go to the java folder and compile the Java source files.
```
cd ../java
```
```
javac -classpath .:* *.java
```
Post a metadata set to Documents and Media by running the DocumentMetadataSets_POST_ToSites class below, replacing the siteId system property value with your site ID.
```
java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DsiteId=1234 DocumentMetadataSets_POST_ToSites
```
If you’re using an older version of Liferay on Java 8, remove the --add-opens argument:
```
java -classpath .:* -DsiteId=1234 DocumentMetadataSets_POST_ToSites
```
Note

If your user and password aren’t test@liferay.com and learn, respectively, replace those values in the DocumentMetadataSets_POST_ToSites.java file and recompile the class before running it.

The class creates a metadata set int the site’s Documents and Media application.

Read on to see how the cURL command and Java class work.

Examine the cURL Command

The DocumentMetadataSets_POST_ToSites.sh and DocumentMetadataSets_POST_ToAssetLibraries.sh scripts post metadata sets by calling a headless-delivery application REST service with cURL.

Here are the command’s arguments:

Arguments	Description
`"http://localhost:8080/o/headless-delivery/v1.0/sites/{1}/document-metadata-sets"`	The REST service endpoint. Your site ID parameter replaces `${1}`.
`"http://localhost:8080/o/headless-delivery/v1.0/asset-libraries/{1}/document-metadata-sets"`	The REST service endpoint. Your asset library ID parameter replaces `${1}`.
`--data-raw`	The raw JSON data sent in the request body.
`--header "accept: application/json"`	Specifies that the client expects a response in JSON format.
`--header "Content-type: application/json" \`	The media type (MIME type) of the resource sent to the server is JSON.
`--request "POST"`	The HTTP method to invoke at the specified endpoint.
`--user "test@liferay.com:learn"`	Basic authentication credentials.

Note

Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth 2.0. See Using OAuth2 to Authorize Users for a sample React application that uses OAuth2.

In the --data-raw request content, you must include the availableLanguages, dataDefinitionFields, and dataLayout properties:

The availableLanguages property specifies the languages available for the document metadata set. It’s an array of language codes.
The dataDefinitionFields property defines the fields for the metadata set. It’s an array where each item represents a field with its associated properties, such as label, type, and validation rules.
The dataLayout property defines the layout of the data in the metadata set. It specifies the arrangement of fields on pages and the layout rules. It’s important to add the fieldNames properly based on the fields that were added to the dataDefinitionFields property.

Other cURL commands for the DocumentMetadataSet REST services use similar arguments.

Examine the Java Class

The DocumentMetadataSets_POST_ToSites.java and DocumentMetadataSets_POST_ToAssetLibraries.java classes post metadata sets by calling a headless-delivery application REST service.

Line (abbreviated)	Description
`DocumentMetadataSetResource.Builder builder = ...`	Gets a `Builder` for generating a `DocumentMetadataSetResource` service instance.
`DocumentMetadataSetResource documentMetadataSetResource = builder.authentication(...).build();`	Specifies basic authentication and generates a `DocumentMetadataSetResource` service instance.
`DocumentMetadataSet documentMetadataSet = new DocumentMetadataSet() { ... };`	Creates a new `DocumentMetadataSet` object, including fields, layout, and metadata definitions for employee-related data.
`documentMetadataSetResource.postSiteDocumentMetadataSet(...);`	Calls the `DocumentMetadataSetResource.postSiteDocumentMetadataSet` method, passing in a site ID and a `DocumentMetadataSet` object to represent the document metadata set for the site.

Note that the project includes the com.liferay.headless.delivery.client.jar file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api.

Note

The main method’s comment demonstrates running the class.

The other example Java classes are similar to this one, but call different methods.

Important

See DocumentMetadataSetResource for service details.

Below are examples of calling other DocumentMetadataSet REST services using cURL and Java.

Get Metadata Sets

List document metadata sets from a site or an asset library. You can also retrieve information about a specific set using its ID.

Get Metadata Sets From a Site or Asset Library

To list document metadata sets from a site, execute the following cURL command or Java class. As above, replace [site-ID]/[asset-library-ID] with your site’s/asset library ID, respectively.

./DocumentMetadataSets_GET_FromSites.sh [site-ID]

The terminal shows a similar output.

{
   (...)
   "facets" : [ ],
   "items" : [ {
      "actions" : {
         "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/document-metadata-sets/32215"
         }
      },
      "availableLanguages" : [ "en-US" ],
      "dataDefinitionFields" : [ {
         "customProperties" : {
         "hideField" : false,
         "tooltip" : {
            "en_US" : ""
         },
         "nativeField" : false,
         "fieldReference" : "employeeId",
         "placeholder" : {
            "en_US" : ""
         }
         },
         "defaultValue" : {
         "en_US" : ""
         },
         "fieldType" : "numeric",
         "indexType" : "keyword",
         "indexable" : true,
         "label" : {
         "en_US" : "Employee ID"
         },
         "localizable" : false,
         "name" : "Numeric51379672",
         "nestedDataDefinitionFields" : [ ],
         "readOnly" : false,
         "repeatable" : false,
         "required" : false,
         "showLabel" : true,
         "tip" : {
         "en_US" : ""
         }
      } ],
      "dateCreated" : "2025-01-22T17:29:13Z",
      "dateModified" : "2025-01-22T17:29:13Z",
      "description" : "",
      "description_i18n" : { },
      "externalReferenceCode" : "d325cda3-a1f7-67af-8066-20c99c84470f",
      "id" : 32215,
      "name" : "Metadata Set for Employee ID",
      "name_i18n" : {
         "en-US" : "Metadata Set for Employee ID"
      },
      "siteId" : 20117
   } ],
   "lastPage" : 1,
   "page" : 1,
   "pageSize" : 20,
   "totalCount" : 1
}

Or execute the java class:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DsiteId=1234 DocumentMetadataSets_GET_FromSites

If you’re using an older version of Liferay on Java 8, remove the --add-opens argument:

java -classpath .:* -DsiteId=1234 DocumentMetadataSets_GET_FromSites

You can find information about the metadata set, its fields, the site/asset library where it’s stored, its ID, title, creation date, modification date, and other details related to the set.

Tip

A metadata set stored in an asset library includes an assetLibraryKey field in its response.

Get a Specific Metadata Set

Get a specific metadata set by executing the following cURL or Java command. Replace [metadataSet-ID] with the set ID.

./DocumentMetadataSets_GET_ById.sh [metadataSet-ID]

A response similar to the previous one appears with the set’s information.

Or execute the java class:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DdocumentMetadataSetId=1234 DocumentMetadataSets_GET_ById

If you’re using an older version of Liferay on Java 8, remove the --add-opens argument:

java -classpath .:* -DdocumentMetadataSetId=1234 DocumentMetadataSets_GET_ById

Post a Document Type to a Site or Asset Library

Create a document type within a site or asset library. Additionally, you can define a document type that incorporates metadata fields by using the metadata ID.

In this example, use the metadata ID to define the document type. Run the DocumentDataDefinitionTypes_POST_ToSites.sh in the terminal to post the document type to a site. Use the site-ID and document-metadata-set-ID as parameters.

Note

./DocumentDataDefinitionTypes_POST_ToSites.sh [site-ID] [document-metadata-set-ID]

The terminal shows a similar output. Information about the document type is returned.

{
   "actions" : {
      "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/document-data-definition-types/32245"
      },
      "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/document-data-definition-types/32245"
      }
   },
   "availableLanguages" : [ "en-US" ],
   "creator" : {
      "additionalName" : "",
      "contentType" : "UserAccount",
      "familyName" : "Test",
      "givenName" : "Test",
      "id" : 20123,
      "name" : "Test Test"
   },
   "dataDefinitionFields" : [ ],
   "dataLayout" : {
      "dataDefinitionId" : 32237,
      "dataLayoutFields" : { },
      "dataLayoutKey" : "32236",
      "dataLayoutPages" : [ {
         "dataLayoutRows" : [ ],
         "description" : {
         "en_US" : ""
         },
         "title" : {
         "en_US" : ""
         }
      } ],
      "dataRules" : [ ],
      "dateCreated" : "2025-01-22T17:32:08Z",
      "dateModified" : "2025-01-22T17:32:08Z",
      "description" : { },
      "id" : 32239,
      "name" : {
         "en_US" : "Employee Document Type"
      },
      "paginationMode" : "single-page",
      "siteId" : 20117,
      "userId" : 20123
   },
   "dateCreated" : "2025-01-22T17:32:08Z",
   "dateModified" : "2025-01-22T17:32:08Z",
   "description" : "",
   "documentMetadataSetIds" : [ 32215 ],
   "externalReferenceCode" : "f0ff18b9-4869-26cb-021d-86a131bd0bca",
   "id" : 32245,
   "name" : "Employee Document Type",
   "siteId" : 20117
}

To verify that the document type was created, open the Site Menu (), expand Content and Data, and go to Documents and Media. Select the Document Types tab to confirm that the Employee Document Type appears there.

Next, use a Java class to post a document type. Post a document type to Documents and Media by running the DocumentDataDefinitionTypes_POST_ToSites class below, replacing the siteId system property value with your site ID and the documentMetadataSetId with the ID for the metadata set created in the previous steps.

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DsiteId=1234 -DdocumentMetadataSetId=5678 DocumentDataDefinitionTypes_POST_ToSites

If you’re using an older version of Liferay on Java 8, remove the --add-opens argument:

java -classpath .:* -DsiteId=1234 -DdocumentMetadataSetId=5678 DocumentDataDefinitionTypes_POST_ToSites

The class creates a document type linked to the metadata set in the site’s Documents and Media application.

Read on to see how the cURL command and Java class work.

Examine the cURL Command

The DocumentDataDefinitionTypes_POST_ToSites.sh and DocumentDataDefinitionTypes_POST_ToAssetLibraries.sh scripts post document types by calling a headless-delivery application REST service with cURL.

Here are the command’s arguments:

Arguments	Description
`"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/document-data-definition-types"`	The REST service endpoint. Your site ID parameter replaces `${1}`.
`"http://localhost:8080/o/headless-delivery/v1.0/asset-libraries/${1}/document-data-definition-types"`	The REST service endpoint. Your asset library ID parameter replaces `${1}`.
`--data-raw`	The raw JSON data sent in the request body.
`--header "accept: application/json"`	Specifies that the client expects a response in JSON format.
`--header "Content-type: application/json" \`	The media type (MIME type) of the resource sent to the server is JSON.
`--request "POST"`	The HTTP method to invoke at the specified endpoint.
`--user "test@liferay.com:learn"`	Basic authentication credentials.

Note

In the --data-raw request content, you must also include the availableLanguages, dataDefinitionFields, and dataLayout properties just like with metadata sets:

Other cURL commands for the DocumentDataDefinitionType REST services use similar arguments.

Examine the Java Class

The DocumentDataDefinitionTypes_POST_ToSites.java and DocumentDataDefinitionTypes_POST_ToAssetLibraries.java classes post document data definition types by calling a headless-delivery application REST service.

Line (abbreviated)	Description
`DocumentDataDefinitionTypeResource.Builder builder = ...`	Gets a `Builder` for generating a `DocumentDataDefinitionTypeResource` service instance.
`DocumentDataDefinitionTypeResource documentDataDefinitionTypeResource = builder.authentication(...).build();`	Specifies basic authentication and generates a `DocumentDataDefinitionTypeResource` service instance.
`DocumentDataDefinitionType documentDataDefinitionType = new DocumentDataDefinitionType() { ... };`	Creates a new `DocumentDataDefinitionType` object, including metadata set IDs, fields, layout, and rules for a document type.
`documentDataDefinitionTypeResource.postSiteDocumentDataDefinitionType(...);`	Calls the `DocumentDataDefinitionTypeResource.postSiteDocumentDataDefinitionType` method, passing in a site ID and a `DocumentDataDefinitionType` object to represent the document type.

Note

The main method’s comment demonstrates running the class.

The other example Java classes are similar to this one, but call different methods.

Important

See DocumentDataDefinitionTypeResource for service details.

Below are examples of calling other REST services using cURL and Java.

Get Document Types

List document types from a site or an asset library. You can also retrieve information about a specific document type using its ID.

Get Document Types From a Site or Asset Library

To list document types from a site, execute the following cURL command or Java class. As above, replace [site-ID]/[asset-library-ID] with your site’s/asset library ID, respectively.

./DocumentDataDefinitionTypes_GET_FromSites.sh [site-ID]

The terminal shows a similar output.

{
   (...)
   "facets" : [ ],
   "items" : [ {
      "actions" : {
         "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/document-data-definition-types/32245"
         },
         "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-delivery/v1.0/document-data-definition-types/32245"
         }
      },
      "availableLanguages" : [ "en-US" ],
      "creator" : {
         "additionalName" : "",
         "contentType" : "UserAccount",
         "familyName" : "Test",
         "givenName" : "Test",
         "id" : 20123,
         "name" : "Test Test"
      },
      "dataDefinitionFields" : [ ],
      "dataLayout" : {
         "dataDefinitionId" : 32237,
         "dataLayoutFields" : { },
         "dataLayoutKey" : "32236",
         "dataLayoutPages" : [ {
         "dataLayoutRows" : [ ],
         "description" : {
            "en_US" : ""
         },
         "title" : {
            "en_US" : ""
         }
         } ],
         "dataRules" : [ ],
         "dateCreated" : "2025-01-22T17:32:08Z",
         "dateModified" : "2025-01-22T17:32:08Z",
         "description" : { },
         "id" : 32239,
         "name" : {
         "en_US" : "Employee Document Type"
         },
         "paginationMode" : "single-page",
         "siteId" : 20117,
         "userId" : 20123
      },
      "dateCreated" : "2025-01-22T17:32:08Z",
      "dateModified" : "2025-01-22T17:32:08Z",
      "description" : "",
      "documentMetadataSetIds" : [ 32215 ],
      "externalReferenceCode" : "f0ff18b9-4869-26cb-021d-86a131bd0bca",
      "id" : 32245,
      "name" : "Employee Document Type",
      "siteId" : 20117
   } ],
   "lastPage" : 1,
   "page" : 1,
   "pageSize" : 20,
   "totalCount" : 1
}

Or execute the java class:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DsiteId=1234 DocumentDataDefinitionTypes_GET_FromSites

If you’re using an older version of Liferay on Java 8, remove the --add-opens argument:

java -classpath .:* -DsiteId=1234 DocumentDataDefinitionTypes_GET_FromSites

You can find information about the document type, the site/asset library where it’s stored, its ID, title, creation date, modification date, and other details related to the document.

Tip

A document type stored in an asset library includes an assetLibraryKey field in its response.

Get a Specific Document Type

Get a specific document type by executing the following cURL or Java command. Replace [document-type-ID] with the document type ID.

./DocumentDataDefinitionTypes_GET_ById.sh  [document-type-ID]

A response similar to the previous one appears with the set’s information.

Or execute the java class:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DdataDefinitionTypeId=1234 DocumentDataDefinitionTypes_GET_ById

If you’re using an older version of Liferay on Java 8, remove the --add-opens argument:

java -classpath .:* -DdataDefinitionTypeId=1234 DocumentDataDefinitionTypes_GET_ById

Put a Metadata Set

PUT services replace the metadata set and its fields entirely. You can replace a metadata set by executing the following cURL or Java command.

In this exercise, replace the [site-ID] with the site ID and the [metadata-set-ERC] parameter with the external reference code (ERC) for the metadata set added to the site before. This updates the metadata set, changing its name.

DocumentMetadataSets_PUT_ToSitesByExternalReferenceCode.sh

Command:

./DocumentMetadataSets_PUT_ToSitesByExternalReferenceCode.sh [site-ID] [metadata-set-ERC]

The metadata set is now named Metadata Set for Employee Documents.

DocumentMetadataSets_PUT_ToSitesByExternalReferenceCode.java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DsiteId=1234 -DexternalReferenceCode=abcdef DocumentMetadataSets_PUT_ToSitesByExternalReferenceCode

If you’re using an older version of Liferay on Java 8, remove the --add-opens argument:

java -classpath .:* -DsiteId=1234 -DexternalReferenceCode=abcdef DocumentMetadataSets_PUT_ToSitesByExternalReferenceCode

The Java class calls DocumentMetadataSetsResource’s putDocument method, passing in the DocumentMetadataSets’s external reference code (ERC).

The above cURL command and Java class replace the specified DocumentMetadataSet’s name.

Delete a Metadata Set/Document Type

Delete a metadata set or a document type by executing the following cURL or Java commands. Replace [metadata-set-ID]/[document-data-definition-type-ID] with the metadata set/document type IDs, respectively.

If the operation is successful, there’s a code 204 response and nothing is returned.

DocumentMetadataSets_DELETE_ById.sh

Command:

./DocumentMetadataSets_DELETE_ById.sh [metadata-set-ID]

DocumentMetadataSets_DELETE_ById.java

Command

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DdocumentMetadataSetId=1234 DocumentMetadataSets_DELETE_ById

If you’re using an older version of Liferay on Java 8, remove the --add-opens argument:

java -classpath .:* -DdocumentMetadataSetId=1234 DocumentMetadataSets_DELETE_ById

DocumentDataDefinitionTypes_DELETE_ById.sh

Command:

./DocumentDataDefinitionTypes_DELETE_ById.sh [document-data-definition-type-ID]

DocumentDataDefinitionTypes_DELETE_ById.java

Command

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DdocumentDataDefinitionTypeId=1234 DocumentDataDefinitionTypes_DELETE_ById

If you’re using an older version of Liferay on Java 8, remove the --add-opens argument:

java -classpath .:* -DdocumentDataDefinitionTypeId=1234 DocumentDataDefinitionTypes_DELETE_ById

The metadata set and document type are removed from Documents and Media.

Capability:

Digital Asset Management

Resource Type:

Official Documentation

Feature:

API Development

Documents and Media

Deployment Approach:

Liferay PaaS

Liferay SaaS

Liferay Self-Hosted