Skip to main content
DMS can convert metadata between CSV (spreadsheet) format and DMS JSON records in both directions. This makes it easy to bulk-import records prepared in a spreadsheet application, or to export your archive for use in Excel, Google Sheets, or data analysis tools.

​
CSV column format

The DMS CSV format uses a flat set of columns that map to the nested JSON structure. Multi-value fields use | (pipe) as a separator within a single cell. 
id,title,type,description,language,creator_name,creator_role,
date_created,date_event,subject,location_name,location_area,
location_latitude,location_longitude,format,rights_license,
rights_access_level,rights_holder,source_contributor,
source_collection,source_original_format,schema_version

​
Multi-value fields

Three columns accept multiple values separated by |:
ColumnExample valueMaps to
creator_nameMarie Consolée|Jean-Baptiste Mushimiyimanacreator[].name
creator_rolenarrator|interviewercreator[].role
subjectoral history|displacement|Congosubject[]
The creator_name and creator_role columns are positional: the first name is paired with the first role, the second name with the second role, and so on.

​
Example rows from batch.csv

batch.csv
id,title,type,description,language,creator_name,creator_role,date_created,date_event,subject,location_name,location_area,location_latitude,location_longitude,format,rights_license,rights_access_level,rights_holder,source_contributor,source_collection,source_original_format,schema_version
b3e7c8a1-4d5f-6e7a-8b9c-0d1e2f3a4b5c,Journey to Dzaleka: A Story of Hope,story,"An oral history account of a Congolese family's journey from Bukavu to Dzaleka Refugee Camp in 2015.",en,Marie Consolée|Jean-Baptiste Mushimiyimana,narrator|interviewer,2024-03-15,2015-08-22,oral history|displacement|Congo|journey|resilience,Dzaleka Refugee Camp,Community Center,-13.7833,33.9833,text/plain,CC-BY-NC-4.0,public,Marie Consolée,Dzaleka Digital Heritage Project,Oral Histories 2024,audio interview (transcribed),1.0.0
d7e8f9a0-b1c2-d3e4-f5a6-b7c8d9e0f1a2,Traditional Songs of the Great Lakes Region,audio,"Field recording of traditional songs performed by Burundian elder women.",rw,Espérance Ndayisaba|Grace Mutoni|Samuel Habimana,narrator|narrator|recorder,2024-04-08,2024-03-22,traditional music|songs|Burundi|cultural heritage|women,Dzaleka Refugee Camp,Community Center,-13.7833,33.9833,audio/mpeg,CC-BY-NC-4.0,community-only,Dzaleka Heritage Audio Archive,Dzaleka Heritage Audio Archive,Traditional Music Archive,live field recording,1.0.0

​
Importing CSV to JSON

dms convert csv2json batch.csv
This reads every row in batch.csv and writes a JSON array of DMS records.
By default the output file is named <stem>_converted.json. For a file named batch.csv the output will be batch_converted.json. Use --output to choose a different path:
dms convert csv2json batch.csv --output records/imported.json
If you pass a directory path as --output, each row is written as an individual file named <type>_<id[:8]>.json: 
dms convert csv2json batch.csv --output records/
Rows without an id value are assigned a new UUID automatically.

​
Exporting JSON to CSV

dms convert json2csv records/story_b3e7c8a1.json
Both a single JSON object and a JSON array of records are accepted. By default the output path is the same as the input with the extension changed to .csv:
json2csv defaults to <input-stem>.csv. For story_b3e7c8a1.json the output will be story_b3e7c8a1.csv. Override with --output:
dms convert json2csv records/story_b3e7c8a1.json --output exports/story.csv

​
Round-trip workflow

You can convert records back and forth between formats without data loss: 
# 1. Import a spreadsheet export to JSON
dms convert csv2json data.csv --output data.json

# 2. Edit records in data.json, then validate
dms validate data.json

# 3. Export back to CSV for sharing with non-technical collaborators
dms convert json2csv data.json --output data-export.csv
The CSV format flattens nested JSON fields. The coverage object (start_date, end_date, period) and the relation array have no corresponding CSV columns and will not survive a round-trip through CSV. If your records use these fields, work directly in JSON.