Privacy and preparation
Data dictionary template for an exported dataset
By SourceX Editorial · Updated
Short answer
A data dictionary template for an exported dataset gives every field a row: its exported name, source label, type, plain-language meaning, a synthetic example, what blanks mean, transformations applied and privacy treatment. Write it from the export files rather than the source system, because exports rename, flatten, split and drop fields along the way.
Key takeaways
- Document each field as exported, not as it appears in the source system's admin screens.
- Give every column a type, a meaning, null behavior, transformations and privacy treatment.
- Use synthetic examples only; real values can identify customers or staff.
- Record export quirks, such as split files and long identifiers that spreadsheets can corrupt.
What a data dictionary does for an exported dataset#
A data dictionary for an exported dataset defines every column in every file: what it means, what type it holds, how blanks should be read, what changed during preparation and how personal details were treated. It answers the questions a reviewer would otherwise send back by email, one field at a time.
The dictionary sits beside two other documents. A dataset card describes the dataset as a whole, including its purpose, sources, time span and limits, and a provenance record explains where the data came from and under what rights. The dictionary is the field-level layer underneath both.
Write it from the export, not from the source system's admin screens. Exports rename fields, flatten nested values, split large tables into several files and leave out anything the export tool does not support, so the admin view of a field can mislead.
The template: columns to include#
The data dictionary template below uses one row per field. Keep it as a spreadsheet with one sheet per exported table or file, plus a sheet for removed fields and a change log.
| Column | What to write | Illustrative entry |
|---|---|---|
| Table or file | The exported file the field appears in | tickets.csv |
| Field name | The column header exactly as exported | requester_id |
| Source field | The label users saw in the system | Requester |
| Type and format | Data type, format, unit and time zone | Text, opaque token |
| Description | Business meaning in one or two plain sentences | Person who opened the ticket, replaced by a stable token |
| Illustrative example | A made-up value in the right format, never a real one | R-7Q2K |
| Nulls and blanks | What an empty value means | Blank when an automation created the ticket |
| Allowed values | Picklist values or valid ranges | Not applicable |
| Transformations | Any change made during export or preparation | Original email address replaced by token |
| Privacy treatment | Kept, removed, tokenized, generalized or redacted in text | Tokenized |
| Relationships | Keys that join to other files | Joins to users.csv on requester_id |
- 01Your work records
- 02Personal details removed
- 03You approve the release
- 04Licensed to AI developers
A filled example for a support ticket export#
A filled example shows how the columns work together. The rows below describe part of a fictional support ticket export after preparation; a real dictionary would cover every field in every file.
| Field | Type | Description | Privacy treatment |
|---|---|---|---|
| ticket_id | Integer | Unique ticket number from the help desk | Kept |
| created_at | Timestamp, UTC | When the ticket was opened | Kept |
| requester_id | Text token | Stable stand-in for the person who opened the ticket | Tokenized |
| organization_tier | Text | Customer plan level when the ticket was created | Generalized from the account name |
| subject | Text | Ticket subject line | Personal details removed |
| resolution_code | Text, picklist | How the ticket was closed | Kept |
| linked_issue_key | Text | Engineering issue linked to the ticket | Kept |
| agent_notes | Text | Internal notes between support agents | Names and contact details redacted |
Rules for writing definitions people can use#
Good definitions describe business meaning, not storage. Integer tells a reviewer almost nothing; number of the warehouse that shipped the order, as assigned in the WMS, tells them what the field is for and where it came from.
Write for two readers at once: an engineer loading the files and a privacy reviewer checking what each column could reveal. A definition that satisfies both usually names the business event, the person or process that recorded it, and any change made before export.
- State units, currency handling and time zones explicitly.
- Say who or what fills the field: a customer, an agent, a technician or an automation.
- Explain what blank means, and whether blank and zero differ.
- Record when a field's meaning changed, for example after a system migration or a picklist cleanup.
- List picklist values in full where they matter, and flag retired values that appear only in older records.
- Never paste real values as examples; write synthetic ones in the correct format.
- Note quality issues openly, such as a field that agents filled in inconsistently.
Export quirks the dictionary must capture#
Export quirks are where a dictionary earns its keep, because they explain the differences between what the system showed and what the files contain. Each quirk deserves a note on the fields it affects.
Some quirks come from the vendor's export format. Salesforce's Data Export Service delivers zip files of CSVs and splits large exports into multiple files, so one object can span several files. Google Vault exports Drive documents as Office files with metadata in separate XML or CSV files, so the dictionary needs to describe those metadata files as well.
Others come from the tools people use to open exports. Oracle's NetSuite documentation warns that opening a CSV export directly in Excel loses precision on numbers longer than 16 digits and recommends importing such columns as text. Mark identifier columns as text in the dictionary and say why, so nobody reopens a file and silently corrupts its keys.
Illustrative: a software company documents its Jira and Zendesk export#
Illustrative: a fictional B2B software company exports Zendesk tickets and the Jira issues linked to them for a licensing review. The first export arrives with dozens of columns named after internal custom field IDs that nobody outside the engineering team can read.
The CTO's team maps every custom field ID to its label, writes plain-language definitions and adds a privacy treatment column agreed with the privacy lead: requester emails become tokens, customer company names are generalized to plan tier, and agent notes go through redaction. A removed-fields sheet lists the satisfaction survey comments and attachment links that were dropped, with the reason for each.
When the reviewer asks why the resolution field is blank for older tickets, the change log already answers it: the picklist was introduced partway through the history and earlier tickets were never backfilled.
Keeping the dictionary in Excel and in machine-readable form#
A spreadsheet is the right working format for a data dictionary because reviewers, counsel and engineers can all read it. Version it with the dataset so the dictionary version and the dataset version always match, and keep the change log on its own sheet.
For delivery, a machine-readable copy helps the recipient load the data correctly. A CSV or JSON version of the dictionary is enough for most recipients, and MLCommons' Croissant format, built on the schema.org Dataset vocabulary, is an option when one is requested.
In the SourceX five-step transaction, the dictionary is produced during Preparation and travels with the dataset at Delivery. Its privacy treatment column feeds the privacy record in the SourceX Evidence Packet, so each field's handling can be traced from the source system to the delivered file.
Frequently asked questions
What is the difference between a data dictionary and a dataset card?
A dataset card describes the whole dataset: purpose, sources, time span, composition and known limits. A data dictionary describes each field inside it. Recipients usually want both, and the card should point to the dictionary for field-level detail.
Should a data dictionary include real sample values?
No. Use synthetic examples in the correct format. Real values, even ones that look harmless, can identify customers or employees, and the dictionary often travels further than the data itself, for example into review emails and internal wikis.
How should free-text fields be documented?
Describe who wrote the text and for what purpose, its typical content in general terms, its language, and exactly what redaction or removal was applied. Note known residual risks, such as names inside email signatures or quoted reply chains, so reviewers know what to check.
Do removed fields belong in the dictionary?
Yes, on a separate sheet. Listing each removed field with the reason it was dropped shows the reviewer the omission was deliberate and helps counsel confirm sensitive fields were handled. It also stops someone from adding them back in a later export.
Who should own the data dictionary?
The system owner or data lead usually drafts it, a privacy reviewer completes or checks the privacy treatment column, and one named person keeps versions aligned with dataset releases. Shared ownership without a single editor tends to produce conflicting copies.
Sources
- Salesforce's Data Export Service delivers exports as zip files of CSVs, split into multiple files when large. Source
- Google Vault converts Drive files such as Docs, Sheets and Slides to DOCX, XLSX and PPTX on export, with metadata in XML or CSV files. Source
- Oracle's NetSuite help warns that opening a NetSuite CSV export directly in Excel loses precision on numbers longer than 16 digits and recommends importing the column as text. Source
- MLCommons' Croissant format is a metadata standard for machine-learning datasets built on schema.org's Dataset vocabulary. Source
Related resources
- IndustryBPO & contact centers data
- QuestionDo AI labs buy medical data?
- QuestionDo AI labs buy video of people working?
- InsightHow do I de-identify customer support transcripts for AI training?
- InsightHow do I de-identify IT service tickets for AI training?
- InsightPurpose limitation: can records collected for one purpose be licensed for AI?
See if your company qualifies
A short company assessment. No data uploads are needed.