2.2: OPL Header and Metadata

The ADAPT WeBWorK Handbook · LibreTexts

0%

Contents

    Text

    Size
    100%
    Theme
    Typeface
    Line length
    Spacing

    From LibreTexts, under CC BY 4.0, as the source states it; its equations are written in TeX, which the PDF shows typeset. This page at LibreTexts.

    The OPL header is the metadata block that comes before DOCUMENT() and makes a problem searchable, classifiable, and reusable. In this guide, the header is treated as a real section ("section zero") even though traditional PG documentation only lists four sections.

    Use this page when: you are creating a new problem or adapting an existing one and need correct metadata for long-term reuse.

    Use the templates in Minimal Templates as your starting point so you do not forget required fields.

    Required and recommended fields

    Required and recommended fields: field, status, and why it matters.
    Field Status Why it matters
    TITLE('...') Required Short, student-facing title used in search and listings.
    DESCRIPTION block Required Two to three sentences describing the task and constraints.
    KEYWORDS(...) Strongly recommended Improves search and grouping across a bank.
    DBsubject/DBchapter/DBsection Strongly recommended Primary classification tags for the Open Problem Library.
    Level(...) Required Bloom's taxonomy level (1-6) for difficulty classification.
    Attribution fields Recommended Credits authors and institutions for long-term reuse.
    Language(en) Required ISO 639-1 code specifying the problem language.

    Copy and edit (OPL header template)

    ## TITLE('Short descriptive title')
## DESCRIPTION
## One to three sentences describing the task and constraints.
## ENDDESCRIPTION
## KEYWORDS('keyword1','keyword2','keyword3')
## DBsubject('Biochemistry')
## DBchapter('Enzymes')
## DBsection('Kinetics basics')
## Level(2)
## Date('2026-01-28')
## Author('Author name')
## Institution('Institution name')
## Language(en)

    TITLE field guidance

    The TITLE is the student-facing name that appears in problem listings and search results. Keep it short (under 80 characters), descriptive, and focused on the task rather than the story wrapper.

    Good vs bad titles

    Good vs bad titles: good title, bad title, and why.
    Good title Bad title Why
    Compute dilution factor from stock and final concentration This is a problem about dilutions in the lab Bad: filler words, says "problem", not task-focused
    X-linked inheritance from fly offspring counts Genetics practice Bad: vague, no detail, "practice" is filler
    Enzyme kinetics: calculate Km from Lineweaver-Burk Calculate Michaelis constant using the reciprocal transformation approach Bad: too long (> 80 chars)
    Determine qPCR fold change from Ct values qPCR Bad: too terse, doesn't describe the task

    DESCRIPTION block guidance

    The DESCRIPTION block is a 2-3 sentence instructor-facing summary that explains the task, any constraints that affect adoption (unit requirements, rounding, domain restrictions), and provenance if adapted from another source.

    Template with placeholders

    ## DESCRIPTION
## [Task in one sentence]. [Constraints or special requirements]. [Optional: Adapted from ...]
## ENDDESCRIPTION

    Biology examples of complete DESCRIPTION blocks

    Enzyme kinetics problem

    ## DESCRIPTION
## Students calculate the Michaelis constant (Km) from enzyme kinetics data using a
## Lineweaver-Burk plot. Answers require two significant figures and appropriate units (mM).
## ENDDESCRIPTION

    Genetics cross problem

    ## DESCRIPTION
## Students determine the probability of offspring genotypes from a dihybrid cross using
## Punnett square logic. Answers are fractions in lowest terms (e.g., 9/16).
## ENDDESCRIPTION

    Dilution series problem

    ## DESCRIPTION
## Students calculate final concentrations in a serial dilution series given a stock
## concentration and dilution factors. Answers must include units (µM or mM) and use
## scientific notation for very small values.
## ENDDESCRIPTION

    What NOT to include in DESCRIPTION

    • Do not paste full solutions or step-by-step instructions.
    • Do not include long pedagogical essays or teaching philosophy.
    • Do not include code or implementation details.
    • Do not describe the story wrapper (e.g., "students imagine they are in a lab").

    KEYWORDS guidance

    Use 3 to 5 keywords (prefer 3-4 when possible) that describe techniques, concepts, or methods. Avoid character names, story nouns, or terms already implied by DBsubject.

    Keyword selection process for biology problems

    Example 1: Dilution problem

    • Good keywords: 'serial dilution', 'concentration', 'stock solution'
    • Bad keywords: 'biology', 'lab', 'science', 'tube'
    • Why: Good keywords are searchable techniques. Bad keywords are too generic or story nouns.

    Example 2: Enzyme kinetics problem

    • Good keywords: 'Michaelis-Menten', 'Lineweaver-Burk', 'enzyme kinetics', 'Km'
    • Bad keywords: 'biochemistry', 'enzyme', 'calculation'
    • Why: Good keywords name specific methods. Bad keywords duplicate DBsubject or are too broad.

    Example 3: qPCR problem

    • Good keywords: 'qPCR', 'fold change', 'Ct value', 'delta-delta Ct'
    • Bad keywords: 'gene expression', 'RNA', 'technique'
    • Why: Good keywords are technique-specific. Bad keywords are outcome terms, not methods.

    How to avoid duplicating DBsubject terms

    If DBsubject is Biochemistry, do not use 'biochemistry' as a keyword. Instead, use technique names like 'enzyme kinetics', 'Henderson-Hasselbalch', or 'buffer capacity'. Keywords should narrow the search within the subject area.

    DBsubject, DBchapter, and DBsection guidance

    These three fields form the primary classification taxonomy for the Open Problem Library. Choose values that fit life science courses and match existing usage in your repository for consistency.

    Biology-appropriate DBsubject values

    Biology-appropriate DBsubject values: dbsubject value and when to use.
    DBsubject value When to use
    Biology - molecular DNA, RNA, transcription, translation, replication
    Biology - introductory General biology concepts, cell structure, basic processes
    Biochemistry Enzyme kinetics, metabolism, protein structure, buffers
    Genetics Inheritance patterns, Punnett squares, linkage, pedigrees
    Laboratory Techniques Dilutions, spectrophotometry, gel electrophoresis, qPCR
    Cell Biology Organelles, transport, signaling, cell cycle
    Biostatistics Statistical tests, experimental design, data analysis

    Decision tree: choosing the right DBsubject

    1. What is the primary discipline? Start with the course context (Biochemistry, Genetics, etc.)
    2. Is it a technique or concept? If purely technique-focused (dilutions, PCR), use Laboratory Techniques.
    3. Is it broad or specific? If the problem spans multiple sub-disciplines, use the most specific subject that still fits typical course organization.
    4. Does it match existing usage? Search your repository for similar problems and copy the exact DBsubject string to maintain consistency.

    Full list of biology-appropriate DBsubject values

    Use these DBsubject values for life science content. If a new subject is needed, add it to the list so tags remain consistent across the repository.

    Full list of biology-appropriate DBsubject values reference.
    DBsubject value When to use
    Anatomy and Physiology Organ systems, body structures, physiological processes
    Biochemistry Enzyme kinetics, metabolism, protein structure, buffers
    Bioinformatics and Computational Biology Sequence analysis, phylogenetics, computational methods
    Biomedical Sciences Disease mechanisms, pharmacology, clinical applications
    Biostatistics Statistical tests, experimental design, data analysis
    Cell Biology Organelles, transport, signaling, cell cycle
    DNA Profiling Forensic DNA analysis, STR markers, electrophoresis patterns
    Ecology Population dynamics, ecosystems, biodiversity
    Evolution Natural selection, phylogenetics, population genetics
    Immunology Immune responses, antibodies, vaccines, immunoassays
    Inheritance Genetics Inheritance patterns, Punnett squares, linkage, pedigrees
    Laboratory Techniques Dilutions, spectrophotometry, gel electrophoresis, qPCR
    Microbiology Bacteria, viruses, microbial growth, antimicrobials
    Molecular Biology DNA replication, transcription, translation, gene regulation
    Neuroscience Neural signaling, brain structure, synaptic transmission
    Organismic Biology Whole-organism biology, plant biology, animal biology

    Complete classification examples

    Example 1: Dilution problem

    ## DBsubject('Laboratory Techniques')
## DBchapter('Solution preparation')
## DBsection('Serial dilutions')

    Example 2: Enzyme kinetics problem

    ## DBsubject('Biochemistry')
## DBchapter('Enzymes')
## DBsection('Kinetics basics')

    Example 3: Genetics cross problem

    ## DBsubject('Genetics')
## DBchapter('Mendelian inheritance')
## DBsection('Dihybrid crosses')

    Problem level: Bloom's taxonomy scale

    The Level(...) field uses a 1-6 scale aligned to Bloom's revised taxonomy: Remember, Understand, Apply, Analyze, Evaluate, Create. This field is required for problems in the biology-problems repository.

    Problem level: Bloom's taxonomy scale: level, bloom's category, verbs, and more.
    Level Bloom's category Verbs Biology example
    1 Remember recall, define, label, list, match, identify "Which amino acid has a sulfur atom in its side chain?"
    2 Understand explain, summarize, interpret, classify, compare "Classify this molecule as a carbohydrate, lipid, protein, or nucleic acid."
    3 Apply apply, use, determine, solve, choose "Using the genetic code table, translate this mRNA sequence."
    4 Analyze analyze, compare, contrast, categorize, infer "Analyze this gel electrophoresis result to determine which protein is largest."
    5 Evaluate evaluate, justify, critique, defend "Justify why an Arg-Glu-Asp peptide would be more soluble than Leu-Val-Ile at pH 7.0."
    6 Create design, propose, formulate, develop, create "Design a peptide sequence that would be maximally soluble at pH 7.0."

    Level assessment tips

    • Level 1 (Remember): Direct recall, no inference or multi-step reasoning needed. Asking for definitions, names, or lists.
    • Level 2 (Understand): Requires understanding and classification, but necessary reference values are given.
    • Level 3 (Apply): Direct application of rules or formulas with clear instructions and provided data.
    • Level 4 (Analyze): Student must infer relationships, analyze multiple factors, or synthesize information from different knowledge domains.
    • Level 5 (Evaluate): Requires defending a conclusion, evaluating competing explanations, or justifying choices based on multiple criteria.
    • Level 6 (Create): Requires synthesizing knowledge to create novel solutions, designs, or models.

    Level format

    ## Level(3)

    Language field

    Use ISO 639-1 language codes to specify the problem language. This field is required. For English, use:

    ## Language(en)

    Attribution and provenance fields

    These fields credit authors, track provenance, and clarify licensing. They are recommended for all problems and required for adapted content.

    Minimal recommended set

    ## Date('2026-01-28')
## Author('Dr. Neil R. Voss')
## Institution('Roosevelt University')

    Rules for attribution

    • If the problem is adapted, also state that in DESCRIPTION (e.g., "Adapted from ...").
    • Use a real date when known. Prefer ISO format: YYYY-MM-DD.
    • Empty strings are acceptable when you do not know the details, but do not invent information.

    Textbook provenance fields

    Use these when the problem is adapted from a textbook, worksheet, or other source. Number the tags (TitleText1, TitleText2, etc.) to map to multiple texts when appropriate.

    ## TitleText1('Title of source')
## EditionText1('Edition')
## AuthorText1('Author(s)')
## Section1('Section identifier')
## Problem1('Problem identifier')

    License comments

    OPL does not define a standard license tag. Use plain comment lines (single #, not ##) to state licensing for the problem text and any included images or code.

    # This work is licensed under CC BY 4.0 (Creative Commons Attribution 4.0
# International License).
# https://creativecommons.org/licenses/by/4.0/
# Source code portions are licensed under LGPLv3.

    Tagging quality rules

    1. DBsubject reflects the discipline and course area, not the scenario.
    2. KEYWORDS reflect methods and concepts, not superficial nouns.
    3. Use consistent capitalization and spelling across the corpus.
    4. Prefer stable, existing label strings over "better" new strings.
    5. Avoid "meta noise" labels like WeBWorK or ZZZ-Inserted Text in new content.

    Header review checklist

    Before publishing a problem, verify the following:

    • DESCRIPTION exists and is short, accurate, and code-free.
    • KEYWORDS exist and are concept-focused (3-5 terms).
    • DBsubject uses an existing repo string from the local list.
    • DBchapter and DBsection are present (no empty strings).
    • Level is set using the 1-6 Bloom's taxonomy scale.
    • Author and Date are present when known.
    • Language(en) is present.
    • No smart quotes or non-ASCII characters in header lines.

    Complete worked examples

    These examples show full OPL headers for different problem types. Copy and adapt for your own problems. For more templates, see Minimal Templates.

    Full header for a dilution problem

    ## TITLE('Serial dilution: calculate final concentrations')
## DESCRIPTION
## Students calculate final concentrations in a serial dilution series given a stock
## concentration and dilution factors. Answers must include units (µM or mM) and use
## scientific notation for very small values.
## ENDDESCRIPTION
## KEYWORDS('serial dilution','concentration','stock solution')
## DBsubject('Laboratory Techniques')
## DBchapter('Solution preparation')
## DBsection('Serial dilutions')
## Level(3)
## Date('2026-01-28')
## Author('Dr. Neil R. Voss')
## Institution('Roosevelt University')
## Language(en)

    Full header for a genetics problem

    ## TITLE('Dihybrid cross: predict offspring ratios')
## DESCRIPTION
## Students determine the probability of offspring genotypes from a dihybrid cross using
## Punnett square logic. Answers are fractions in lowest terms (e.g., 9/16).
## ENDDESCRIPTION
## KEYWORDS('dihybrid cross','Punnett square','Mendelian inheritance','independent assortment')
## DBsubject('Genetics')
## DBchapter('Mendelian inheritance')
## DBsection('Dihybrid crosses')
## Level(3)
## Date('2026-01-28')
## Author('Dr. Neil R. Voss')
## Institution('Roosevelt University')
## Language(en)

    Full header for a pathway problem

    ## TITLE('Glycolysis: identify rate-limiting enzymes')
## DESCRIPTION
## Students identify which enzymes in the glycolytic pathway are subject to allosteric
## regulation and explain their physiological significance. Free-response answers are
## graded for keyword matches.
## ENDDESCRIPTION
## KEYWORDS('glycolysis','allosteric regulation','rate-limiting enzyme','metabolism')
## DBsubject('Biochemistry')
## DBchapter('Metabolism')
## DBsection('Glycolysis')
## Level(4)
## Date('2026-01-28')
## Author('Dr. Neil R. Voss')
## Institution('Roosevelt University')
## Language(en)

    Common mistakes and how to avoid them

    • Empty DBsubject string: Never leave DBsubject, DBchapter, or DBsection empty. Choose the closest existing label and revise later if needed.
    • Smart quotes in header: Use plain ASCII quotes ('), not curly quotes (' or '). Smart quotes break OPL parsing tools.
    • Missing ENDDESCRIPTION tag: Always close the DESCRIPTION block with ## ENDDESCRIPTION. Without it, parsers may read subsequent code as part of the description.
    • Too many keywords: More than 5 keywords dilutes search effectiveness. Stick to 3-5, preferring the most distinctive terms.
    • Using "practice" or "problem" in title: Titles should describe the task, not announce that it's a practice problem. Replace "Practice computing dilutions" with "Compute dilution factor from concentrations".
    • Pasting code into DESCRIPTION: The description is for humans, not parsers. Keep it plain English and code-free.

    Apply it today

    • Before editing a problem, confirm it has a TITLE and DESCRIPTION block.
    • Copy the template from Minimal Templates and fill in metadata before writing PGML.

    This page titled 2.2: OPL Header and Metadata was last modified on Fri, 27 Feb 2026 15:16:38 GMT and is shared under a CC BY 4.0 license and was authored, remixed, and/or curated by Neil R. Voss.