Write a data dictionary before another person reads your report

Solve interpretation before calculation

A colleague receives a table headed impressions and assumes the values occurred during October. You intended cumulative observations taken 24 hours after each post. Both people can calculate correctly and still describe different things. The missing artifact is an explicit definition, not a more elaborate chart.

A data dictionary travels beside the data and explains how to read it. W3C’s tabular model separates a cell’s text from its semantic value and provides concepts for rows, keys and metadata. Our small JSON dictionary is an original exercise format; it is not advertised as a complete implementation of that specification.

Define the row and its key first

State whether one row is a post, an observation of a post, a daily account total or an interaction. If the same post is measured at several ages, post_id alone is not unique across the full observation table. Choose an appropriate compound key or an observation identifier and explain it.

The example has one observation per fictional post, each at 24 hours. Its short post IDs are exercise identifiers, not actual LinkedIn URNs. The observed_at values use an explicit UTC timestamp. None of these rows is a real account measurement.

Write definitions that settle a disagreement

For each field, record type, allowed values, units and how absence is represented. For a number, explain the metric and collection clock. For a category, define unknown rather than forcing every record into organic. For a timestamp, say which event it marks and preserve the time-zone basis.

A declared category remains a declaration unless the source verifies it. The dictionary cannot establish that a post was organic or that the source collection is complete. Keep collection limitations beside the field definitions so later users do not mistake a tidy schema for validated evidence.

Check the three worked records

Download reporting-example.csv and data-dictionary.json together. The constructed records contain impressions 0, blank and 250. All have an entered age of 24 hours. The first and third declare organic distribution; the blank row declares unknown.

There are three records, two available impression values, one observed zero and one unavailable value. Two rows qualify for the declared organic-and-observed subset. Summing that subset gives 250. Calling all three rows complete would be wrong, even though treating the blank as zero happens to produce the same sum here.

Version a meaning change, not just a renamed column

Changing impressions from a 24-hour observation to a current lifetime total changes the metric’s time basis. Do not hide that behind an unchanged column label. Record the new dictionary version, affected files and whether older rows can actually be converted. Without historical observations, the old 24-hour values may be unrecoverable.

Likewise, replacing unknown distribution with organic changes eligibility. Preserve the earlier declaration and record the evidence for a correction. A version number alone is not enough: explain what changed and which previously computed results need review.

1. Give the dictionary a version and source scope.
2. Define the row unit, key and observation clock.
3. Describe types, units, categories and missing values.
4. Walk through a zero, an unavailable value and a normal record.
5. Record semantic changes before reusing a previous analysis.

Bind the file, meaning version and analysis together

A filename alone does not show which dictionary was used to interpret a table. Keep the actual data reference, dictionary edition, row unit and selection rule together in the handoff. An optional local file hash can identify equal bytes; it establishes neither provenance, permission nor factual correctness. Do not publish private raw files merely to make a reference look complete.

Three constructed additions: G1 binds F1 to D1 and the declared organic-and-observed selection; the original 0, blank and 250 still yield two available values and selected sum 250. G2 binds the same F1 to D2 even though D2 defines current lifetime rather than 24-hour values; the meaning check fails despite identical bytes. G3 has no explanation for blank values; the value remains unknown instead of becoming zero.

W3C recommends usable metadata, identifiable versions and change history. Our small handoff record is an original practice format, not a complete implementation of that recommendation or CSVW. It records file identity, meaning version, selection rule and actual recalculation as separate checks. A new dictionary cannot retroactively create unavailable historical observations.

The original three records and dictionary remain unchanged; G1–G3 are additional constructed handoff cases.

Test the handoff with a question

Ask a reviewer to identify the unavailable record, the observed zero and the exact subset used for a total without your verbal help. If they cannot, improve the definitions before publishing a chart. This is a suggested review task; no independent reviewer or reader outcome is claimed for this exercise.

A dictionary explains data; it does not grant permission to share it. Keep personal references private and publish only the minimal appropriate derivative. The related evidence-record guide connects a particular published claim to the exact files and operation used; that is a separate job from defining columns.