Positional Labeled Tab-Separated Log Format

PLTSV.md

PLTSV: Draft Specification

• Date: 2026-08-17
• Version: 0.6

Positional Labeled Tab-Separated Log Format

1. Abstract

At its core, PLTSV is ordinal LTSV with the first three columns guaranteed.

It is a minimal, line-oriented envelope log format that stands directly atop the established Labeled Tab-Separated Values (LTSV) specification and classic POSIX Tab-Separated Values (TSV). By combining the mechanical predictability of TSV with the self-describing extensibility of LTSV, it creates a strict architectural divide: a universal positional core for high-speed infrastructure routing, and a flexible tail for proprietary application context.

2. Philosophy: Elevating Convention to Contract

PLTSV does not attempt to invent a new paradigm; rather, it formalizes existing best practices.

In the real world, most logger libraries emitting LTSV already place the timestamp, severity, and message first by convention. However, because the LTSV specification itself provides zero positional guarantees, downstream parsers, edge routers, and generic CLI tools cannot safely optimize for it. They are forced to parse the entire line into a dictionary just to locate the severity level, simply because a rogue microservice might have put host: first.

PLTSV takes the implicit convention that engineers already use and promotes it to a strict, enforceable contract. It gives infrastructure explicit permission to be “dumb and fast” for routing, while leaving the tail “smart and flexible” for the application.

3. Merits & Advantages

• O(1) Edge Routing: Log forwarders and edge nodes can peek at the first two tab-stops to filter by time or severity without allocating memory for a hash map or parsing the tail.
• Universal CLI Compatibility: Because the core fields are strictly anchored, you can confidently use cut -f1-3 across a heterogeneous fleet of microservices to extract primary data.
• LLM & Agentic Sympathy: By stripping away the heavy syntactic noise of JSON (braces, quotes, commas), PLTSV maximizes token density. Its flat, predictable structure allows autonomous agents to ingest and filter streams natively using structured shells or POSIX tools, avoiding brittle JSON queries.
• Zero-Configuration Extensibility: Application developers can append arbitrary, high-cardinality metadata to the tail of the log without updating shared schemas, writing custom parsers, or breaking downstream routers.

4. Format Definition

A PLTSV stream consists of zero or more records.
Each record is a single line terminated by \n (LF). \r\n MAY be accepted on input but MUST be normalized to \n on output.
Empty lines MUST be ignored.

Record structure (ABNF):

record         = core-fields *(TAB ext-field) NL
core-fields    = time-field TAB level-field TAB payload-field
time-field     = "time:" time-value
level-field    = "level:" level-value
payload-field  = "payload:" value
ext-field      = label ":" value
label          = 1*(ALPHA / DIGIT / "_" / "-" / ".")
time-value     = ISO8601-date-time   ; see Section 5.1
level-value    = level               ; see Section 5.2
value          = *VALCHAR
VALCHAR        = %x01-08 / %x0B / %x0C / %x0E-5B / %x5D-FF
                 / escaped
escaped        = "\\" / "\t" / "\n" / "\r"
TAB            = %x09
NL             = %x0A

Positional requirements (MUST):

1. First field → timestamp (time:)
2. Second field → level (level:)
3. Third field → payload (payload:)
4. Fourth field onward → optional extension fields (any order)

The labels time, level, and payload are mandatory in their respective positions. Strict-mode parsers MUST reject records that use different labels in the first three positions. Lenient parsers MAY accept alternate labels but MUST still treat the positions as authoritative.

5. Core Fields (The Routing Layer)

5.1 Timestamp (time:)

• MUST be a valid ISO-8601 combined date and time expression with timezone offset.
• UTC (Z) is strongly preferred.
• Fractional seconds are allowed.
• Examples of valid values: 2026-08-17T23:05:12Z, 2026-08-17T23:05:12.123Z, 2026-08-17T16:05:12-07:00

5.2 Level (level:)

Standard tooling MUST understand the following uppercase values:

• DEBUG
• INFO
• WARN
• ERROR

Additional level values MAY appear. Consumers that do not recognize a level SHOULD preserve the original string and MAY map it to the nearest standard level when required by downstream systems.

5.3 Payload (payload:)

Free-form text. The default interpretation is plain text.
Newlines and tabs inside the payload MUST be escaped according to Section 6.

6. Escaping Rules

The only characters that MUST be escaped inside any value are:

Character	Escape Sequence
Tab (%x09)	\t
Newline (%x0A)	\n
Carriage return (%x0D)	\r
Backslash (%x5C)	\\

No other characters require escaping.
The colon (:) has no special meaning inside a value.
Values MAY contain spaces and any UTF-8 characters.
Empty values are represented as label: (nothing after the colon).

7. Extension Fields (The Tail)

Any fields after the third position form the extension tail. They use the same label:value syntax.

PLTSV is strictly an envelope format and enforces zero opinions on the taxonomy, schema, or naming conventions of extension fields.

• Extension fields are proprietary to the emitting application.
• Routers and generic parsers MAY treat the tail as an opaque string.
• Domain-specific consumers MAY unpack the tail using proprietary knowledge.
• Unknown labels MUST be ignored by consumers that do not understand them.

8. Error Handling Guidelines

8.1 Producer Requirements

• Producers MUST emit the three core fields in the required order and with the required labels.
• Producers MUST apply the escaping rules in Section 6.
• On internal formatting failure, a producer SHOULD emit a minimal safe record (time: + level:ERROR + descriptive payload) rather than a malformed line or silence.

8.2 Strict Mode (Parsers)

A strict parser MUST reject a record when any of the following occur:

• Fewer than three fields
• Core fields do not use the exact labels time:, level:, payload:
• Timestamp value is not a valid ISO-8601 date-time with offset
• An unescaped tab or bare newline appears inside a value
• Invalid escape sequence (e.g. trailing \)

Rejected records MUST NOT be partially interpreted.

8.3 Lenient Mode (Recommended for Collectors)

A lenient parser SHOULD recover and continue. Recommended behavior:

Condition	Recommended Action
Fewer than 3 fields	Treat entire line as payload; synthesize time = observation time, level = INFO
Wrong core labels	Still treat positions as authoritative; record the anomaly
Invalid timestamp	Replace with observation time; add pltsv.timestamp_error:1
Unknown level	Preserve original value
Unescaped TAB / broken line	Skip or emit synthetic error record with original line as payload
Invalid escape	Replace bad escape with U+FFFD or leave literal backslash
Duplicate labels in tail	Last value wins (document the choice)
Empty line	Ignore

Lenient parsers SHOULD expose metrics for recovered and rejected records and MAY add diagnostic fields prefixed with pltsv..

8.4 Stream-Level Behavior

A single malformed record MUST NOT abort processing of the stream.
Parsers SHOULD continue after an error.

9. Parsing Recommendations

Minimal compliant parser:

1. Split the line on TAB.
2. Require (strict) or handle (lenient) at least three fields.
3. Split each field on the first colon only.
4. Treat the first three fields as timestamp, level, and payload by position.
5. Fold remaining fields into a map of label → value.

10. Examples

Minimal record (core only)

time:2026-08-17T23:05:12.123Z	level:INFO	payload:service started

With extension fields

time:2026-08-17T23:05:12.123Z	level:ERROR	payload:payment failed	user.id:u-987	order.id:ord-456	http.status_code:402

Escaped payload with tail

time:2026-08-17T23:05:12.123Z	level:ERROR	payload:stack trace:\n\tat com.example.Foo.bar(Foo.java:42)	service:checkout	trace_id:ab12cd34

11. Agentic & AI-Assisted Usage

PLTSV is intentionally well-suited to AI agents and automated tooling:

• The core contract is small enough that an agent can reliably generate correct parsers, filters, and emitters from the specification alone.
• Extremely low syntactic noise (no braces, quotes, or commas required for the common case) improves token efficiency and reduces parsing errors.
• Fixed positions for time, level, and payload allow agents to perform fast filtering and routing with simple string or field operations, without needing full structured parsing.
• Extension fields can be appended without breaking existing consumers, making it easy for agents to enrich records for a specific task.
• The format remains fully compatible with ordinary POSIX tools (cut, awk, grep, etc.), which many agent runtimes already use.

The format is not only for agents — the same properties that benefit automated systems also make it pleasant and efficient for human operators and traditional infrastructure. Agentic friendliness is a consequence of the minimal design, not a special mode.

12. Non-Goals

• Nested data structures (flatten or embed opaque serialized data)
• Binary content
• Multi-line records
• Schema registry or formal type system
• Compression or framing beyond the line format

13. Compatibility Notes

• A pure LTSV parser can read PLTSV records.
• Positional tools can extract the first three fields with simple splitting (cut -f1-3, etc.).
• Future versions of PLTSV will not alter the meaning or position of the three core fields.

---

End of Specification