Data import formats

The most versatile data format for importing data to Custobar is JSON, but also comma-separated values (CSV) is supported. When uploading data using the Custobar API, the format of the data must be specified using the HTTP Content-Type header.

JavaScript Object Notation (JSON)

When importing data in JSON format, the data items are send in a list, optionally wrapped in a JSON object's property with name corresponding to the type of the entities being imported. Here is an example of product import, importing two products, using the unwrapped list style.

[
  { "external_id": "P001-01", "title": "Unicorn T-Shirt, Pink" },
  { "external_id": "P001-02", "title": "Unicorn T-Shirt, White" }
]

And the same using JSON object wrapper

{
  "products": [
    { "external_id": "P001-01", "title": "Unicorn T-Shirt, Pink" },
    { "external_id": "P001-02", "title": "Unicorn T-Shirt, White" }
  ]
}

The content type header for importing JSON is "application/json"

Content-Type: application/json

The character encoding for JSON in UTF-8, as dictated by JSON specification. If the string values in the data contain non-ascii characters, they should be either escaped using valid JSON escape sequences, or encoded in UTF-8.

Comma-separated values (CSV)

The proper HTTP content type header for importing CSV data is text/csv. Optionally, character set may be given in the header. Supported charsets are "utf-8", "utf-16" and "iso-8859-1" (latin-1). If not given, character encoding defaults to utf-8. To import latin-1 encoded data, use:

Content-Type: text/csv; charset=iso-8859-1

Delimiter character for fields can be either comma (","), semi-colon (";") or tabulator ("\t"). Custobar will infer the correct delimiter to use from the data.

The first line of the CSV file should be a header line listing all column names. Here is the product import example using a comma delimited CSV:

external_id,title
P001-01,"Unicorn T-Shirt, Pink"
P001-02,"Unicorn T-Shirt, White"

Note that the title values that contain delimiter characters or newline characters must be quoted using double quotes. It is ok to quote all values even if not strictly required. Because double quotes function as escape characters, they need to be escaped as well. The CSV escape for double quote character is double double quote. For example, importing a product with quotes in title:

external_id,title
s06e07,"Episode 7: ""Once More, With Feeling"""

Nested fields in CSV

Because a CSV does not support nested fields, importing nested objects can be a little tricky. It is however possible, using dot-separated property paths. For example, this customer import with nested structure:

{
  "customers": [
    {
      "external_id": "c001",
      "email": "cge@example.com",
      "horse": {
        "name": "Käthy",
        "breed": "arabian",
        "color": "chestnut"
      }
    }
  ]
}

can be imported using CSV file like this (semi-colon delimited this time)

external_id;email;horse.name;horse.color
c001;cge@example.com;Käthy;chestnut

JSON lists can be encoded using integer indices in the property paths. For example, importing the stock amount for a product in a single location

external_id;stock.0.shop_id;stock.0.quantity
P001-01;1;39

This will be treated as the JSON structure below

[
  {
    "external_id": "p001-01",
    "stock": [
      {
        "shop_id": "1",
        "quantity": "39"
      }
    ]
  }
]

Note that the numerical property values are converted to JSON strings. They will be interpreted as numbers as appropriate when validating the data against the data schema.