How to Write a Catalog Data Dictionary
What to write for each catalog field before anyone checks, maps, or releases a value: name, definition, obligation, and owner.
- 01 Name the field
- 02 Define it
- 03 Mark obligation
- 04 Name the owner
A dictionary is the field list you are willing to stand behind
A catalog data dictionary is the list of fields this catalog uses, with enough written detail that a person and a check can apply the same meaning. A column that exists only in a database, or only in a slide, is not in the dictionary yet. If two teams describe the same field differently, you have two drafts, not a dictionary.
W3C Best Practice 1, in the Data on the Web Best Practices recommendation of 31 January 2017, says to provide metadata for both human users and computer applications. Best Practice 3 says to provide metadata that describes the schema and internal structure of a distribution. Both are about data on the web. A dictionary is how a catalog meets the spirit of those two lines for its own fields: a person can read the definition, and a validation check can read the obligation. The recommendation does not supply your fields, and it does not name a file format for the dictionary.
The metadata quality checklist uses this list. It should not keep a second, quieter list of required fields. If the check and the dictionary disagree, the release is checking a catalog you did not describe.
This diagram scrolls sideways on a narrow screen.
Write one entry per field
Each entry needs a stable field name, a definition, an obligation, the allowed form of the value, and an owner. The field name is the handle used by mappings and checks. The definition says what the value means. Obligation says whether an empty value may ship. The form says how a filled value is written. The owner is the permission to change the entry, not a job title on a slide.
Keep the definition to the meaning. “The name shown to customers” is a definition. “The name, and also the subtitle when marketing asks” is two fields wearing one name. Split them. A definition that needs a meeting to interpret will be interpreted differently at intake and at release.
Obligation is required, optional, or conditional. Conditional means you write the condition. “Required on the storefront, optional in the internal index” is a condition. “Required if we feel like it” is not. An empty optional field is allowed to stay empty. The quality checklist already says this. The dictionary is where that choice is recorded so the checklist has something to point at.
Allowed form points at a rule you already have. Dates and locale tags follow the normalization rules. A controlled value points at the taxonomy, not at a fresh list typed into the dictionary entry. If the entry invents a second list of allowed labels, the two lists will drift.
This table scrolls sideways on a narrow screen.
| Part | What it answers | If it is missing |
|---|---|---|
| Field name | Which field is this in checks and mappings? | People will match on the label and miss |
| Definition | What does a value mean? | Two teams will fill it differently |
| Obligation | May this value be empty? | Empty will be treated as an error and as a pass |
| Form | What does a filled value look like? | The same fact will be stored in several shapes |
| Owner | Who may change this entry? | The definition will change in a ticket and nowhere else |
Version the dictionary with the checks that use it
A check against last month’s fields is not a check against today’s. Put a version or a date on the dictionary, and cite that version from intake, from the quality check, and from the release log. When you add, rename, or retire a field, that change is itself a catalog change. It gets a log line. Records are not silently re-read against a definition they were never checked with.
Best Practice 7 of the same W3C recommendation says to assign and indicate a version number or date for each dataset. The subject is a dataset. Use it here only if you publish the dictionary as data. Even when you do not, the editorial method is the same: an undated dictionary cannot be cited by a release. Keep the previous text readable for as long as a log line cites it.
Renaming a field is a dictionary change and a mapping change together. The old name remains an alias until every stored mapping and check has moved, or it remains forever as a retired name that checks reject. Deleting the name on the same day you add the new one makes old files look unmapped when they were valid under the previous version.
Point mappings and rules at the entry
A field mapping may send a source column only to a field that has an entry. A validation rule may require a value only where the entry says required or conditional. If a rule needs a field the dictionary does not list, add the entry first, with a definition, and then write the rule. A rule that introduces the field is how required fields appear overnight.
Do not paste an outside element set in and call it done. A shared set is useful when you already mean what it means and you will keep that meaning. It is not a substitute for the commercial, rights, or asset fields you actually release. The quality checklist says the same about copying a public element set. This page is where the local entries are written.
What this page does not claim
Best Practice 1, Best Practice 3, and Best Practice 7 do not list the fields a commercial catalog must have. They do not require a particular dictionary format. Structural metadata in Best Practice 3 describes the schema of a distribution. A dictionary can serve that purpose when you publish one. The parts of an entry, the three obligations, and the rule that checks cite a version are this publication’s method.
When a dictionary entry should change
When is a clearer definition enough?
When the values already stored still match the new wording. Edit the definition, version the dictionary, and leave the field name in place.
When needed: A wording fix that does not move any record from valid to invalid.
When do you add a field instead of widening one?
When the new wording would make some current values mean two things. Add a field with its own entry. Do not stretch the old definition and hope the old values still fit.
When needed: A subtitle, a channel-specific name, or a second date that is not the first date.
When can a field be removed?
When no check, mapping, or released record still depends on it, or those dependencies are migrated in the same change. Retire the entry by version. Do not delete the name from history.
When needed: A field that is no longer collected and no longer displayed.