SDTM Mapping Spec Walkthrough

Picture a reviewer pointing at one Vital Signs (VS) value: subject 004, week 8, Vital Signs Test Code (VSTESTCD) SYSBP, result 142 millimetres of mercury. Your program can explain how that number was computed, but only the mapping specification explains why it was computed that way, and who approved that decision. The studies that answer this calmly all share one artifact: a spec where every Study Data Tabulation Model (SDTM) variable traces to a source, a transformation, and a decision owner. Today we cover spec column anatomy, a row-by-row VS walk, hygiene rules, and how that spec becomes define Extensible Markup Language (define-XML) and machine-usable code.

This slide calls the mapping spec a three-party contract, because three groups read it for different reasons. Data management reads it to know what was assumed about collection, and programmers read it to know exactly what to build. Reviewers and inspectors read it to trace any submitted value back to a source. The spec exists so those three readings never conflict. The enforcement rule is simple: every mapped variable must trace to a spec row. Code that outputs a variable with no spec row is a finding, raised during internal quality control (QC) or inspection, whichever comes first.

Each mapping spec row is a contract answering five auditable questions about one target variable. Target names the Study Data Tabulation Model, or SDTM, variable being produced, like the Vital Signs, or VS, variable VS.VSSTRESN; Source names the raw dataset variable, here RAW.VS.RESULT, or the word assigned. Transformation must be a formula, not prose — for example, if the temperature is in Fahrenheit, subtract 32 and multiply by five ninths. Controlled Terminology, or CT, and Origin carries the codelist binding, such as UNIT, plus whether the value is from the Case Report Form, or CRF, derived, or assigned — here Origin equals Derived. Notes and Query records open questions, the decision owner, and dates, like Q-117 pending Data Management, or DM, response. Drop any one of these five columns, and the row stops being a contract.

This checkpoint quiz tests your grasp of the Study Data Tabulation Model (SDTM) mapping specification basics. For the first question, a defensible SDTM mapping specification is read by three parties. The correct answer is B, because the implementing statistical programmer needs explicit source-to-target derivation rules, quality control (QC) needs independent testable target rules, and the regulatory reviewer or auditor needs to trace an approved specification row to the emitted SDTM output. For the second question, a defensible SDTM specification row for a target variable such as Vital Signs Test Code (VSTESTCD) in the Vital Signs (VS) domain must contain five columns: the target variable name, the variable label, the source mapping reference, the exact derivation instruction, and controlled terminology or permitted-value constraints, with an explicit not applicable when no codelist applies. The correct answer is A, B, C, D, and E. For the third question, if your SDTM program writes Vital Signs Sequence Number (VSSEQ) but no approved specification row names it, the output is undocumented and not defensible, so you must stop treating the dataset as final, add an approved specification row for VSSEQ with the required metadata, obtain review and approval, and rerun the VS program.

This is the complete Vital Signs, or VS, specification: fourteen rows, verbatim from the published define-XML, that is, Extensible Markup Language. Rows one and two are assigned constants: STUDYID is XYZ-001, and DOMAIN is VS. Row three derives USUBJID, the unique subject identifier, by joining Demographics, or DM, on SUBJID and reusing that value verbatim. Row four builds VSSEQ, the Vital Signs sequence number, as a count within USUBJID after a deterministic sort by VSTESTCD, VSDTC, and VSPOS, meaning test code, collection date and time, and position. Row nine is value-level: if the test code is TEMP and the unit is F, convert with input minus thirty-two, times five over nine; otherwise keep the raw result. Rows twelve and fourteen carry queries and conventions: VSPOS holds open query Q-117 about Supine, and VSDY has no day zero.

In this hands-on exercise, you work on the website at jaimeyan.com/learn rather than in the video, assembling four incomplete Vital Signs, or VS, specification rows: the sequence number, VSSEQ; the numeric standard result with its standard unit, VSSTRESN and VSTRESU; the position, VSPOS; and the study day, VSDY. For each Target you select the correct Source, Transformation, Controlled Terminology and Origin, and Notes or Query block, and when a choice is wrong the feedback points you back to the source row, because a blank row is always better than a guessed rule. So after the video ends, open jaimeyan.com/learn and try it yourself, so you can defend every row you write.

Rule one: one row per target variable, because Vital Signs Original Results, or VSORRES, and Vital Signs Standard Results Numeric, or VSSTRESN, have different sources and different rules. Rule two: transformations as formulas, not prose — standardize units is a wish, but Celsius equals Fahrenheit minus 32 times 5 divided by 9 is a specification. Rule three: unresolved rows carry an open query identifier — a blank transformation is allowed while Q-117 is open, but guessing is never allowed. Rule four: constants get rows too — assigned variables appear in Define Extensible Markup Language, or define-XML, so record each assignment in the spec. Rule five: every revision is dated and owned — the file itself must answer 'someone changed the temperature rule in March.'

In this scene, we move from spec rows to code. The published Statistical Analysis System (SAS) data step builds the Vital Signs (VS) domain from the raw Vital Signs dataset. Rows 7 through 10 of the Study Data Tabulation Model (SDTM) specification transcribe almost mechanically into that SAS snippet. The code keeps the Unique Subject Identifier (USUBJID), Vital Signs Sequence Number (VSSEQ), Vital Signs Test Code (VSTESTCD), Vital Signs Original Result (VSORRES), Vital Signs Original Units (VSORRESU), Vital Signs Standardized Result in Numeric (VSSTRESN), and Vital Signs Standardized Units (VSSTRESU). Notice what is missing: there is no judgment, because every branch exists because a spec row says it does. When the Q-117 answer arrives, the fix lands in one spec row first, then in one program line, and the two changes review together.

On this slide, we move from the specification to define-XML, the metadata standard from the Clinical Data Interchange Standards Consortium, or CDISC. The Origin column, meaning Case Report Form, Derived, or Assigned, becomes the Origin attribute on each ItemDef. The Controlled Terminology, or CT, column, such as Vital Signs Test Code, or VSTESTCD, becomes a codelist reference. A value-level rule, like row nine, becomes a computational method through value-level metadata. This define-XML must be generated from the spec, never hand-typed, so spec and metadata cannot disagree. The spec itself is data: Comma-Separated Values, or CSV, or YAML Ain't Markup Language, or YAML, files under version control, so a mapping change is a Pull Request, or PR, diff; then Continuous Integration, or CI, closes the loop: change, rebuild domains, regenerate define-XML, re-run validation, and drift fails the build.

Now let's put the spec in the driver's seat for an agentic workflow. Agents are strong at the mechanical layer: they transcribe formula-grade specification rows into code accurately in one pass, and they do it consistently. The failure mode sits at the edges; an agent may fix a program while the spec row stays put, which is drift, or fill a blank transformation row with a plausible rule of its own, which is gap-filling. So make drift mechanical too: derive the expected variable list from the spec or the generated define-XML, where XML stands for Extensible Markup Language, and diff it against produced datasets in continuous integration, or CI. Finally, this tool-specific layer is volatile; it was last verified on August thirtieth, two thousand twenty-six, so re-verify before relying on it.

This is the final knowledge check, so let's apply the Vital Signs (VS) mapping rules we just walked through. Question one asks which five metadata fields make a mapping spec row auditable and which structure rule keeps two different measurements apart. The correct answer is A: source dataset, source variable, target variable, transformation or derivation, and controlled terminology or codelist, with one VS record for each Vital Signs test, so two different Vital Signs Test Codes (VSTESTCD), such as systolic and diastolic blood pressure, never share a single Original Result (VSORRES) and Standardized Numeric Result (VSSTRESN) row. Question two is a multiple-response item about an unresolved VSORRES value with an open data-management query. The correct answers are A and C: leave the VSSTRESN transformation blank while keeping the open query ID visible against the row, and do not guess a mapping, because a tracked blank is safer than an invented rule that can pass checks and appear in define Extensible Markup Language (define-XML) as confirmed. Question three asks why define-XML must be generated from the spec rather than from the final SAS dataset or from hand-written code, and what happens first when a query closes in a Continuous Integration (CI) pipeline. The model answer: generating it from the spec keeps the metadata tied to the controlled source-to-target rules and makes drift visible in CI, and when the query about the VSORRES and VSSTRESN code is answered, your first action is to update the spec transformation, then regenerate define-XML and run CI.

So, the mapping specification is a contract: a three-party agreement where every mapped variable traces to a spec row. Every row answers five questions: target, source, transformation, controlled terminology and origin, and notes or queries. That is the anatomy of the fourteen-row vital signs (VS) domain walk you just saw. Keep it defensible: transformations as formulas, open query identifiers visible, constants as their own rows, every revision dated and owned. The same rows generate the define-XML — that is, Extensible Markup Language (XML) — file and transcribe into code; in agent-era tooling the spec stays authoritative while a continuous integration diff catches divergence. From Study Data Tabulation Model (SDTM) adverse events (AE) mapping, the series next moves to Analysis Data Model (ADaM) Basic Data Structure (BDS), covering the laboratory analysis dataset (ADLB) and the vital signs analysis dataset (ADVS).