How to write a data dictionary for AI licensing

What a data dictionary should answer

Imagine a prospective reviewer sees a field called "closed". Does it mean a problem was solved, an account ended or a ticket was merged? The data dictionary should answer that question without requiring a tour of your internal systems.

The W3C metadata vocabulary for tabular data includes descriptions of columns, data types, missing-value markers and required values. It is a technical reference for expressing structure, not an AI buyer's mandatory template. Use the ideas to make a plain document understandable before deciding whether a machine-readable version is useful.

Keep the task narrow. A dictionary describes the fields; a quality review checks what is actually present. Neither document establishes permission to share the collection. Start with the licensing readiness guide if ownership and restrictions are still unclear.

Write one useful entry for each proposed field

For every field you are considering, record:

• A neutral field name and a plain-English definition.
• The kind of value, such as text, a date or a category.
• The unit or date convention, where relevant.
• Permitted categories and what each category means.
• Whether the field can be missing and what a blank means.
• How the value is created: entered by a person, imported or calculated.
• Any known change in meaning over the period covered.

Do not include a field merely because it exists in the source system. Ask what question it helps answer in the proposed review. Keep excluded or sensitive fields out of the shared outline. Even a schema can reveal something confidential about a product or customer workflow, so have the outline checked before sharing it.

An invented entry for a resolution field

Here is an illustrative dictionary entry, made up for this article. It is not a description of a real company's records.

Field: resolution_category. Meaning: the support team's final administrative category when a case closes. Type: category. Possible values: configuration_change, product_fix, duplicate, unresolved. Missing value: no category recorded. Created by: a team member choosing an option at closure. Limitation: the category is not independent confirmation that the customer tested the resolution.

The limitation matters as much as the label. It tells the reader not to interpret every closed case as a successful outcome. If your real system has changed categories, describe that change rather than forcing old and new labels into an apparently consistent history.

For another field, such as elapsed_time, explain whether the measure means clock time or working time, which events start and stop it, and whether pauses are included. A number without that context leaves the reviewer guessing.

Explain blanks and relationships

Do not use a single label for every absence unless that is genuinely how the system works. "Not recorded", "not applicable" and "removed from this extract" describe different situations. Record uncertainty explicitly when nobody can reliably explain a historical value.

Describe how records relate without exposing identifiers. For example, say that one case can have several status changes and one final administrative category. Explain whether the proposed collection would preserve that relationship. If the link has been removed, say what the reader can no longer follow.

An illustrative mistake is describing each status-change row as a separate resolved case. A dictionary should prevent that interpretation by defining what a row represents. You can demonstrate the relationship with fictional labels; there is no need to paste a live case or account reference into an enquiry.

Give the dictionary a version and an owner

The W3C's Data on the Web recommendations cover provenance and version information alongside metadata. Applied here, that means explaining where a collection came from and which description matches it. It does not mean putting private business data on the public web.

Give your working dictionary a date, version label and internal owner. Record the source system in non-confidential terms, the period described, any transformations you know about and unresolved questions. When definitions change, keep a short change note so a reviewer can see which explanation was used for an earlier discussion.

Do not confuse a maintained document with a verified dataset. Mark an untested definition as needing confirmation. If nobody has checked whether the exported values follow the dictionary, avoid describing them as validated.

Test the explanation before sharing it

Ask a colleague who does not use the system every day to interpret the invented example. Can they explain what one record represents? Can they tell a measured outcome from an administrative label? Note the questions they ask and improve the definitions.

Next, have the relevant owner check that the dictionary does not expose confidential field names, customer-specific workflows or credentials. Keep operational access details in your own systems. Do not attach a real export as an appendix to make the document more convincing.

For an initial Fairlode review, a short description of record types, formats and known limitations is enough to begin. A full dictionary may be useful later if a named recipient has a specific requirement and a sharing process has been agreed. Preparation should follow a credible question, not become a documentation project with no decision at the end.