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:

| Field Pattern | Semantic Type | |--------------|---------------| | FirstName, GivenName | person.first_name | | LastName, Surname | person.last_name | | SSN, SocialSecurity | ssn | | Email, EmailAddress | email | | Phone, PhoneNumber | phone_number | | Street, Address1 | address.street | | City | address.city | | State | address.state_abbr | | Zip, ZipCode | address.zipcode | | Amount, Balance, Price | decimal(min, max, decimals) | | Date, EffectiveDate | date.past or date.future | | VIN | vehicle.vin | | AccountNumber | pattern:ACC-{######} |

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