Schema & Column Types

GKit builds a schema for your sheet the moment it reads the header row. That schema drives how values are serialised in JSON responses, which filter operators are legal, how sorting behaves, and whether a write request is accepted or rejected.

This page explains how GKit infers a type from a header name alone - before it ever looks at cell values - and what each of the five supported types means end-to-end.

Header-name inference

GKit first tries to infer a column type from the header name itself, using a set of well-known naming patterns. This runs before cell-value sampling, so a column named created_at is treated as datetime even if the sheet is empty.

When a header name matches a pattern, GKit skips cell-value sampling for that column entirely. If no pattern matches, GKit falls back to sampling the first non-empty cell to decide between string, number, boolean, and datetime.

Supported column types

GKit supports five column types. Each controls serialisation, filtering, sorting, and write validation.

string

Plain text. Cell values are returned as JSON strings with no transformation. Empty cells become null.

Filtering operators: =, !=, contains, startsWith, endsWith.

Sorting: lexicographic (A → Z).

number

Integer or floating-point values. GKit coerces the raw cell string to a JavaScript number. Values that cannot be coerced - such as a cell containing "N/A" - become null rather than causing an error.

Filtering operators: =, !=, >, >=, <, <=.

Sorting: numeric ascending or descending.

boolean

True/false flag. GKit recognises the following as true (case-insensitive): true, yes, 1, on. Any other non-empty value becomes false. Empty cells become null.

Filtering operators: =, !=.

Sorting: false before true (ascending).

datetime

Date or date-time values. GKit parses the cell value and serialises it as an ISO 8601 UTC string (YYYY-MM-DDTHH:mm:ss.sssZ). Bare dates with no time component are treated as midnight UTC.

{
  "created_at": "2025-06-01T00:00:00.000Z",
  "published_at": "2025-06-15T14:30:00.000Z"
}

Filtering operators: =, !=, >, >=, <, <=. Filter values must be ISO 8601 strings or the special keyword now.

?filter=created_at:>=:2025-01-01T00:00:00.000Z
?filter=published_at:<:now

Sorting: chronological.

json

Structured data stored as a JSON string in the cell. GKit parses the string and returns the parsed value inline. If parsing fails, the raw string is returned and a _parse_error key is added to the row object.

{
  "tags": ["sale", "featured"],
  "metadata": { "source": "import", "version": 2 }
}

Filtering operators: =, != (compared against the serialised JSON string). Deep key filtering is not supported - pre-filter in your application code.

Sorting: not supported for json columns.

Overriding inference with type-hint suffixes

Append :type to any header name to force a specific type regardless of what the name or cell values suggest.

zip_code:string      → "90210"  (prevents numeric coercion)
revenue:number       → 1200.50
launched:boolean     → true
archived_at:datetime → "2025-03-10T00:00:00.000Z"
config:json          → { "retries": 3 }

The suffix is stripped before the key appears in JSON responses. A header named revenue:number returns as revenue in every response object.

Null handling

Regardless of column type, an empty cell always becomes null in the JSON response. This applies to cells that were never filled in, cells cleared after data entry, and cells where a formula returns an empty string.

Use the null filter keyword to find or exclude empty cells:

?filter=published_at:=:null      - rows with no publish date
?filter=price:!=:null            - rows that have a price set

Best practices for header naming

Getting inference right from the header name avoids surprises when the sheet is empty or partially filled.

• Use the _at suffix for all date and time columns: created_at, expires_at.
• Prefix boolean flags with is_ or has_: is_published, has_image.
• Avoid naming numeric columns with words that look like booleans: active_count is inferred as number; is_active as boolean.
• If a column holds ZIP codes, phone numbers, or other digit-only strings that must not be parsed as numbers, append :string to the header: zip_code:string.
• Keep header names lowercase with underscores. GKit strips :type suffixes before exposing keys, so the JSON output is always clean.
• For JSON columns, store valid JSON in every cell - invalid JSON falls back to the raw string and may cause unexpected behaviour in clients that expect an object.