Provide metadata in an XML file
Overview
Every XML file must contain a top level <itemset> element under which any number of <item> elements can be placed, each representing a real world object. Items can be both new or metadata updates for existing items previously uploaded.
Every item should contain a set of appropriate metadata elements to describe the properties of the item, along with either one <image> or <video> element, or a <sequence> containing multiple <subitem> elements.
Here’s a simple example of how XML metadata for 3 items would look in a text editor:
<?xml version='1.0' encoding='UTF-8'?>
<itemset>
<item identifier="p1">
<title><text lang="en">George Washington</text></title>
<description>
<text lang="en">The first president of the United States</text>
</description>
<creator><text lang="en">Sam Jones</text></creator>
<image filename="george1.jpg"></image>
</item>
<item identifier="p2">
<title><text lang="en">John Adams</text></title>
<description>
<text lang="en">The second president of the United States</text>
</description>
<creator><text lang="en">Jeff Ross</text></creator>
<image filename="john1.jpg"></image>
</item>
<item identifier="p3">
<title><text lang="en">Thomas Jefferson</text></title>
<description>
<text lang="en">The third president of the United States</text>
</description>
<creator><text lang="en">A. Richardson</text></creator>
<image filename="thomas1.jpg"></image>
</item>
</itemset>
If you have multiple digitizations for the same item, then you should include these as subitems.
Each item and subitem must be identified by a unique and long lived identifier attribute. Once an item or subitem is assigned an identifier, it must not change. We recommend you set the identifier to an original unique identifier from your own system, or a URI uniquely representing the item.
Example files
To help get you started, below are a couple of example XML files. Clicking the examples will be bring you to Google Drive. Click the download button in Google Drive to save these files to your computer, then open them in a text editor.
| Examples | Basic (filled with sample data) |
|---|---|
| Complete (filled with sample data) | |
XML metadata file specification
Required elements
<title>
Definition
A short title for the item.
- Required
- Translation possible
- Maximum 100 characters
- For subitems this is a recommended field
- Must be contained inside one of the following elements:
<item><subitem>
Example
<title>
<text lang="en">Photograph of Mount Olympus</text>
</title>
Each <item> included in your metadata file must also contain one of the following media types:
<image>
Definition
Used to specify an image filename.
- The image filename is included as an attribute as shown in the example below
- You must upload an image with the same filename through the Google Developers Console before uploading your metadata file
- Must be contained inside one of the following elements:
<item><subitem>
Example
<image filename="img46692.jpg"></image>
<video>
Definition
Used to specify an a YouTube video ID.
- The YouTube video ID is included as an attribute as shown in the example below
- Videos must be public or unlisted (not private) and allow embedding
- Must be contained inside one of the following elements:
<item><subitem>
Example
<video youtubeid="q-TxebxUD54"></video>
<sequence>
Definition
Used to contain subitems for items with multiple digitizations.
- Learn more about including items with multiple digitizations
- Must be contained inside the following element:
<item>
Example
<sequence>
<subitem identifier="p314.1">
...
</subitem>
...
</sequence>
<item> or <subitem>. You will receive an error when importing your XML file if they are positioned elsewhere.
Recommended elements
<creator>
Definition
Creator of item such as the author, painter, or photographer.
- Refinements possible
- Multiple values possible
- Translation possible
- Must be contained inside the following element:
<item>
Example
<creator>
<text lang="en">Pablo Picasso</text>
</creator>
<dateCreated>
Definition
Date an item was created, such as when a painting was painted.
- Multiple values possible
- Translation possible
- Will appear next to the title
- Both start and end date fields must be included in order to display a date range
- Accepted format: YYYY, YYYY-MM-DD, or YYYY-MM
- A textual display date can be provided if appropriate
- A date range may be specified by separating the start and end date by a forward slash:
Example: YYYY-MM-DD/YYYY-MM-DD - Example values:
- 1889
- 1889-06
- 1889-09-28
- 1889-09/1890-04
- 2010-04-23/2011-02-09
- Must be contained inside the following element:
<item>
Example
<dateCreated>
<dateValue>1889-01/1905-12</dateValue>
<dateDisplay lang="en">c. 1889 - c. 1905</dateDisplay>
</dateCreated>
<description>
Definition
A lengthier description of the item.
- Translation possible
- Maximum 2000 characters
- Must be contained inside the following element:
<item>
Example
<description>
<text lang="en">This photograph shows the snow-capped peak of Mount Olympus</text>
</description>
<format>
Definition
Physical dimensions of the object.
- Refinements possible
- Multiple values possible
- Translation possible
- Example values:
- 11in x 23in
- 400mm x 350 mm
- Must be contained inside one of the following elements:
<item><subitem>
Example
<format>
<text lang="en">30cm x 48.5cm</text>
</format>
<location>
Definition
Name of the primary physical location for the item, such as the location where a photograph was taken.
- Refinements possible
- Multiple values possible
- Translation possible
- Will appear next to the title
- Provide the placename as a minimum
- Longitude and latitude can be specified optionally
- Must be contained inside the following element:
<item>
Example
<location>
<placename lang="en">Mount Olympus, Greece</placename>
<latitude>40.085556</latitude>
<longitude>22.358611</longitude>
</location>
<medium>
Definition
Material or form used by the artist/creator.
- Multiple values possible
- Translation possible
- Example values:
- Oil on Canvas
- Watercolor
- Linograph
- Must be contained inside the following element:
<item>
Example
<medium>Oil on Canvas</medium>
<type>
Definition
Physical or material type of the item.
- Refinements possible
- Multiple values possible
- Translation possible
- Example values:
- Document
- Photograph
- Video
- Must be contained inside the following element:
<item>
Example
<type>
<text lang="en">Document</text>
</type>
Optional elements
<contributor>
Definition
A person or organization that contributed to the creation of the item.
- Refinements possible
- Multiple values possible
- Translation possible
- Must be contained inside the following element:
<item>
Example
<contributor>
<text lang="en">Royal Academy of Arts</text>
</contributor>
<date>
Definition
Date or date range for the item. For example, the date the photograph was taken or the start date of the period a document was written.
- Refinements possible
- Multiple values possible
- Translation possible
- Will appear next to the title
- Both start and end date fields must be included in order to display a date range
- Accepted date formats: YYYY, YYYY-MM-DD, or YYYY-MM
- A textual display date can be provided if appropriate
- A date range may be specified by separating the start and end date by a forward slash:
Example: YYYY-MM-DD/YYYY-MM-DD - Example values:
- 1889
- 1889-06
- 1889-09-28
- 1889-09/1890-04
- 2010-04-23/2011-02-09
- Must be contained inside the following element:
<item>
Example
<date>
<dateValue>1889-01/1905-12</dateValue>
<dateDisplay lang="en">c. 1889 - c. 1905</dateDisplay>
</date>
<datePublished>
Definition
Date the item was published, such as a book.
- Multiple values possible
- Translation possible
- Both start and end date fields must be included in order to display a date range
- Accepted format: YYYY, YYYY-MM-DD, or YYYY-MM
- A textual display date can be provided if appropriate
- A date range may be specified by separating the start and end date by a forward slash:
Example: YYYY-MM-DD/YYYY-MM-DD - Example values:
- 1889
- 1889-06
- 1889-09-28
- 1889-09/1890-04
- 2010-04-23/2011-02-09
- Must be contained inside the following element:
<item>
Example
<datePublished>
<dateValue>1889-01/1905-12</dateValue>
<dateDisplay lang="en">c. 1889 - c. 1905</dateDisplay>
</datePublished>
<locationCreated>
Definition
Name of the primary physical location for the item, such as the location where a photograph was taken.
- Multiple values possible
- Translation possible
- Will appear in the details
- Must be contained inside the following element:
<item>
Example
<locationCreated>
<placename lang="en">Mount Olympus, Greece</placename>
<latitude>40.085556</latitude>
<longitude>22.358611</longitude>
</locationCreated>
<language>
Definition
Language of the material (as opposed to the language of the metadata text).
- Multiple values possible
- Translation possible
- Must be contained inside one of the following elements:
<item><subitem>
Example
<language>
<text lang="en">French</text>
</language>
<originalSource>
Definition
Should only be used if the item’s original source is different than the organization publishing the item and is used to provide attribution.
- Must be contained inside the following element:
<item>
Example
<originalSource>
<url href="http://www.example.com" lang="en">Example Museum of Fine Art</url>
</originalSource>
<provenance>
Definition
Description of provenance of object.
- Refinements possible
- Multiple values possible
- Translation possible
- Must be contained inside the following element:
<item>
Example
<provenance>
<text lang="en">Acquired by the foundation of culture preservation</text>
</provenance>
<publisher>
Definition
A person or an organization responsible for publishing the item.
- Refinements possible
- Multiple values possible
- Translation possible
- Must be contained inside the following element:
<item>
Example
<publisher>
<text lang="en">News International</text>
</publisher>
<relation>
Definition
To be used to provide a link to back to the institution's webpage for the item.
- Refinements possible
- Multiple values possible
- Translation possible
- These links are only visible when the item details panel is expanded
- Must be contained inside the following element:
<item>
Example
<relation>
<url href="http://www.example.com" lang="en">Example Museum of Fine Art</url>
</relation>
<rights>
Definition
A statement about the various property rights associated with the item, including intellectual property rights.
- Refinements possible
- Multiple values possible
- Translation possible
- Example: a copyright statement
- May be used for either a textual statement or a URL pointing to a rights statement, or a combination
- Example values:
- Copyright Acme 1999 - All rights reserved.
- http://example.org/static/terms
- Must be contained inside the following element:
<item>
Example
<rights>Copyright Acme 1999 - All rights reserved.</rights>
<subject>
Definition
Free text field for keywords representing topic of item.
- Refinements possible
- Multiple values possible
- Translation possible
- Must be contained inside one of the following elements:
<item><subitem>
Example
<subject>
<text lang="en">Berlin Wall</text>
</subject>
<transcript>
Definition
Transcript of any text in the image or video.
- Translation possible
- Must be contained inside one of the following elements:
<item><subitem>
Example
<transcript>
<text lang="en">This is some text that was seen in a painting</text>
</transcript>
Metadata property refinements
Property refinements are used to extend or provide a more specific meaning to existing properties while preserving the semantic link between the base and refined properties. For example, a property such as 'painter' can refine the existing creator property in order to supply a more specific meaning to the creator. Search results for base properties and filtering by base properties would also include results for refined properties, while preserving the refined property names when viewing detailed information for an item.
To define a refinement, add a customtype attribute to any property supporting refinements and set its value to the refined property name.
For example:
<creator customtype=”painter”>
<text>Vincent Van Gogh</text>
</creator>
Refined properties inherit the data type of the base property, and must include the same subelement as the base property. Importing metadata in an XML file is the only way to add or edit property refinements.
Custom metadata elements
Custom properties can also be used to define a complete new property without a refinement, although it is recommended to use refinements wherever possible.
Use the name attribute to provide a label to reference the custom metadata you are providing. This is demonstrated in the examples below.
After uploading custom metadata, you will see the 
<customtext>
Definition
To be used if there is additional metadata you would like to provide.
- Multiple values possible
- Translation possible
- Example: to explicitly include the name of a photographer, use a 'photographer' label
- Must be contained inside the following element:
<item>
Example
<customtext name="label">
<text lang="en">Anna Atkins</text>
</customtext>
<customlocation>
Definition
To be used if there is additional location metadata you would like to provide
- Multiple values possible
- Translation possible
- Example: to explicitly include the location of discovery, use a label like 'discovery'
- Must be contained inside the following element:
<item>
Example
<customlocation name="label">
<placename lang="en">Mount Olympus, Greece</placename>
<latitude>40.085556</latitude>
<longitude>22.358611</longitude>
</customlocation>
<customdate>
Definition
To be used if there is additional custom date fields you would like to provide.
- Multiple values possible
- Translation possible
- Example: to explicitly include the date of discovery, use a label like 'discovery'
- Both start and end date fields must be included in order to display a date range
- Accepted format: YYYY, YYYY-MM-DD, or YYYY-MM
- A textual display date can be provided if appropriate
- Must be contained inside the following element:
<item>
Example
<customdate name="label">
<dateValue>1889-01/1905-12</dateValue>
<dateDisplay lang="en">c. 1889 - c. 1905</dateDisplay>
</customdate>
<customlink>
Definition
To be used if there is additional URL you would like to provide
- Multiple values possible
- Translation possible
- Example: to explicitly include a wikipedia link, use a label like 'wikipedia'
- Must be contained inside the following element:
<item>
Example
<customlink name="label">
<url href="http://www.example.com" lang="en">Example Museum of Fine Art</url>
</customlink>
Providing multiple values
Many of the elements listed above permit more that one value, for example it's possible to list two creators for the same artwork.
To add additional values simply repeat the entire element within its <item> or <subitem> container.
Example
<item>
...
<creator>
<text lang="en">John Doe</text>
</creator>
<creator>
<text lang="en">Sam Smith</text>
</creator>
<creator>
<text lang="en">Jane Doe</text>
</creator>
...
</item>
Translating values
All text based metadata values can be provided in multiple languages. If no language is specified, English is assumed.
To add a language, repeat the subelement including a lang attribute with the appropriate the two-digit BCP 47 language code.
Example
<item>
...
<title>
<text lang="en">Mona Lisa</text>
<text lang="fr">La Joconde</text>
<text lang="ja">モナ・リザ</text>
</title>
...
</item>
| Language | Language Code |
|---|---|
| Afrikaans | af |
| Albanian | sq |
| Arabic | ar |
| Azerbaijani | az |
| Basque | eu |
| Bengali | bn |
| Belarusian | be |
| Bulgarian | bg |
| Catalan | ca |
| Chinese (simplified) | zh-CN |
| Chinese (traditional) | zh-TW |
| Croatian | hr |
| Czech | cs |
| Danish | da |
| Dutch | nl |
| English | en |
| Esperanto | eo |
| Estonian | et |
| Filipino | tl |
| Finnish | fi |
| French | fr |
| Galician | gl |
| Georgian | ka |
| German | de |
| Greek | el |
| Gujarati | gu |
| Haitian Creole | ht |
| Hebrew | iw |
| Hindi | hi |
| Hungarian | hu |
| Icelandic | is |
| Indonesian | id |
| Irish | ga |
| Italian | it |
| Japanese | ja |
| Kannada | kn |
| Korean | ko |
| Latin | la |
| Latvian | lv |
| Lithuanian | lt |
| Macedonian | mk |
| Malay | ms |
| Maltese | mt |
| Norwegian | no |
| Persian | fa |
| Polish | pl |
| Portuguese | pt |
| Romanian | ro |
| Russian | ru |
| Serbian | sr |
| Slovak | sk |
| Slovenian | sl |
| Spanish | es |
| Swahili | sw |
| Swedish | sv |
| Tamil | ta |
| Telugu | te |
| Thai | th |
| Turkish | tr |
| Ukrainian | uk |
| Urdu | ur |
| Vietnamese | vi |
| Welsh | cy |
| Yiddish | yi |
Items with multiple digitizations
Subitems represent a digitization of part of a real world object, such as a page of a book, or a scan of one side of a document. You will need to submit metadata for both the top level item (the document) and for each subitem that represents an individual page or image of that document, for example.
Please follow these guidelines when structuring metadata for items with multiple digitizations:
- All subitems must be contained inside the
<sequence>element of the parent item - Each subitems with a given sequence must specify a unique "identifier"
- The order in which
<subitem>elements are added is the order in which they appear - Subitems cannot further nest additional
<sequence>or<subitem>elements
Check the complete XML example file structure to see an example of multiple digitizations.