CollectionBuilder
CollectionBuilder Documentation has moved!
Please visit:
https://collectionbuilder.github.io/cb-docs/
Content on this page is out of date.
Metadata
CollectionBuilder has some metadata standards and formats that you’ll need to follow in order for your site to work correctly. Follow the steps below to get your metadata ready.
- Metadata Template
- Required Fields
- Fields Required for Visualizations
- Recommended Fields
- Formatting Your Spreadsheet
- Uploading Your Metadata
Before You Start: To prevent formatting and encoding errors that can result from using Microsoft Excel, we recommend editing your metadata in Google Sheets. If your data will require a good amount of wrangling to get it into CollectionBuilder’s format, we suggest you use OpenRefine, a platform that facilitates large scale data cleaning and transformation.
1. Metadata Template
CollectionBuilder can accomodate any metadata field you dream up (well, within reason…)
A few fields, nevertheless, are required for the tool to work, and others are required if you would like certain visualizations to work. We’ve created metadata templates that contain all the required, visualization-dependent, and recommended fields.
If you’d like a model for your metadata, take a look at your type’s metadata template by clicking on the appropriate button to the right. The templates are contained in Google Sheets for easy re-use (just “Make a Copy” via the File menu to get started).
For a more detailed description of how each format is defined and mapped, see the CollectionBuilder Data Dictionary.
2. Required Fields
Without values in the fields below, CollectionBuilder will not work properly.
- objectid:
- This is the field that CollectionBuilder uses to identify each object. This should be a unique string, all lowercase with no spaces or special characters as it will be used to form the item’s URL. Underscores (
_) and dashes (-) are okay; slashes (/) should NOT be used in this field. - Example value:
coll002
- This is the field that CollectionBuilder uses to identify each object. This should be a unique string, all lowercase with no spaces or special characters as it will be used to form the item’s URL. Underscores (
- title:
- The title field is used to indicate the name of an item. This should be a short, descriptive set of words that identify the item. Each item may only have one title.
- Example value:
Haystack Rock
- format:
- This field indicates the item’s media type. Since CollectionBuilder uses logic based on
formatto display objects, this is the most important field to ensure the interactive visualizations function correctly. If there are errors or anomalies, some pages will not work. The input for this field should be structured according to MIME type standards, consisting of a type and a subtype concatenated with a slash (/) between them.- Image:
image/jpeg - Document:
application/pdf - Audio:
audio/mp3 - Video:
video/mp4
- Image:
- This field indicates the item’s media type. Since CollectionBuilder uses logic based on
Required Fields for YouTube Objects
- youtubeid (Only required if your collection contains YouTube videos):
- This is the unique string assigned to a video when it is uploaded to YouTube. An easy way to find this is to look at the url for your YouTube video. The ID will be the string attached to the end of this url: https://www.youtube.com/watch?v=
- Example value:
sHhk1eAgopU
Required Fields for GH and SA
- filename:
- This is the digital object’s filename, including the name itself as well as the object’s file extension. Each filename property should have a single value and end with a file extension.
- The filename should be a lowercase unique string with no spaces or special characters. Underscores (
_) are okay; slashes (/) and hyphens (-) should NOT be used in this field. - Records for YouTube objects will not usually have a value in this field.
- Common Extension Options:
.jpg,.pdf,.mp3 - Example value:
letter001.pdf
Required Fields for CONTENTdm
- cdmid (for CONTENTdm skin):
- This is the unique identification number assigned to the item by CONTENTdm (the field titled “CONTENTdm number” in your exported metadata). For convenience, we generally make this correspond with the number in the item’s objectid (ex. objectid:
coll002, cdmid:2), but this correspondence is not necessary for CollectionBuilder to work. - Example value:
142
- This is the unique identification number assigned to the item by CONTENTdm (the field titled “CONTENTdm number” in your exported metadata). For convenience, we generally make this correspond with the number in the item’s objectid (ex. objectid:
At this time, CONTENTdm’s compound objects are not supported in CollectionBuilder. If you have a compound object, link to it as a complete pdf.
3. Fields Required for Visualizations
CollectionBuilder uses these fields to generate contextual visualizations, including a map, timeline, and word clouds reflecting the frequency of subjects and locations in a collection.
| Page | Required Fields |
|---|---|
| Map | latitude & longitude |
| Timeline | date (yyyy at minimum) |
| Subjects | subject |
| Location | location |
- latitude:
- A geographic coordinate specifying the north-south position of an item. See the Map section for more information.
- Example value:
46.731643
- longitude:
- A geographic coordinate specifying the east-west position of an item. See the Map section for more information.
- Example value:
-117.165625
- date:
- This field indicates a point in time associated with the item. This
datefield will be used for sorting and displaying on a timeline, so may often be an estimated / approximate date, rather than one more precisely formatted to archival description standards. We suggest adding more complex descriptions of date (date ranges, uncertainties, etc) in a separate field such as “date_created”. - Dates should be represented in the format
yyyy-mm-dd, which will enable our various timeline visualizations. See the Timeline section for more details. - For less exact dates,
yyyy-mmoryyyymay be used. - Example value:
1997-07-16,1997-07,1997 - (Dates in a
mm/dd/yyyyformat will also work)
- This field indicates a point in time associated with the item. This
- subject:
- The subject field contains topic(s) related to the item.
- This field allows for multiple subjects to be input for a single record. Each should be separated with a semicolon (
;). - See the Subjects section for more information.
- Example value:
Dogs; Cats; Zebras
Note: This field needs to be named ‘subject’ (not ‘subjects’) for many default features in CollectionBuilder to work. Data in this field will create the word cloud that allows users to visualize the frequency of subjects used within the collection.
- location:
- This field designates a geographic location(s) to which the item is tied. Much like the subject field, this field will build a tag cloud of the most used locations in your collection. See the Locations section for more information. Be sure to separate multiple location entries for a single record with a semicolon (
;). - Example value:
Pullman, Washington; Moscow, Idaho
- This field designates a geographic location(s) to which the item is tied. Much like the subject field, this field will build a tag cloud of the most used locations in your collection. See the Locations section for more information. Be sure to separate multiple location entries for a single record with a semicolon (
If your metadata does not have map coordinates, but you would like to experience CollectionBuilder’s map visualization, we’ve created a demo list of latitudes and longitudes that you can add to your data just for practice.
4. Optional Fields
The rest of the fields in the CollectionBuilder metadata template are not required for CollectionBuilder or its visualizations to work, but their use is encouraged to ensure a richly informative collection. These remaining fields are listed below, along with their respective definitions and examples.
CollectionBuilder can accommodate any field you include in your metadata once you customize your site. For example, you can display any field on item pages or on the Browse page. See the Metadata and Browse customization sections for more information.
- creator:
- The creator property designates an entity primarily responsible for making the resource. Multiple creators may be input, as long as each is separated by a semicolon (
;). - Example value:
Smith, JohnorSmith, John; Doe, Jane
- The creator property designates an entity primarily responsible for making the resource. Multiple creators may be input, as long as each is separated by a semicolon (
- description:
- The description should be a brief account of the object. Each object should only have one description.
- Example value:
Postcard of the Memorial Gymnasium on the University of Idaho campus in Moscow, Idaho.
- source:
- The source field designates a related source collection or resource from which the object is derived. This field is especially relevant for digitized archival collections. In such a situation, the name of the physical archival collection would be the input for this field. The input should be expressed as the collection name followed by a comma, then followed by the holding library.
- Example value:
PG 5, University of Idaho Library Special Collections and Archives
- identifier:
- The identifier field is used to preserve the unique identifier assigned to the object by the object’s (usually physical) source collection.
- Example value:
ARG-02-16-1993
- type:
- An object’s type distinguishes between types of image, sound, text, etc. using a one- or two-value input. At minimum, the input should contain a value chosen from the DCMI Type Vocabulary. If using a second value, the second value does not need to relate to a controlled vocabulary, but should give further specification of the object type. The two values in a pair should be separated by a semicolon (
;). See examples below. - Example value:
Image;StillImage,Image;MovingImage,Text,Sound
- An object’s type distinguishes between types of image, sound, text, etc. using a one- or two-value input. At minimum, the input should contain a value chosen from the DCMI Type Vocabulary. If using a second value, the second value does not need to relate to a controlled vocabulary, but should give further specification of the object type. The two values in a pair should be separated by a semicolon (
- language:
- This field indicates the language associated with the object. Recommended best practice is to use a controlled vocabulary such as the ISO 639-2 Codes for the Representation of Names and Languages to designate language tags.
- Example value:
en,fr,de
- rights:
- The rights field should include a free-text rights statement describing information about rights held in and over the object.
- Example value:
Educational use includes non-commercial use of text and images in materials for teaching and research purposes. Digital reproduction rights granted by the University of Idaho Library. For other uses beyond free use, please contact University of Idaho Library Special Collections and Archives Department.
- rightsstatement:
- This field is a standardized rights statement, designated in the form of a URI. It should be presented as a creativecommons.org URI or a rightsstatements.org URI.
- Example value:
http://rightsstatements.org/vocab/NoC-US/1.0/
5. Formatting Your Metadata
Make sure you’re following the guidelines below, otherwise CollectionBuilder may not work.
- Field Names Should Be Lowercase and Not Contain Special Characters
- Before you upload your metadata to CollectionBuilder, it is best practice to make all field names lowercase, since CollectionBuilder expects default fields to be lowercase. Preferably field names should not contain hyphens (
-), spaces (/,\), or special characters (&, etc.)–these won’t necessarily break things, but might cause issues when fields are passed through javascript code!
- Before you upload your metadata to CollectionBuilder, it is best practice to make all field names lowercase, since CollectionBuilder expects default fields to be lowercase. Preferably field names should not contain hyphens (
- Use a Semicolon When You Have Multiple Values
- Use a semicolon (
;) to separate values in multi-valued fields.
- Use a semicolon (
- No Special Characters in ID values
- When creating objectids and filenames do not use spaces (
/,\), and special characters (&). Since these values will be used in URLs, they should be web safe characters.
- When creating objectids and filenames do not use spaces (
Tip: In Visual Studio Code, there’s an easy way to make your fields lowercase:
- Highlight the first row of your CSV (the row containing field names)
- Click the ‘Command Palette’ option in the View menu
- Start typing ‘Transform to lowercase’–the option will appear!
6. Uploading Your Metadata
Note: CSV metadata should be in UTF-8 encoding. CSVs downloaded from Google Sheets or exported from OpenRefine will have the correct encoding. However, Excel does not handle UTF-8 correctly, and may cause issues. The encoding “UTF-8 with BOM” (created by Excel save as CSV) will not work!
- Get your metadata ready for upload:
- Once you’ve finished creating your metadata in Google Sheets (or other software), click “File” and select “Download as Comma-separated values.”
- Locate the metadata CSV you’ve just downloaded on your computer.
- Without opening it, name this file using all lowercase letters, no spaces, and no hyphens.
- Example filenames:
idahowater.csv,hjccc_dev.csv
- Upload your metadata:
- Navigate to the _data directory on the GitHub.com repository.
- Click the “Upload Files” button at the top of the page.
- Open your File Explorer (PC) or Finder (Mac) and locate the CSV you just downloaded and renamed (it’s probably in your “Downloads” folder).
- Drag the file onto the web page.
- Write a short commit message and then click the green “Commit changes” button at the bottom of the page.
- Locate the CSV you just downloaded and renamed (it’s probably in your “Downloads” folder) in your File Explorer / Finder
- Copy (or drag and drop) the metadata file into your CollectionBuilder project repository’s
_datadirectory (your repository is probably in your Documents > GitHub folder). - Commit the new metadata using Git or GitHub Desktop, and push your changes to the repository.
« Set Up Git Back to Top Config File »