This blog post, part of a series about JSON data formats in the Contentstack SaaS headless CMS, describes how Contentstack represents media asset metadata and references as JSON.
In Contentstack, assets store metadata about files uploaded into the CMS. Technically, assets are like entries in that they consist of structured field values, but with some differences:
- Contentstack automatically determines the asset structure and certain field values, such as the binary file size and whether to include image dimensions as well as values for those dimensions.
- You cannot add, change, or remove asset fields.
- One field of the asset contains the URL of a binary resource on the Contentstack media CDN.
- Assets use different APIs than entries.
- In the content management environment, assets may appear in folders, but that information is not available to content delivery APIs.
To associate assets with content, content types can include file fields. In entries, the values of file fields reference one or more assets by their identifiers. For a file field that allows a single selection, the value of the field is the ID of the selected asset. For file fields that allow multiple selections, the value of the field is the list of IDs. Entries do not actually contain asset metadata.
To optimize common use cases, APIs render asset metadata inline into each entry, duplicating that data and making it appear as part of the entry itself rather than as a separate record. If the include_publish_details query string parameter is true, as in this example, then the JSON includes publishing details for the asset separate from those of the entry.
Whether you retrieve the asset metadata directly from an API or from the field of an entry, the format is the same. What follows is an example of asset metadata inlined into the value of a file field.
"filefieldkey": {
"uid": "blt6275efe2e38a8d63",
"created_at": "2021-11-30T15:35:40.831Z",
"updated_at": "2021-11-30T15:35:40.831Z",
"created_by": "bltf659c3e814f4dce6",
"updated_by": "bltf659c3e814f4dce6",
"content_type": "image/jpeg",
"file_size": "116614",
"tags": [],
"filename": "filename.jpg",
"url": "https://images.contentstack.io/v3/assets/blt69c032f07cada0c4/blt6275efe2e38a8d63/61a644cc3bee072a7f478ff7/filename.jpg",
"ACL": [],
"is_dir": false,
"parent_uid": null,
"_version": 1,
"title": "filename.jpg",
"dimension": {
"height": 1004,
"width": 800
},
"publish_details": [
{
"environment": "blt32092e3976f60b0b",
"locale": "en-us",
"time": "2021-11-30T16:08:47.288Z",
"user": "bltf659c3e814f4dce6",
"version": 1
}
]
},
Assume that the is_dir and parent_uid keys are internal for managing asset folders.
Content delivery synchronization APIs do not inline asset metadata, providing entry and asset data separately, and may be more efficient under other use cases.
In this example, you can see separate synchronization events for an entry and an asset.
"items": [
//...
{
"event_at": "2021-11-30T16:08:47.226Z",
"type": "asset_published",
"content_type_uid": "sys_assets",
"data": {
"_version": 1,
"is_dir": false,
"uid": "blt6275efe2e38a8d63",
//...
}
},
//...
{
"event_at": "2021-12-01T15:36:23.317Z",
"type": "entry_published",
"content_type_uid": "contenttypekey",
"data": {
"_version": 1,
"locale": "en-us",
"uid": "bltb001c2cd672a1518",
//...
"file": "blt6275efe2e38a8d63",
//...
}
},
//...
],
As it is based on the typical structure of an entry, the JSON representation of an asset is relatively self-explanatory. For reference:
To optimize and otherwise manipulate images, add query string parameters to the value specified by the url key.
A convenient way to associate custom data with a file is to create a group field to contain a file field, with additional fields within that group to contain the custom data.
Deliverystack.net 
2 thoughts on “Contentstack JSON Data Formats: Assets and File Fields”