Data Formats

Reference for import and export file formats in Kuviq.

Overview

This guide covers:

• CSV format specifications
• Excel file requirements
• JSON structure
• Field types and validation
• Common issues

CSV Format

General Requirements

Requirement	Specification
Encoding	UTF-8 (recommended)
Delimiter	Comma (,)
Line ending	CRLF or LF
Text qualifier	Double quote (")
Headers	First row

Handling Special Characters

When data contains commas or quotes:

name,description
"Item with, comma","Description with ""quotes"""
Normal item,Normal description

Date Formats

Accepted date formats:

Format	Example
ISO 8601	2024-01-15
ISO with time	2024-01-15T10:30:00
US format	01/15/2024
European	15/01/2024

Recommended: ISO 8601 for consistency.

Boolean Values

True	False
true	false
TRUE	FALSE
1	0
yes	no
YES	NO

Empty Values

• Empty string: ,,
• Null: Leave empty
• Don't use: "null", "N/A", "none"

Excel Format

Supported Versions

Format	Extension	Support
Excel 2007+	.xlsx	Full
Excel 97-2003	.xls	Full
OpenDocument	.ods	Limited

Sheet Requirements

• Data on first sheet
• Or named sheet specified
• Headers in row 1
• Data starting row 2

Formatting Issues

Avoid:

Issue	Problem
Merged cells	Data loss
Formulas	Values not read
Conditional formatting	Ignored
Comments	Ignored
Images	Ignored

Date Handling

Excel dates:

• Use date format cells
• Not text that looks like dates
• Check regional settings

Number Handling

Issue	Solution
Leading zeros	Format as text
Long numbers	Format as text
Currency symbols	Remove
Thousand separators	Remove or configure

JSON Format

Structure

Basic JSON export structure:

{
  "exportDate": "2024-01-15T10:30:00Z",
  "exportType": "items",
  "data": [
    {
      "id": "item_001",
      "name": "Fire Extinguisher A1",
      "itemType": {
        "id": "type_001",
        "name": "Fire Extinguisher"
      },
      "location": {
        "id": "loc_001",
        "name": "Building A"
      },
      "status": "available",
      "customFields": {
        "pressureGauge": "OK",
        "lastServiceDate": "2024-01-10"
      }
    }
  ]
}

Nested Objects

Related data nested:

{
  "item": {
    "id": "item_001",
    "name": "Fire Extinguisher A1",
    "inspections": [
      {
        "id": "insp_001",
        "date": "2024-01-15",
        "result": "passed"
      }
    ]
  }
}

JSON Lines Format

For large exports, JSON Lines:

{"id": "item_001", "name": "Fire Extinguisher A1"}
{"id": "item_002", "name": "First Aid Kit B2"}
{"id": "item_003", "name": "Safety Harness C3"}

Field Specifications

Item Fields

Field	Type	Required	Description
name	string	Yes	Item name (max 200 chars)
itemType	string	Yes	Type name or ID
location	string	No	Location name or ID
serialNumber	string	No	Serial/asset number
manufacturer	string	No	Manufacturer name or ID
status	enum	No	available, in_use, needs_attention, under_maintenance, retired
description	text	No	Description (max 5000 chars)
externalId	string	No	Your system's ID
tags	array	No	Comma-separated tags
customFields	object	No	Type-specific fields

Location Fields

Field	Type	Required	Description
name	string	Yes	Location name
parent	string	No	Parent location name/ID
address	string	No	Physical address
description	text	No	Description
externalId	string	No	Your system's ID

User Fields

Field	Type	Required	Description
email	email	Yes	User email address
name	string	Yes	Display name
role	enum	No	superAdmin, admin, manager, user
locations	array	No	Assigned location names/IDs
externalId	string	No	Your system's ID

Inspection Fields

Field	Type	Required	Description
item	string	Yes	Item name or ID
template	string	Yes	Template name or ID
inspector	string	Yes	User email or ID
date	datetime	Yes	Inspection date/time
result	enum	Yes	passed, failed
elements	array	Yes	Element results
notes	text	No	Inspector notes

Custom Fields

Custom Field Format

In CSV:

name,itemType,cf_pressure_gauge,cf_last_service
Fire Ext A1,Fire Extinguisher,OK,2024-01-15

In JSON:

{
  "name": "Fire Ext A1",
  "itemType": "Fire Extinguisher",
  "customFields": {
    "pressure_gauge": "OK",
    "last_service": "2024-01-15"
  }
}

Custom Field Types

Type	CSV Value	JSON Value
Text	Plain text	"string"
Number	123.45	123.45
Boolean	true/false	true/false
Date	2024-01-15	"2024-01-15"
Select	Option text	"option_value"
Multi-select	opt1,opt2	["opt1", "opt2"]

Reference Fields

Referencing Other Records

Reference by name or ID:

Reference	By Name	By ID
Location	"Building A"	"loc_12345"
Item Type	"Fire Extinguisher"	"type_67890"
User	"john@example.com"	"user_abcde"

Creating References

For import:

• Referenced record must exist
• Or create in same import
• Or import in order (locations first)

Validation Rules

Required Fields

• Must have value
• Cannot be empty string
• Cannot be null

String Limits

Field Type	Limit
Name	200 characters
Description	5000 characters
Notes	2000 characters
Tags	50 per item

Value Validation

Type	Validation
Email	Valid email format
Date	Valid date value
Enum	Must match allowed values
Number	Numeric value

Common Issues

CSV Issues

Issue	Cause	Solution
Wrong delimiter	System uses ; or
Encoding errors	Not UTF-8	Save as UTF-8
Missing quotes	Text with commas	Ensure quoted
Extra columns	Trailing commas	Clean file

Excel Issues

Issue	Cause	Solution
Dates wrong	Regional format	Use ISO format
Numbers truncated	Cell format	Format as text
Leading zeros gone	Auto-format	Format as text
Data missing	Wrong sheet	Move to first sheet

JSON Issues

Issue	Cause	Solution
Parse error	Invalid syntax	Validate JSON
Wrong structure	Missing keys	Check documentation
Encoding	Not UTF-8	Re-encode

Sample Files

Items CSV Sample

name,itemType,location,serialNumber,manufacturer,status,description
Fire Extinguisher A1,Fire Extinguisher,Building A Floor 1,FE-2024-001,Kidde,available,10lb ABC extinguisher
First Aid Kit B2,First Aid Kit,Building B,FAK-2024-002,Johnson & Johnson,available,Standard wall-mounted kit
Safety Harness C3,Safety Harness,Warehouse,SH-2024-003,3M,available,Fall protection harness

Locations CSV Sample

name,parent,address,description
Headquarters,,123 Main St,Main office building
Building A,Headquarters,,North wing
Building A Floor 1,Building A,,First floor
Building A Floor 2,Building A,,Second floor
Building B,Headquarters,,South wing
Warehouse,,456 Industrial Blvd,Storage facility

Users CSV Sample

email,name,role,locations
john.smith@example.com,John Smith,admin,
jane.doe@example.com,Jane Doe,manager,"Building A,Building B"
bob.wilson@example.com,Bob Wilson,user,Warehouse

Tools & Tips

Helpful Tools

Tool	Use For
Excel	Editing, viewing
Google Sheets	Collaboration
OpenRefine	Data cleaning
jq	JSON processing

Pre-Import Checklist

• Headers in first row
• Required fields present
• Date format consistent
• References valid
• No duplicate keys
• Encoding is UTF-8
• No empty rows
• Test with small sample

Next Steps

• Bulk Import - Import data
• Bulk Export - Export data
• Items Management - Manual entry