Agree what every intake field means before anyone builds the form. Use copy-ready specifications and failure tests to keep labels, permitted values and missing answers consistent.
One team reads “required date” as the day work must finish. Another treats it as the earliest acceptable visit. Both can enter a valid date while sending the request down the wrong path. A field name and a dropdown are not enough to settle the meaning.
This data dictionary template helps an operations owner define a form’s fields with the person configuring it and the people using its records. Copy the settings, field specification, value list and test record below into a shared document or spreadsheet. The complete resource is inline; there is no separate download or import file.
The example covers a small internal help-request form. It specifies the data, not an inventory system or the full approval and fulfillment process. All limits, roles and release gates are a proposed operating design to adapt locally—not a regulatory standard or a claim that a particular form builder enforces them.
Set the boundary of the dictionary
A data dictionary describes the meaning and properties of individually named data elements. The USGS data-dictionary guidance includes types, optionality, reference values, missing-data codes and validation rules, and recommends updating the dictionary when structures change. Those principles are useful for business forms as well as datasets.
Use one dictionary version for one defined form and its stored request record. A row describes a field, not one person’s submitted answer. A business glossary can explain “priority”; the dictionary must additionally explain which field stores it, what values are allowed and what a blank means.
DICTIONARY SETTINGS Dictionary ID / version: [Stable ID / revision] Form and record covered: [Name, system and exact scope] Excluded records or channels: [Explicit boundary] Business owner / backup: [Named people] Configurator / test reviewer: [Named people] Approval authority: [Role and current person] Source form/configuration reference: [Exact version reference] Validation stages: [Draft save / submission / later update] Local date/time convention: [Format and named time zone] Code-list convention: [Where codes and labels are maintained] Access and retention policy: [Applicable internal references] Planned effective cutoff: [Date, time and zone] Review trigger / next review: [Event triggers and date] Release state: [Working / In review / Approved / In use / Superseded] Open issue / owner / next action / due: [Or None] Approval and implementation evidence: [Pending until verified]
The business owner resolves meaning and allowed values. The configurator identifies what the implementation can actually enforce. The test reviewer checks the configured form and a saved/exported record. The approval authority accepts the agreed scope and remaining limitations. One person may perform several roles, but record which responsibility they performed.
Copy one specification for every field
Use the field key as stable text, separate from the label users see. Define a naming convention supported by your chosen system; do not assume a convention below is a universal platform requirement. If a system generates its own identifier, record that actual identifier alongside your business key.
FIELD SPECIFICATION — repeat for each field Dictionary version / form: [Match settings] Field key / system identifier: [Stable key / actual ID, or Pending build] Display label: [Plain-language label] Definition and purpose: [What the value means; what it is used for] Logical type: [Text / integer / decimal / date / timestamp / choice / etc.] Format / unit / length or precision: [Exact rule, or Not applicable] Entry source and editor: [Requester / named source / derived; who may change it] Required at: [Specific stage, condition, or Optional] Blank meaning: [Not supplied / not applicable / unknown; one explicit rule] Default: [Exact value and when applied, or None] Allowed values / code-list reference: [Exact values or bounded domain] Validation and cross-field rules: [Testable conditions, including stage] Failure handling: [Message, blocked action, correction owner] Consumer / downstream mapping: [Who uses it; actual destination if known] Example accepted / rejected value: [Synthetic examples and reasons] Sensitivity / access-policy reference: [Local classification decision] Business owner / reviewer: [Named people or inherited settings] Change reference / effective version: [Decision and applicable version] Implementation / test evidence: [Actual check references, or Pending]
Do not fill unknown implementation facts with a guess. “Pending build” is acceptable in a working specification, but not proof that a released form matches it. “Optional” also needs a blank rule: an absent quantity must not silently become zero, and an absent answer must not mean “no” unless that behavior was explicitly chosen.
Keep codes separate from display labels
For each choice list, copy this companion record. It lets the team change a user-facing label without silently changing the stored meaning.
VALUE LIST — one row per permitted code List ID / version | Stored code | Display label | Meaning Allowed for new entries from / until | Historical interpretation Owner | Approval reference | Implementation/test reference
Use “No end set” rather than inventing an expiry. Retiring a code should stop new use at the agreed cutoff without erasing what the code meant in earlier records. A code’s meaning must not be recycled for a different request type. If two systems use different codes, record an explicit mapping and its owner; similar labels are not mapping evidence.
Completed example: an internal help-request form
Fictional example: Northline Services wants one form for supply requests and meeting-room setup requests. This dictionary defines seven fields. It does not authorize stock release, reserve a room or promise a service deadline.
Settings: dictionary HELP-DD / 1, form HELP-INTAKE / 1, covering submitted help records only. Email requests and fulfillment records are excluded. Maya is business owner and approver; Jonah is backup; Luis configures the form; Priya tests it. A pilot cutoff is November 18, 2026 at 09:00 America/Chicago. Review is due December 18 and whenever a field, list, route or consumer changes. State remains Working until actual implementation evidence exists.
For all seven fields, the owner is Maya and reviewer Priya; access and retention follow the organization’s internal request-record policy. The consumer is the internal help coordinator. There are no external mappings in this pilot. Defaults are None; an automatic identifier or derived route is computed, not a preselected user answer. System IDs and implementation evidence are Pending build. All examples below are synthetic.
Field meanings, types and entry authority
| Key and label | Definition, type and format | Source and editor |
|---|---|---|
request_idRequest ID | Unique identifier of one accepted submission; text, 1–40 characters. It is not a count and must preserve leading zeros. | Assigned by the request system after acceptance; not requester-editable. |
site_codeService site | The site where help is requested; single choice from SITES/1. | Requester selects; coordinator owns any recorded correction. |
request_kindType of help | The kind of work requested, not its urgency; single choice from KINDS/1. | Requester selects; coordinator owns any recorded correction. |
unit_countNumber of supply units | Requested count of individual units, not packs or approved stock; integer 1–50 when applicable. | Requester enters for Supplies. It does not establish availability or release authority. |
needed_onRequested service date | Day the requester would like service; date, YYYY-MM-DD, interpreted as a local calendar date in America/Chicago. Not a guaranteed completion date. | Requester enters; coordinator confirms any later agreed service commitment elsewhere. |
request_noteRequest details | Instructions describing the need; text up to 500 characters after trimming surrounding spaces. | Requester enters; coordinator may record an attributed correction. |
route_codeReceiving queue | Initial receiving queue determined by site and request type; text from ROUTES/1. | Derived after valid selections; not requester-editable. This is routing, not approval. |
Required stages, blank rules and rejection behavior
Draft saves may be incomplete and must stay distinguishable from accepted submissions. Run the following checks at submission. A later correction must be attributed and checked against the rules applicable to that correction; it must not rewrite the original request’s history.
| Field | Rule and missing-data meaning | Failure and accepted example |
|---|---|---|
| request_id | Required on the accepted record, unique within the request system. Blank means acceptance is not confirmed. | Coordinator investigates a missing or duplicate ID before routing. Accepted text: 000184. |
| site_code | Required at submission. Only NTH or STH. Blank means no site selected. | Block submission: “Choose a service site.” Accepted: NTH. |
| request_kind | Required at submission. Only supplies or room_setup. Blank means no type selected. | Block submission: “Choose a type of help.” Accepted: supplies. |
| unit_count | Required only for supplies: a whole number from 1 through 50. For room_setup, it must be blank, meaning not applicable. Zero never means unknown. | Block submission: “Enter 1–50 individual supply units, or clear quantity for room setup.” Accepted: 6 for Supplies. |
| needed_on | Required. Valid calendar date no earlier than the local submission date. Blank means no requested date. Compare only on a new submission or an explicit change to this field. | Block submission: “Enter today or a later valid service date.” Accepted on Nov 18: 2026-11-20. Existing records do not become invalid just because time passes. |
| request_note | For room_setup, require 10–500 characters after trimming. For supplies, allow blank or 1–500 characters. Blank means no additional instructions, not approval. | Block submission: “Add room setup instructions, or shorten details to 500 characters.” Accepted: Arrange six chairs in a circle. |
| route_code | Required before routing. Derive from the exact valid pair below. Blank means unresolved; never default to the first queue. | Hold routing if no match or if altered. Luis investigates with Maya. Accepted: N-SUP for NTH + supplies. |
On a blocked submission, the requester corrects the identified input. A configuration failure belongs to Luis, with Maya deciding the interim operating route. The pilot review target is the same working day; an unresolved issue is escalated to Jonah before that day ends with an owner and next review time. This is a local target, not a product service guarantee.
Define the example lists and route rule
| List | Stored code → label and meaning |
|---|---|
| SITES/1 | NTH → North site; STH → South site. Both identify the place needing service. |
| KINDS/1 | supplies → Supplies, a request for individual consumable units; room_setup → Room setup, a request to arrange a meeting room. |
| ROUTES/1 | N-SUP → North supplies queue; N-ROOM → North room team; S-SUP → South supplies queue; S-ROOM → South room team. |
Every listed code is proposed for new entries from the pilot cutoff, with No end set. Maya owns all three lists; approval and implementation references remain Pending. These are example settings, not evidence that a live form has been approved.
Route rule: NTH + supplies → N-SUP; NTH + room_setup → N-ROOM; STH + supplies → S-SUP; STH + room_setup → S-ROOM. No other pair is permitted. Recalculate the route after an authorized change to either input; never keep an old route silently. A submitted request with ID 000184, NTH, supplies, 6, 2026-11-20 and a blank note should derive N-SUP.
Test meaning as well as field format
Copy a test record for every acceptance check. Record actual results only after testing the selected implementation; the expected outcomes below are not test-pass claims.
TEST RECORD Dictionary version / configuration version: [Exact references] Test ID / tester / timestamp: [Identity and actual execution time] Inputs / validation stage: [Synthetic record and action] Expected acceptance or block: [Rule and visible message] Expected saved value / route: [Exact result, or No accepted record] Actual result / saved-record evidence: [Pending until run] Pass / fail / issue owner / retest reference: [Actual outcome]
- Normal supply request: NTH, supplies, 6, valid future date, blank note. Expect acceptance, a unique text ID and N-SUP.
- Quantity boundaries: Supplies with 1 or 50 passes the quantity rule; blank, 0, −1, 1.5 or 51 blocks. Valid quantity alone does not make the whole submission valid.
- Condition change: change Supplies with quantity 6 to Room setup. Expect a quantity error until the requester clears 6 and supplies a note of at least 10 trimmed characters. Do not silently discard their answer.
- Whitespace: ten spaces are not ten characters of instructions after trimming. Expect a blocked Room setup submission.
- Dates: reject an impossible date such as 2026-02-30 and a date before the submission day. On November 18, test November 18 as an accepted boundary and November 17 as rejected. Check the configured local day near midnight.
- Code and identity preservation: an import or export must not turn 000184 into 184. An unknown site code must not produce a receiving queue. Check all four valid route pairs.
- Changed definitions: if a new type is proposed, keep it unavailable for new submissions until its fields, route and tests are agreed. Do not repurpose
suppliesto mean something new in historical records.
Approve the dictionary against the actual form
- Inspect the current form and stored record. List visible, hidden and derived fields. Include exports or receiving queues that interpret them; a screen-only review can miss stored codes.
- Resolve semantic disagreements. Ask the receiving team what it does with each field. Split two different meanings into separate fields rather than allowing one ambiguous “date” or “status.”
- Check implementation feasibility. Luis records which validations are enforced and which need a reviewer. If a required block cannot be enforced, Maya must accept a clearly defined alternative before release—not leave the dictionary pretending it is automatic.
- Run and retain tests. Priya compares messages, saved values and derived routes with the approved specification. Record failures and retests, including blank and conditional cases.
- Authorize use. Maya approves the exact dictionary and configuration references after blocking issues are resolved. Record the actual effective time and evidence; keep the prior version for interpretation of older records under the applicable records policy.
Keep the wider process in a workflow requirements document. It defines who receives work and what decisions follow. The dictionary defines the data those steps rely on. Neither replaces the other.
Where Workhint fits
A shared dictionary can be enough while a team agrees on its fields. Workhint’s Workflow Engine describes configuring requests, assignments and role-based approvals, including required information before work advances. That is relevant when incomplete intake must reach a correction owner rather than move forward unchecked.
The Workhint workflow automation software solution describes custom forms, conditions, routing, roles and approvals. Bring the agreed dictionary to configuration discussions, then demonstrate the actual field rules and failure paths in the chosen setup. These pages do not establish native dictionary import, automatic synchronization, every validation in this example, or a dedicated data-catalog feature.
Frequently asked questions
Is a data dictionary the same as a form template?
No. A form template collects answers. The dictionary explains what its fields mean, which answers are valid, who supplies them and how missing values or changes are handled. One form may have several versions of its dictionary over time.
Should every optional field allow a blank?
Only under a stated rule. Specify whether blank means not supplied, not applicable or unknown. If those meanings affect decisions differently, use an explicit separate value or field instead of collapsing them into the same empty cell.
Can the dictionary enforce validation?
Not by itself. It is a specification. The selected form, receiving system and review process must implement the rules, and actual tests must show what happens. Record unsupported behavior rather than assuming a written rule is active.
When should a field definition change?
When the meaning, type, source, permitted values, requirement, calculation or consumer changes. Record the decision, effective version and effect on existing records. A cosmetic label change still needs a check that stored codes and downstream interpretation remain correct.
Start with one form and the fields that drive its next decision. The useful result is not a longer spreadsheet: it is an agreement that a requester, configurator and receiving team can all test against the same saved record.

Leave a Reply