Skip to content

list and item Elements

<list>

The <list> element defines a collection of data items, where each item can contain its own attributes, keys, and arrays. Lists are useful for representing structured data, such as rows in a table, or collections of objects with shared attributes. The <list> can contain multiple <item> elements that represent individual entries.

Attributes

  • name: Specifies the name of the list, which will serve as the key for the list in the generated data. This is a mandatory attribute.

Children

  • item: The <item> element defines individual entries within the list. Each item can have its own set of attributes, keys, nested keys, lists, and arrays.

<item>

The <item> element represents an individual entry within a <list>. Items can include their own key-value pairs, nested data structures, arrays, or even other lists, allowing you to create complex and nested data models.

Attributes

  • condition: (Optional)
  • Specifies a condition that determines if the item should be included in the generated output. The condition should evaluate to true or false.

Children

  • key: Defines individual key-value pairs for the item.
  • nestedKey: Allows you to specify nested key-value pairs, enabling you to create hierarchical structures within an item.
  • list: Enables nested lists within an item for complex data hierarchies.
  • array: Defines arrays within the item.

Example 1: Simple List with Static Items

In this basic example, each item in the list is defined with static key-value pairs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<list name="employees">
    <item>
        <key name="first_name" constant="John"/>
        <key name="last_name" constant="Doe"/>
        <key name="position" constant="Developer"/>
    </item>
    <item>
        <key name="first_name" constant="Jane"/>
        <key name="last_name" constant="Smith"/>
        <key name="position" constant="Manager"/>
    </item>
</list>

Here, the employees list contains two items representing two employees, each with first_name, last_name, and position keys.

Example 2: List with Dynamic Content

You can generate lists dynamically using generators or scripts to populate the values.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<list name="products">
    <item>
        <key name="product_name" script="f'Product {random.randint(1, 100)}'"/>
        <key name="price" script="random.uniform(10.0, 100.0)"/>
    </item>
    <item>
        <key name="product_name" script="f'Product {random.randint(101, 200)}'"/>
        <key name="price" script="random.uniform(50.0, 200.0)"/>
    </item>
</list>

In this example, the products list contains two items where the product_name and price are generated dynamically using Python expressions.

Example 3: List with Arrays in Items

Each item in a list can contain arrays of related data, allowing you to represent more complex structures.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<list name="departments">
    <item>
        <key name="name" constant="Engineering"/>
        <array name="team_members" type="string" count="3" script="['Alice', 'Bob', 'Charlie']"/>
    </item>
    <item>
        <key name="name" constant="Marketing"/>
        <array name="team_members" type="string" count="3" script="['Dave', 'Eve', 'Frank']"/>
    </item>
</list>

Here, the departments list contains two departments, each with an array of team_members.

Example 4: List with Nested Structures

You can nest additional lists or keys inside items to create hierarchical data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
<list name="companies">
    <item>
        <key name="company_name" constant="TechCorp"/>
        <nestedKey name="address">
            <key name="street" constant="123 Main St"/>
            <key name="city" constant="San Francisco"/>
            <key name="zipcode" constant="94105"/>
        </nestedKey>
        <array name="employees" script="['John Doe', 'Jane Smith']"/>
    </item>
    <item>
        <key name="company_name" constant="BizCorp"/>
        <nestedKey name="address">
            <key name="street" constant="456 Market St"/>
            <key name="city" constant="New York"/>
            <key name="zipcode" constant="10001"/>
        </nestedKey>
        <array name="employees" script="['Alice Johnson', 'Bob Brown']"/>
    </item>
</list>

In this example, the companies list contains two companies, each with a nested address structure and an array of employees.

Example 5: List with Conditional Items

You can add conditions to items to control whether they should appear in the generated output.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<list name="users">
    <item condition="random.randint(0, 1) == 1">
        <key name="username" constant="user123"/>
        <key name="email" constant="[email protected]"/>
    </item>
    <item>
        <key name="username" constant="user456"/>
        <key name="email" constant="[email protected]"/>
    </item>
</list>

Here, the users list contains two items, but the first item will only be included if the condition (random.randint(0, 1) == 1) evaluates to true.

Example 6: List of Nested Lists

You can nest additional lists inside items for more complex hierarchies, such as representing a company with multiple departments.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<list name="company">
    <item>
        <key name="name" constant="Acme Corp"/>
        <list name="departments">
            <item>
                <key name="department_name" constant="Sales"/>
                <array name="employees" script="['Alice', 'Bob']"/>
            </item>
            <item>
                <key name="department_name" constant="Engineering"/>
                <array name="employees" script="['Charlie', 'Dave']"/>
            </item>
        </list>
    </item>
</list>

In this example, the company list contains an item for Acme Corp, which includes a nested list of departments, each with an array of employees.

Example 7: List with Dynamic Data and Arrays

You can generate dynamic data inside a list and populate arrays dynamically within the items.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<list name="projects">
    <item>
        <key name="project_name" script="f'Project {random.randint(1, 10)}'"/>
        <array name="milestones" script="[f'Milestone {i}' for i in range(1, 4)]"/>
    </item>
    <item>
        <key name="project_name" script="f'Project {random.randint(11, 20)}'"/>
        <array name="milestones" script="[f'Milestone {i}' for i in range(4, 7)]"/>
    </item>
</list>

In this example, the projects list contains two projects, each with dynamically generated project names and milestones.

Best Practices for Using <list> and <item> Elements

  1. Use Conditional Logic: Leverage the condition attribute in <item> to control which items appear in the output, allowing you to add variability and control in your generated data.

  2. Nesting for Complexity: Combine <list>, <item>, <nestedKey>, and <array> elements to build complex hierarchical data structures like organizations, products, or multi-level records.

  3. Dynamic Data Generation: Use the script attribute inside <key>, <array>, and <nestedKey> to dynamically generate content for your lists and items.

  4. Type Matching: Ensure that data types (e.g., string, int, float, bool) in your arrays and lists match the expected format to avoid issues in the output.

  5. Scalability: Lists and items can be combined to generate large datasets or complex models, but careful management of script complexity and conditions will help maintain readability and scalability.