Create Test Lane

Create Test Lane

Overview

This skill creates test lanes for the ceremony-field-catalog test data generator. Each test lane is a paired XSD schema + meta.yaml configuration that defines how to generate realistic test XML data for a specific business context.

Workflow

Step 1: Gather Requirements

Collect the following information:

1. Context details: What business domain/​context is this for? (e.g., loans, deposits, payments)
2. Data structure: What elements and hierarchy should the XML have?
3. Required metadata: What metadata keys identify this data type?
4. Data realism needs: Which fields need realistic data (names, addresses, SSNs, etc.)?

Step 2: Create the XSD Schema

Create the XSD file at sdks/​python/​test_lanes/<context>/<lane_name>.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/​2001/​XMLSchema">
    <xs:element name="Root">
        <xs:complexType>
            <xs:sequence>
                <!-- Define elements here -->
                <xs:element name="FieldName" type="xs:string"/>
                <xs:element name="Amount" type="xs:decimal"/>
                <xs:element name="OptionalField" type="xs:string" minOccurs="0"/>
                <xs:element name="RepeatingItem" maxOccurs="unbounded">
                    <!-- Nested structure -->
                </​xs:element>
            </​xs:sequence>
        </​xs:complexType>
    </​xs:element>
</​xs:schema>

Key XSD patterns:

• minOccurs="0" for optional elements
• maxOccurs="unbounded" for repeating elements
• nillable="true" for elements that can be nil
• <xs:restriction> with <xs:enumeration> for fixed value lists

Important: Optional enum elements must be nillable

When an element uses an enumeration type AND is optional (minOccurs="0"), you MUST also add nillable="true". This is because the generator's emptyRate setting can produce empty values, but empty strings are not valid enum values. Making the element nillable allows it to be represented as xsi:nil="true" instead of an empty string.

<!-- WRONG: Will fail validation if emptyRate produces empty value -->
<xs:element name="Status" type="StatusEnum" minOccurs="0"/>

<!-- CORRECT: Can be nil when empty -->
<xs:element name="Status" type="StatusEnum" minOccurs="0" nillable="true"/>

This applies to all optional elements with enumeration types (Gender, Status, Type, Category, etc.).

Step 3: Generate or Create the Meta File

Option A: Use init-meta command (for existing XSD):

cd sdks/​python
python -m testgen.cli init-meta --xsd test_lanes/<context>/<lane>.xsd --context <context_id>

Option B: Create manually at sdks/​python/​test_lanes/<context>/<lane_name>.meta.yaml:

Refer to references/​meta-format.md for the complete meta.yaml format specification.

Step 4: Configure Semantic Types

Map field paths to semantic types for realistic data. Common mappings:

Step 5: Configure Field Overrides

Customize generation for specific fields:

fieldOverrides:
  "/​Root/​OptionalSection":    # Optional element
    fillRate: 0.3             # Include 30% of the time
  "/​Root/​Items/​Item":         # Repeating element
    repeatRange: [2, 10]      # Generate 2-10 items

Step 6: Validate the Test Lane

cd sdks/​python

# Dry run to verify generation works
python -m testgen.cli run ./​test_lanes/ -l <context>/<lane_name> --dry-run -n 5 --output-dir ./​test_output/

# Inspect generated XML
cat ./​test_output/​*.xml

File Locations

• XSD schemas: sdks/​python/​test_lanes/<context>/<lane_name>.xsd
• Meta configs: sdks/​python/​test_lanes/<context>/<lane_name>.meta.yaml
• CLI module: sdks/​python/​testgen/​cli.py

Resources

This skill includes reference documentation:

references/

• meta-format.md - Complete meta.yaml format specification with all semantic types and options