Fixtures

Fixtures let you load initial data from JSON or CSV files into the database when the application starts. AMSDAL checks for new or changed fixture data on each startup and creates or updates objects accordingly.

Directory Structure

Place fixture files inside a fixtures folder within the model directory:

📁 models
└── 📁 my_model
    ├── 📄 model.json
    └── 📁 fixtures
        ├── 📄 data.json
        └── 📄 data.csv

External IDs

Every fixture record must have an _external_id — a unique identifier used to:

• Link related fixtures by reference
• Determine whether to create or update an object on subsequent runs

The _external_id must be unique across all fixtures and all models.

Note

Deleting a fixture file does not delete the corresponding objects from the database. You must delete them manually.

JSON Format

[
    {
        "_external_id": "parent_location",
        "name": "Parent Location",
        "parent": null,
        "tags": ["tag1", "tag2"]
    },
    {
        "_external_id": "child_location",
        "name": "Child Location",
        "parent": "parent_location"
    }
]

References between fixtures use the _external_id value. In the example above, "parent": "parent_location" creates a reference to the first fixture.

Named Fixtures

To define fixtures for multiple models in a single file, use a JSON object keyed by class name:

{
    "Location": [
        {
            "_external_id": "new_york",
            "name": "New York"
        }
    ],
    "Person": [
        {
            "_external_id": "john_doe",
            "first_name": "John",
            "last_name": "Doe",
            "location": "new_york"
        }
    ]
}

CSV Format

Use column headers as field names:

_external_id,name,parent,tags
parent_location,Parent Location,,"tag1,tag2"
child_location,Child Location,parent_location,

Ordering

By default, fixture loading order is not guaranteed. Use the _order field to control the sequence:

[
    {
        "_external_id": "parent",
        "_order": 1,
        "name": "Parent"
    },
    {
        "_external_id": "child",
        "_order": 2,
        "name": "Child",
        "parent": "parent"
    }
]

The _order value can be any number (integer or float), including negative values. Fixtures are loaded in ascending order. Default is 0.

File Type Fixtures

For models with File fields, place files in a fixtures/files directory and reference them by path:

📁 models
└── 📁 country
    └── 📁 fixtures
        ├── 📄 data.json
        └── 📁 files
            └── 📄 us.png

[
    {
        "_external_id": "us",
        "name": "United States",
        "code": "US",
        "icon": "Country/us.png"
    }
]

The file path format is [ModelName]/[FileName]. This also works with list[File] fields:

{
    "_external_id": "hotel_1",
    "name": "Freehand Los Angeles",
    "photos": ["Property/1.jpeg", "Property/2.jpeg", "Property/3.jpeg"]
}