Second working draft

SFlat v0.2 standard functionality

Last update: October 2026

SFlat v0.2 keeps the original text-row model as the Text profile and adds a Payload profile for large strings and binary values, while tightening canonical bytes, integrity checks, and validation rules.

SFlat v0.2 is experimental and pre-1.0. This page is a public overview, not a normative replacement for the draft specification.

Document structure

An SFlat document is UTF-8 without a byte-order mark and uses LF line endings only. It starts with a declaration, followed by single-line headers, one empty line, and then the body.

#!sflat 0.2
Profile: payload
Layout: row
Body-Encoding: text-payloads
Records: 1
Schema: Id:int64:req;Name:str(100):req;Photo:bytes:opt

--1,Alice,#p:1:5120:deflate+b64
#p:1 <exactly 5120 stored bytes>

Required headers

Profile — text or payload.
Layout — v0.2 supports row.
Body-Encoding — text or text-payloads.
Records — exact logical record count.
Schema — ordered field definitions.

Optional headers

Description — one-line human description.
Body-Bytes — byte length from the data origin to EOF.
Body-Hash — sha256: digest over stored body bytes.
Index — sparse record offsets for fast seeking.
External-References — advisory companion resources.

Profiles

Profile	Body-Encoding	Purpose
`text`	`text`	The fully textual row-oriented profile and direct successor to SFlat 0.1.
`payload`	`text-payloads`	Rows plus counted payload references for large strings and binary data.

A reader must reject unsupported profiles or incompatible profile/body-encoding combinations; extension headers cannot change body parsing rules.

Schema, field hints, and scalar values

Schema fields are separated by semicolons and use name:type:presence[hints]. Presence is req or opt. Hints are optional, uninterpreted key=value notes such as units or source metadata; they must never affect parsing or validation.

Type	Purpose
`str(n)`	Unicode string up to n scalar values.
`bool`	`true` or `false`.
`int32`, `int64`	Signed 32-bit or 64-bit integers.
`float64`	Finite IEEE-754 binary64, shortest round-trip text.
`decimal(p,s)`	Exact decimal with required scale.
`date`, `time(p)`	Calendar date and local time values.
`local-datetime(p)`	Date-time without an offset or timezone interpretation.
`instant(p)`	UTC instant ending in `Z`.
`offset-datetime(p)`	Date-time with explicit `+HH:MM` or `-HH:MM` offset.
`uuid`	Canonical lowercase hyphenated UUID.
`bytes`, `bytes(n)`	Logical octets, optionally length-bounded.

\N is an explicit null and is valid only for optional fields. Empty fields are empty strings only for str(n). Trailing optional fields may be omitted and mean null.

Payload profile and binary data

The Payload profile keeps ordinary scalar values inline and adds two binary forms: inline #b values and counted #p payload lines.

Inline bytes

Values below 256 logical bytes must be written inline as #b:<logical-bytes>:<chain>:<encoded>. In the Text profile the transform chain must be b64.

Counted payloads

Values at or above 256 logical bytes must be written as #p:<id>:<stored-bytes>:<chain>, followed immediately by matching #p:<id> ... payload lines.

SFlat v0.2 uses one canonical binary chain: deflate+b64, or plain b64 when uncompressed storage is chosen. Payload IDs are scoped to the current record, and comments must not appear between a record and its payload lines.

Canonical bytes, validation, and integrity

Canonical writers emit UTF-8 without BOM, LF line endings, lowercase format tokens, ordered standard headers, canonical scalar text, and deterministic inline-vs-payload placement using the 256-byte threshold.

Body-Bytes verifies the exact stored body length.
Body-Hash: sha256:... verifies the exact stored body bytes.
Index stores byte offsets to selected record boundaries.
External-References lists small advisory companion resources.

Body-Hash is an integrity check for the stored bytes, not proof of authenticity and not a cross-tool logical content fingerprint.

What changed from v0.1

Added

Profiles and Body-Encoding: text-payloads.
float64, uuid, and bytes.
#b inline bytes and #p payloads.
Field hints and External-References.

Changed

LF-only line endings.
Body-Hash uses sha256:.
New escapes \/ and \#.
Validation accounts for counted payload ranges.

Deferred

Digital signatures.
Row hashes and logical content fingerprints.
Additional codecs such as Zstandard or Z85.
Nested structures, arrays, maps, and column storage.