XML User Dictionary

XML User Dictionary

Custom User-Dictionaries

Central registries with locally defined data items are expected to create and provide user dictionaries to vendors by October 1st prior to the effective date of the upcoming NAACCR version.


A user dictionary is an XML file that defines key metadata about NAACCR data items as they relate to a NAACCR XML data exchange file, their valid XML parent elements, and processing rules. The user dictionaries should include all current registry-specific data items, and any new items planned for implementation with the latest published NAACCR version. This will help vendors prepare customized files and software applications and reduce the chance of delay for deployment of updated software.


All central registries should do the following:

  1. Determine if a user dictionary needs to be created or updated (refer to FAQ)
    1. If your registry determines it does not need a user dictionary, you should still use the form on the XML Dictionary Submission Clearinghouse(MyNAACCR Login Required) to communicate this information (e.g. [Your Registry] is not creating a user dictionary)
  2. Review existing registry-specific data items to determine if their reporting needs have changed and remove items that are no longer needed.
  3. Identify and define new registry-specific data items for inclusion.
  4. Download and fill out the Data Dictionary Details Template with details of all registry-specific data items.
  5. Use the Data Dictionary Details Template and a recommended software tool  to create an XML User Dictionary with all registry-specific data items
  6. Validate the user dictionary (refer to FAQ)
  7. Upload the completed Data Dictionary Details Template and XML User Dictionary to the XML Dictionary Submission Clearinghouse(MyNAACCR Login Required).


Important Links

Data Dictionary Details Template

XML Dictionary Submission Clearinghouse(MyNAACCR Login Required)

NAACCR Data Exchange Standard: XML Specifications


NAACCR Edits Metafile Clearinghouse

Order by :

Frequently Asked Questions

  • Yes, if your registry transmits or receives abstracts with data items that are not defined in the NAACCR base dictionary, NAACCR Data Standards & Data Dictionary, (formerly Volume II).
    • If a standard setter requires a new field for annual data submissions or special projects, they typically provide a user dictionary
  • Yes, if your central registry database vendor requires a user dictionary to define custom data items for central registry use only.
  • No, if your registry only transmits or receives abstracts with data items that are defined in the NAACCR base dictionary (Data Standards & Data Dictionary, Volume II). Please submit the form indicating your registry does not maintain a user dictionary.
  • If you receive or transmit NAACCR Vol V pathology items in abstracts, you should not include them in your user dictionary. You should inform your vendors that you use the NAACCR Vol V pathology dictionary (under development)
  • Yes, if you transmit or receive those data items in NAACCR abstracts received from reporting facilities.
  • No, if you don’t require that data item in abstracts from reporting facilities and don’t include that field in abstract submissions to other agencies. For example your registry database might contain a “Family History of Cancer” field for patients.
  • Some vendors of central registry software may require the custom data items for central registry use only be included in a user dictionary for editing, extracting data, etc. These should be indicated in the Data Dictionary Details Template’s Required Status from Reporting Facilities column.
  • The Data Dictionary Details Template which will prompt you for the following details. Refer to NAACCR Data Exchange Standard for more details on these attributes.
    • Maximum 32 characters, start with lowercase, include no punctuation
    • For example, BIRTHPLACE—STATE’s NAACCR ID is birthplaceState
  • Item Name
  • Item Number (recommended 9000+)
  • Parent XML Element (Tumor, Patient, NaaccrData)
  • Length
  • Record Types (A, M, C, I)
  • Data type (digits, alpha, mixed, numeric, date, text)
  • Additionally, the following items are not ultimately defined in the user dictionary, but are included in the Data Dictionary Details Template as they are critical information for software vendors
    • Codes and description
    • Required Status from Reporting Facilities
  • The NAACCR XML workgroup strongly recommends registries review their user dictionary or decision not to create a user dictionary with the release of every NAACCR version, and update their entry on the user dictionary clearinghouse website. Typically user dictionaries include a NAACCR version attribute that must be updated to continue collecting data when the new NAACCR version is released.
    • Open or register your dictionary in a recommended software tool
    • Open your user dictionary in a browser (Chrome, Firefox) and check:
      • Verify the Custom Uniform Resource Identifier (URI) follows naming conventions specified in the XML Data Exchange Standard and includes user dictionary version
      • Ensure all data items and corresponding attributes for your dictionary are included in your Data Dictionary Details Template
  • According to the XML Data Exchange Standard, the filename for a user dictionary should match the last part of the dictionary Uniform Resource Identifier (URI).
    • For example, if the URI is https://mystate.gov/state-cancer-registry/mystate-naaccrdictionary-v1.xml the filename is mystate-naaccrdictionary-v1.xml
  • URI is a unique string that defines the dictionary. It acts as an identifier and is referenced by the NAACCR XML data files. User dictionaries should reference the organization that created them.
  • According to the XML Data Exchange Standard, the custom user dictionaries use the format [custom URI]/[organization]-naaccr-dictionary[-xxx][-v#.#].xml where xxx is the corresponding NAACCR version, which is only required if the custom dictionary depends on a specific NAACCR version. v#.# is your organization’s version of the dictionary (semantic versioning recommended). The suggested custom user dictionary’s file name is the same as the end of this URI.
    • For example: https://mystate.gov/state-cancer-registry/mystate-naaccrdictionary-180-v1.xml
  • Though they look like internet addresses, they do not need to point to an existing web location.

Help with User Dictionaries

NAACCR has established this website as a User Dictionary Clearinghouse to show examples of user dictionaries from other central registries and provide the Data Dictionary Details Template that will help central registries gather information needed to define their own XML User Dictionary. Central registries with registry-specific data items are encouraged to fill out the Excel template and upload it to the XML Dictionary Submission Clearinghouse with a corresponding XML User Dictionary so that registry software vendors can get access to these required files and deploy software changes in a timely manner.


Once uploaded, these files will be publicly available with the intent of allowing registry software vendors the registry-specific customizations, including codes and definitions, for registry-specific data items in their software. While codes and descriptions and item required status are not defined in a user dictionary, central registry-assigned codes and descriptions must be shared with vendors in order to generate look up tables in software displays.


Please note that the Data Dictionary Details Template does not take the place of a user dictionary. The template provides a reference with information needed to successfully implement registry-specific data items in software with the end goal of bringing all of the information together in one place to create a user dictionary file. Once the spreadsheet is filled out, central registries with registry-specific data items must also create and maintain the actual XML user dictionary file. The workgroup recommends that each registry store a copy of past user dictionaries at their registry, as this Clearinghouse only publishes the most recent upload per for each registry.


Additional help can be received by posting to the NAACCR XML Forum, which is monitored by the NAACCR XML Data Exchange Workgroup

Copyright © 2018 NAACCR, Inc. All Rights Reserved | naaccr-swoosh-only See NAACCR Partners and Sponsors