Property Type Handling in CSV¶

When loading data, every value in your CSV starts as a string. The Loader automatically coerces these strings into the correct types based on the property definitions on your entity type. This page documents how each property type is handled. These behaviors do not change across entities and apply to all loadTypes.

null or empty values

If no value is specified for a given property, the property will be set to null or 0, depending on the property type. Use this if you want to clear out the value of a property. Exclude the property column entirely from the CSV file if you do not want to edit a property.

CSV Headers: Labels vs. Slugs¶

CSV column headers can use either the property's slug (key) or its display label. The Loader automatically converts labels to slugs during the preprocessing pipeline (steps 4 and 6).

Example: If your entity type has a property with:

Slug: fabricWeight
Label: Fabric Weight

Either of these CSV headers will work:

fabricWeight,name,federatedId

Fabric Weight,name,federatedId

Matching rules:

Slug matching is exact (case-sensitive).
Label matching is case-insensitive.
If a column matches neither a slug nor a label, it is ignored during entity construction and a warning is recorded.
If a column matches a disabled/archived property, a warning is recorded but the value is still processed.

Type Coercion Reference¶

String / Text¶

Behavior	Details
Coercion	None -- passed through as-is
Empty value	Empty string `""` is a valid value and will be set on the property
`null` handling	Only truly falsy values (not empty strings) are skipped

CSV escaping notes:

You must escape double quotes by ensuring that the entire column is wrapped in double quotes themselves.
- Example: to get value He said "Hello World!", CSV should be ,"He said, "Hello World!"",
You do not need to escape single quotes in CSV.
- Example: to get value O'Brien, CSV can be ,O'Brien,
Commas within values can be escaped by enclosing the column in double quotes.
- Example: to get value New York, NY, CSV should be ,"New York, NY",

Number / Currency / Percent / Sequence¶

Behavior	Details
Coercion	Commas, backslashes, and double quotes are stripped, then parsed as `Number`
Empty value	Skipped (property not set) unless the parsed value is `0`, which is valid
Examples	`"1,234.56"` → `1234.56`, `"50"` → `50`, `"$20.00"` → `NaN` (don't include currency symbols)

Always specify the exact value you intend to load, irrespective of the decimal format setting:

For Percent: use a number between 0 and 100. Example: 50 for 50%, 50.5 for 50.5%.
For Currency: use a number. Example: 20 for $20, 20.5 for $20.50.
For Number: use a number. Example: 20 for 20, 20.5 for 20.5.

The platform will round any numbers up to the nearest decimal place.

Don't include currency symbols or percent signs

The Loader strips commas and quotes but does not remove currency symbols ($, €) or percent signs (%). Provide raw numeric values only.

Boolean¶

Behavior	Details
Coercion	`"true"` / `"false"` (case-insensitive) converted to `true` / `false` in step 1 of the pipeline
Empty value	`false` is a valid value and will always be set (not skipped)
Always included	Boolean properties are always included in the entity, even when the value is `false`

Specify TRUE or FALSE in the CSV. Yes or No are not supported.

Date¶

Behavior	Details
Coercion	Parsed as a standard JavaScript Date
Supported formats	`YYYY-MM-DD`, `YYYY-MM-DDTHH:mm:ss.SSSZ`, and most standard date formats
Empty value	Sets the property to `null` (clears the date)
Display	Dates display as `MM/DD/YYYY` in core apps regardless of input precision

You may provide a date with or without the timestamp included, with support down to milliseconds in ISO format. Only a date without timestamp will display to end users.

Specifying 2000-01-01 (format YYYY-MM-DD) in the CSV will display 01/01/2000 in core apps as January 1st, 2000.
Specifying 2025-06-24T16:55:16.123Z (format YYYY-MM-DDTHH:mm:ss.SSSZ) in the CSV will display as 06/24/2025 in core apps as June 24th, 2025.

Single Select (Choice)¶

Behavior	Details
Coercion	Display labels are automatically converted to option set values (keys) during preprocessing
Matching	You can provide either the option key or the display label
Empty value	Sets the property to `null` (clears the selection)
Invalid value	A warning is recorded if the value doesn't match any option; the value is passed through as-is

Example: For an option set "Sub Class" with { key: "sweater", label: "Sweater" }:

CSV value "sweater" → stored as "sweater" (already a key)
CSV value "Sweater" → converted to "sweater" during preprocessing

Multi Select¶

Behavior	Details
Coercion	Comma-separated string is split into an array. Each value undergoes display-to-key conversion.
Format in CSV	Comma-separated within the cell, e.g., `"North America,Europe"`
Empty value	Sets the property to `null` (clears all selections)
CSV escaping	Since commas are used as both CSV delimiters and multi-select separators, wrap the cell in double quotes: `"value1,value2"`

Example: For an option set "Regions" with options { key: "north-america", label: "North America" } and { key: "south-america", label: "South America" }:

CSV value "North America,South America" → ["north-america", "south-america"]
CSV value "north-america,south-america" → ["north-america", "south-america"]

Size Range¶

Size ranges support two formats in CSV:

Format 1: Key-Value Dimensional

For multi-dimensional size ranges, use a colon-separated format where each dimension lists its sizes:

width: S,M,L | length: 30,32,34

Format 2: Comma-Separated Flat

For simple one-dimensional size ranges:

S,M,L,XL

Size range validation

After loading, size range values are validated against the entity's size range template. Invalid sizes (not in the template) are automatically removed, and warnings are recorded.

Formula¶

Behavior	Details
Always skipped	Formula properties are never loaded from CSV. Any values in formula columns are silently discarded.
Calculation	Formulas are calculated automatically by the platform after entity creation/update.

You cannot load into any property backed by a Formula directly. The Formula will always calculate itself on create or update, and there is no override capability.

Object Reference¶

Behavior	Details
Coercion	The CSV value should be the `federatedId` of the referenced entity. The Loader resolves this to an entity ID.
Resolution	Federated IDs are looked up in batches. Unresolved references produce warnings.
Requirement	The referenced entity must already exist in VibeIQ with a `federatedId`.

There is no support for id or name matching to other entities at this time.

Example: To relate an Item to a Color via an object reference property colorReference, specify the federatedId of the Color in the CSV. If the Color's federatedId is NAVY-BLUE, specify NAVY-BLUE in the Item load CSV.

User List¶

Behavior	Details
Coercion	The CSV value should be the email address of the user. The Loader resolves emails to user IDs.
Resolution	All org users are fetched and matched by email.

Style Number,Style Name,Merchandiser
STY-001,Classic Tee,jane.doe@company.com
STY-002,V-Neck Tee,john.smith@company.com

Property Levels (Family, Option, All, Override)¶

On entity types with property levels (referred to in the API as roles), loading behavior is distinct between each of them. Currently, these apply to:

Item entities
ProjectItem entities

Family/Option Suffix Columns¶

For entity types with property levels, you can use the Family or Option suffix on property names to target specific levels:

CSV Header	Effect
`someProperty`	Sets the value on the entity as-is
`somePropertyFamily`	Sets the value specifically on the Family entity
`somePropertyOption`	Sets the value specifically on the Option entity

The suffix is stripped during matching -- somePropertyFamily resolves to the property with slug someProperty.

"Family" and "Option" Properties¶

There is no special handling for these property types. You will simply need to match the property key as a column in the CSV, or by using federatedMappings and conditionalColumns.

"Family" properties will update the single Family-level entity and those values will be copied down and persisted onto each of that Family's Options.
"Option" properties will update the single Option-level entity and those values will be persisted only onto that Option entity.

"All" Properties¶

"All" properties are managed individually for every entity in a Family, regardless if it's a Family or Option level entity. No copy down behavior exists for these properties because of this. The loader handles this differently based on what you give it.

If you provide an exact match on the property key, the loader will update the value for that property on every entity in the Family. You may also uniquely specify Family and Option level values separately by splitting the CSV out into two columns. One column with name suffixed with "Family" and the other with "Option". By doing this you can specify different values for each of the Family and Option.

Example with Family and Option columns:

itemFederatedId	optionFederatedId	somePropertyKeyFamily	somePropertyKeyOption
001	001-RED	Some Family Value	Unique RED value
001	001-BLUE	Some Family Value	Unique BLUE value
001	001-GREEN	Some Family Value	Unique GREEN value

The Family item will be given value "Some Family Value" for its somePropertyKey property.
The Option items will be given each different values for their somePropertyKey properties.

Keep the Family column values the same for all rows when splitting them out!

If you are splitting out an "All" property with Family and Option columns, ensure you keep the Family column values the same for all rows. Otherwise, you may see indeterminate behavior where the loader randomly picks one of them, because it doesn't know which is the correct value.

Example with a single column:

itemFederatedId	optionFederatedId	somePropertyKey
001	001-RED	All the same
001	001-BLUE	All the same
001	001-GREEN	All the same

The Family item will be given value "All the same" for its somePropertyKey property.
The Option items will all be given that same "All the same" value for their somePropertyKey properties.

"Override" Properties¶

"Override" properties are like "Family" properties, where the value set on the Family entity's property will copy down to all the Options' properties. The key distinction is that you can override the value on the Option level by specifying a different value for it. Just like for "All" properties, you can use "Family" and "Option" suffixes to specify different values for each. See the "All" properties section for more information on how this works.

Special Handling¶

Nested Properties¶

Properties with dot-notation slugs (e.g., dimensions.width) are supported. The Loader builds nested objects automatically:

CSV value "10" in column dimensions.width produces:

{
  "dimensions": {
    "width": "10"
  }
}

Properties Not in the Type Schema¶

CSV columns that don't match any property on the entity type (by slug or label) are silently ignored during entity construction. They produce a warning during preprocessing but don't cause errors.

Federated ID Encoding¶

Federated IDs containing forward slashes (/) are automatically URL-encoded to %2F when looking up existing entities. You don't need to pre-encode them in your CSV.