June 27, 2025
Do’s and Don’ts of Define.xml
General
DO
Create codelists that describe the data collection process and include all planned terms for the variable. All CRF options should be included in the codelists, not just those present in the data.
DO
Keep it concise. Take time to ensure only relevant information is provided in the define.xml.
DON’T
Make your define.xml too complicated. Remember that review team who are not familiar with your data or mappings will need to navigate your define.xml.
DON’T
Assume the end users of your define.xml have CDISC knowledge. Taking the time to ensure your define.xml is clear, concise, and consumable for review team is important.
DON’T
Assume everyone reading your define.xml has programming knowledge. The define.xml is intended to be both machine and human readable and contains information that different members from review team might need to reference.
Derivations and comments
DO
Concisely define all the derivations used. Define.xml should provide derivations that are clear and concise to replicate the same results.
DO
Describe all internal standards. To avoid confusion, ensure that the review team are given the necessary information to leverage Sponsor standards during the review process.
DON’T
Cut corners and list a derived variable as Origin = Assigned. It is always best to provide the derivation.
DON’T
Have any raw data references in your derivations or comments. The review team does not have access to your raw data.
DON’T
Blindly copy out derivations and comments from the mapping spec into the define.xml. Often there is coding language and raw data references that may clutter your file. Instead, replace the technical jargon with human-readable language.
Codelists
DO
Create codelists for each variable populated by a list of pre-defined terms. Variables collected via drop down lists, or which have a pre-defined limited set of terms, should have an associated codelist within the define.xml.
DO
Create codelists that describe the data collection process and include all planned terms for the variable. All CRF options should be included in the codelists, not just those present in the data.
DON’T
Have one UNIT codelist for all unit variables/values across the data package. When a reviewer clicks on EXDOSU codelist, they want to see only the units in the EX domain, not units across EX, LB, VS, etc.
DON’T
Create codelists with all values from CDISC CT when many values are irrelevant to your data package – similarly, when a reviewer clicks on EXDOSU codelist, they do not want to see all 500+ units from CDISC CT.
DON’T
Complicate your define.xml with codelists meant for other data packages. Including ADaM codelists in SDTM define.xml, and vice versa, will lead to complex and large define.xml files to navigate.
Before you submit
DO
Look at your finalized define.xml file using the stylesheet. Incorporating this step into internal review process is sure to find some overlooked details.
DO
Create a separate PDF file for large derivations that require formatting. The define.xml standard does not account for formatting (e.g., new line characters, numbered lists, bullet points, etc.)
DON’T
Just hit the “generate define.xml” button in your software tool. Incorporating common-sense QC steps will go a long way. Spend time reviewing your define.xml through a web browser with the stylesheet applied.
Download our helpful checklist for your copy of the essential Define do’s and don’ts.
Need more help with Define.xml?
If you have lingering questions or need additional support, we’re here to assist. Reach out to our team for expert guidance and ensure your submissions are seamless and compliant.
Product Manager, Pinnacle 21 by Certara
This blog was originally written by David Roulstone in 2018, and was updated by Trevor Mankus in June 2025.
