name

create-test-lane

description

This skill should be used when creating new test lanes for the XML test data generator. A test lane consists of an XSD schema file paired with a meta.yaml configuration file. This skill guides the process of creating both files with proper semantic type mappings, distribution settings, and field overrides. Use when users request new test lanes, want to generate test data configurations, or need help setting up XSD + meta.yaml pairs for the testgen CLI tool.

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:

Context details: What business domain/context is this for? (e.g., loans, deposits, payments)
Data structure: What elements and hierarchy should the XML have?
Required metadata: What metadata keys identify this data type?
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