Working with a data dictionary

Edit online

The data dictionary provides a semantic view of all variables used within your application. As you approve or adjust AI‑generated values, it automatically adds new entries.

By mapping application variables to their corresponding interpretations, the data dictionary serves as a centralized reference that includes each variable’s name, a concise description, and a detailed explanation. This functionality enables you to work with an existing data dictionary or introduce additional variables whenever required.

When you provide a prompt to Bob that requires a COBOL or PL/I program to be read, the following options are available. These options allow the scan_program tool to analyze the file to extract variable information and enable data dictionary capabilities:
  • Yes, scan the program to enable data dictionary features.
  • No, explain the program without data dictionary context.
  • No, and don’t ask about scanning this application in the future.
Note: Initiate the data dictionary creation by using Z Code mode.

Tools

To know about the tools used by IBM® Bob Premium Package for Z to work with data dictionary, see Using workflows, skills, tools, and commands.

Creating the data dictionary

To create the data dictionary, select Yes, scan the program to enable data dictionary features. After you make this selection, the system proceeds with the following steps:
  1. Using existing heuristics and new heuristics, the data dictionary tools that identifies relevant variables for description generation.
  2. The generated AI descriptions are presented for your validation.
  3. Approved descriptions are saved as a .json file.
  4. The explain tool consumes the validated data dictionary as part of its contextual input.
  5. The JSON file is stored in bobz folder in the current workspace.

Update data dictionary

To add new variables, perform the following steps:
  1. In IBM Bob Premium Package for Z, select the Z Code mode.
  2. Select the prompt or type explain <filename.cbl> in the chat.
  3. Bob displays the following options:
    • Use existing data dictionary as-is: This option is displayed only if the data dictionary file (DD.json) exists.
    • Synchronize data dictionary from server: This option is displayed only when the Z Understand server is configured and there are possible updates from the server.
    • Update data dictionary with new variables: This option is displayed irrespective of whether the DD.json exists.
  4. To add new variables, select Update data dictionary with new variables option. The variable analysis workflow is initiated and includes the following steps:
    • Step 1: Select the top 15 business variables from candidate list
    • Step 2: Expand selected variable names
    • Step 3: Save to data dictionary by using edit_data_dictionary tool
  5. The DD.json file opens in the editor for verification. Once the verification is complete, select I’m done editing.
  6. Based on the selection, IBM Bob Premium Package for Z generates a detailed explanation incorporating the data dictionary metadata of the COBOL program.

Working with a business glossary

A business glossary is a .json file containing a set of terms and definitions that help explain business concepts that relate to the application. You must add the .json file into the bobz folder. Here is an example of the business glossary .json file format: businessglossary.json.


[
  {
    "glossary_name": "FINANCE",
    "fileName": "businessglossary.json",
    "upload_date": "11/19/2025",
    "glossary_path": "",
    "glossary_elements": [
      {
        "term": "Account Number",
        "description": "Identifier to uniquely identify a customers back account"
      },
      {
        "term": "Interest Rate",
        "description": "The interest rate offered to customer for their savings account balance"
      }
    ]
  }
]
The business glossary displays the following information:
  • glossary_name (required): A glossary is a set of terms that are related to a specific subject in the application. An application contains multiple glossaries. For example, an application might include a Finance glossary and an Insurance glossary.
  • term (required): A term represents a specific concept in the glossary. For example, the Finance glossary includes Account number and Interest rate, while the Insurance glossary includes Policy number and Customer number. A term appears in more than one glossary.

  • description (required): Each term includes a description.

    For example:
    • Account number: Identifier to uniquely identify a customer’s bank account.
    • Interest rate: The interest rate that is offered to customers for their savings account balance.

Working with naming conventions

Naming conventions are acronyms that replace full names in code variables. Specifying naming conventions improves AI accuracy. A naming conventions file is in the .json format. You must add the .json file into the bobz folder. Here is an example of the naming conventions .json file format: namingconventions.json.


[
  {
    "glossary_name": "FINANCE",
    "fileName": "businessglossary.json",
    "upload_date": "11/19/2025",
    "glossary_path": "",
    "glossary_elements": [
      {
        "term": "Account Number",
        "description": "Identifier to uniquely identify a customers back account"
      },
      {
        "term": "Interest Rate",
        "description": "The interest rate offered to customer for their savings account balance"
      }
    ]
  }
]
The naming conventions tool displays the following information:

  • acronym (required): The acronym replacing the full name in a code variable.

    Example: CR can represent Customer Report.

  • fullName (required): The full name corresponds to the acronym.

    Example: Customer Report is the full name for CR.

  • description (required): A description of the acronym.

    Example: Customer details saved in the profile for CR.

  • patternMatch (required): The position of the acronym in the variable name, which is specified by using regular expressions.

    Example patterns apply to the acronym CR.

  • scope (required): Specifies what the acronym applies to. For this release, you can enter any character string. The acronym is searched within the application’s code variables. More specific scope values will be introduced in a future release.

Data dictionary workflow

The process of creating a data dictionary is now available as a streamlined workflow. To begin, select Start Workflow from the Bob panel. In the workspace, choose Generate data dictionary, then select a program in the workspace through Browse Files, and click Continue with Selection.

Once initiated, the workflow automatically identifies variables and generates descriptions for the most relevant business variables. After reviewing and verifying the generated data dictionary entries, select I’m done editing to complete the process. The DD.json file is then successfully generated and saved.