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 (default)
  • 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 examples

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 entire key:

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

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.

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 examples

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 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

CSV formatting rules

• Fields containing commas must be enclosed in double quotes
• Fields containing 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

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 (Tab-Separated Values) and TAB files use tab characters to separate classification data fields.

TSV/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/TAB examples

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 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 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

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