Classification set file formats

The JSON file format follows conventions for JSON Lines (JSONL). The file must contain one JSON object per line, where each object represents a single classification record.

JSON structure

Each JSON object must contain:

• key (required): The unique identifier for the classification record

• data (required for updates): An object containing classification column names and their values

• action (optional): The action to perform. Supported values include:

  • update (the default action, when no action is specified)
  • delete-field
  • delete-key

• enc (optional): Data encoding specification. Supported values include:

  • utf8 or UTF8 (default)
  • latin1 or LATIN1

All JSON field names (key, data, action, enc) are case-sensitive and must be lowercase.

JSON validation rules

• The key field is required and cannot be null or empty.
• For update actions, the data field is required and cannot be empty.
• For delete-field actions, the data field must contain the fields to delete.
• For delete-key actions, the data field must not be present.
• Supported encoding values are case-insensitive and include standard charset names.

JSON examples

Some examples of JSON records in a JSON file.

Basic update record

{"key": "product123", "data": {"Product Name": "Basketball Shoes", "Brand": "Brand A", "Category": "Sports"}}

Update with encoding specified

{"key": "product456", "enc": "utf8", "data": {"Product Name": "Running Shoes", "Brand": "Brand B"}}

Delete specific fields

{"key": "product789", "action": "delete-field", "data": {"Brand": null, "Category": null}}

Delete an entire key

{"key": "product999", "action": "delete-key"}

CSV (Comma-Separated Values) files use commas to separate classification data fields.

CSV structure

• Header row: The first row must contain column headers and the first column must be the key column. Subsequent columns should match names in yours classification set schema
• Data rows: Each subsequent row contains classification data
• Delimiters: Fields are separated by commas
• Quoting: Fields containing commas, quotes, or newlines should be enclosed in double quotes

CSV formatting rules

• Fields that contain commas must be enclosed in double quotes.
• Fields that contain double quotes must escape quotes by doubling them ("").
• Empty fields represent null values for that classification.
• Leading and trailing spaces around fields are automatically trimmed.
• Special characters (tabs, newlines) within quoted fields are preserved.

CSV delete operations

• Use ~deletekey~ in any field to delete the entire key and all its classification data
• Use ~empty~ in specific fields to delete only those classification values (leaves other fields intact)
• When using ~empty~, you can mix deletions with updates in the same file

CSV examples

Some examples of CSV records in a CSV file.

Basic classification data

Key,Product Name,Brand,Category,Price
product123,"Basketball Shoes",Brand A,Sports,89.99
product456,"Running Shoes",Brand B,Sports,79.99
product789,"Winter Jacket",Brand C,Clothing,149.99

Delete an entire key

Key,Product Name,Brand,Category,Price
product999,~deletekey~,,,

Delete specific fields (mixed with updates)

Key,Product Name,Brand,Category,Price
product123,"Updated Product Name",Brand A,Sports,89.99
product456,,~empty~,~empty~,79.99

TSV (Tab-Separated Values) and TAB files use tab characters to separate classification data fields.

TSV and TAB structure

• Header row: The first row must contain column headers and the first column must be the key column. Subsequent columns should match names in yours classification set schema.
• Data rows: Each subsequent row contains classification data.
• Delimiters: Fields are separated by tab characters (\t).
• Quoting: Generally no quoting is needed, but some implementations support quoted fields.

TSV and TAB formatting rules

• Fields are separated by single tab characters.
• Empty fields (consecutive tabs) represent null values.
• No special quoting is typically required.
• Leading and trailing spaces are preserved.
• Newline characters within fields should be avoided.

TSV and TAB delete operations

• Use ~deletekey~ in any field to delete the entire key and all its classification data.
• Use ~empty~ in specific fields to delete only those classification values (leaves other fields intact).
• When using ~empty~, you can mix deletions with updates in the same file.

TSV and TAB examples

Some examples of TSV or TAB delimited records in a TSV or TAB file.

Basic classification data

Key    Product Name    Brand    Category    Price
product123    Basketball Shoes    Brand A    Sports    89.99
product456    Running Shoes    Brand B    Sports    79.99
product789    Winter Jacket    Brand C    Clothing    149.99

Delete an entire key

Key    Product Name    Brand    Category    Price
product999    ~deletekey~

Delete specific fields (mixed with updates)

Key    Product Name    Brand    Category    Price
product123    Updated Product Name    Brand A    Sports    89.99
product456        ~empty~    ~empty~    79.99