This is an advanced topic for people who need to work with metadata directly through the API or Imports. You may be looking for

the Metadata

 page instead. 

This page details the structure of metadata which must be followed if you are working with metadata directly as JSON. This structure is essential to maintaining the functionality of metadata through the Liquid State System. You need to understand this if you are going to be changing metadata through either

1. Imports or,
2. API Calls

Basic Structure

Metadata for Carbon has a basic structure which must be preserved. The top level object is composed of as many keys as you like, however there are two reserved keys which have special meaning in the Liquid State System.

1. readonly and,
2. tags

Readonly

Readonly is a place for metadata which is maintained by automated systems and cannot be changed once it is set. This is ideal for Liquid State maintained metadata and for any custom metadata you might produce which should not be changed by users once it is in place. Within readonly we strongly recommend that you namespace your metadata, for example Liquid State uses a key called "ls" as an organisational namespace followed by keys for each of the products which set metadata e.g. "feeds", "carbon", "ubiquity".

Readonly metadata can only be set by Imports, it cannot be replaced via API calls.

Tags

Tags is the second reserved key in metadata. This key can be set, and can be edited by users in Carbon however it has a required schema which cannot be changed. The tags key must follow these rules:

1. tags must be an array
2. each tag in the array must be an object containing the following keys
   1. term: this is the actual value which will be used for comparing tags. This should be normalised for easy comparisons (lowercase, single word or hyphenated slug)
   2. label: this is the value which will be displayed in the User Interface
   3. namespace: This is an optional value which can be used to separate multiple tags with the same term but different meanings. It should be blank not missing if it is unset.

Tags can be set via the API, Imports and the User Interface in carbon.

Example metadata

The following is an example metadata object which could be included in an import.

{
	"readonly": {
		"my-company": {
			"product-id": {
				"database_id": 1			
			}
		}	
	},
	"tags": [
		{
			"term": "infection",
			"label": "Infection",
			"namespace": ""
		},
		{
			"term": "virus",
			"label": "Virus",
			"namespace": ""
		}
	],
	"my-company": {
		"product-id": {
			"editable": "field"
		}
	}
}