DTL Specification

Grammar & Syntax

File Structure

dtl-file     = header-1 NEWLINE header-2 NEWLINE table+

header-1     = "@dtlv" version "^" domain "^" profile "^" 
               compression "^" security "^" web3 "^" checksum

header-2     = "@sec" "^" hash-algo "^" wallet "^" signature "^" chain-id

table        = table-header NEWLINE data-row*

table-header = table-name "|" schema "|" row-count "|" 
               table-security "|" table-web3 "|" table-compression

schema       = field-def ("," field-def)*

field-def    = field-name ":" field-type

field-type   = "s" | "i" | "f" | "b" | "D" | "T" | "u" | "j"
             | "a(" inner-type ")"
             | "e(" enum-values ")"

enum-values  = value ("," value){0,9}  # Max 10 values

data-row     = value ("|" value)*

Character Encoding

• All DTL files MUST be UTF-8 encoded
• Pipe character (|) is reserved as field delimiter
• Caret character (^) is reserved for header fields
• Newline (\n) separates rows
• Comments start with # and extend to end of line

Type System

Enum Type Specification

Rules

• Maximum 10 values per enum field
• Exact match only - case-sensitive validation
• No whitespace around values (unless intentional)
• Any characters except comma and parentheses
• Empty values not allowed in definition

Valid Examples

# String enums
status:e(pending,active,completed,cancelled)
priority:e(low,medium,high,critical)
role:e(admin,user,guest)

# Numeric-looking enums (still strings)
rating:e(1,2,3,4,5)
grade:e(A,B,C,D,F)

# Codes
blood_type:e(A+,A-,B+,B-,AB+,AB-,O+,O-)
http_method:e(GET,POST,PUT,DELETE,PATCH)

Invalid Examples

# ❌ More than 10 values
month:e(jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec)

# ❌ Empty value
status:e(active,,inactive)

# ❌ Nested parentheses
type:e(a(b),c)

Security Modes

Hash Table Format

When using S1 or S2, a companion hash table stores integrity proofs:

HASH_TABLENAME|row:i,hash:s|N|S0|W0|C0
1|blake3_abc123def456...
2|blake3_789xyz012abc...
3|blake3_def789ghi012...

Web3 Modes

Signature Table Format

SIG_TABLENAME|row:i,signer:s,signature:s|N|S0|W0|C0
1|0xABCD...1234|0xSIG123...
2|0xABCD...1234|0xSIG456...
3|0xEFGH...5678|0xSIG789...

Blockchain Anchoring

CHAIN|target:s,chain:s,txid:s,block:i|1|S0|W0|C0
FILE|ETH|0xabc123...def456|19234567

Domain Codes

DTLAuth Token Specification

ID Token (dtID)

Domain: dtID
Profile: DTLAuthID1
Required Tables:
  - USER: uid, name, email, role:e(...), aud:a(s)
  - CLAIMS: uid, iss, iat:T, exp:T, nbf:T
Security: S2 (encrypted)
Web3: W1 (file-signed)

Access Token (dtAC)

Domain: dtAC  
Profile: DTLAuthAC1
Required Tables:
  - PERMS: uid, scope:e(...), resource, exp:T
Optional Tables:
  - LIMITS: uid, endpoint, rpm:i, daily:i
Security: S2 (encrypted)
Web3: W1 (file-signed)

Standard Enums

# Roles (customize per application)
role:e(admin,user,guest,moderator,super,service)

# Scopes
scope:e(read,write,admin,delete,none)

# Token Status
token_status:e(active,revoked,expired,pending)

# MFA
mfa:e(verified,pending,disabled,required)

SDK Type Parsing Examples

See how each data type is handled by the SDKs:

🐍 Python - Type Conversion

from dtl_parser import DTLParser, create_table, DtlType

parser = DTLParser()

# Parse DTL with all types
dtl = """
@dtlv1.0^dtWEB^pDemo^c0^s0^w0^hash
@sec^none^0x0^none^0

DATA|id:u,name:s,count:i,price:f,active:b,created:D,modified:T,metadata:j,tags:a(s),status:e(on,off)|1|S0|W0|C0
550e8400-e29b-41d4-a716-446655440000|Test|42|99.99|1|2025-01-15|2025-01-15T10:30:00Z|{"key":"value"}|[a,b,c]|on
"""

doc = parser.parse(dtl)
table = doc.get_table("DATA")
row = table.rows[0]

# Access typed values
print(row["id"])        # "550e8400-..." (str, UUID format)
print(row["count"])     # 42 (int)
print(row["price"])     # 99.99 (float)
print(row["active"])    # True (bool)
print(row["metadata"])  # {"key": "value"} (dict)
print(row["status"])    # "on" (validated enum)

# Check field types
for field in table.fields:
    print(f"{field.name}: {field.type.value}")
    if field.enum_values:
        print(f"  Enum values: {field.enum_values}")

📘 TypeScript - Type Safety

import { parse, DtlType, DtlField } from 'dtl-parser';

const doc = parse(dtlContent);
const table = doc.tables.find(t => t.name === 'DATA')!;
const row = table.rows[0];

// TypeScript knows these types!
const id: string = row.id;
const count: number = row.count;      // Parsed as number
const price: number = row.price;      // Parsed as number
const active: boolean = row.active;   // Parsed as boolean
const metadata: object = row.metadata; // Parsed JSON
const status: string = row.status;    // Validated enum

// Check enum fields
table.fields.forEach((field: DtlField) => {
    if (field.type === DtlType.ENUM && field.enumValues) {
        console.log(`${field.name} allows: ${field.enumValues.join(', ')}`);
    }
});

💜 C# - Strong Typing

using Dtlaz.Parser;

var parser = new DtlParser();
var doc = parser.Parse(dtlContent);
var table = doc.GetTable("DATA");
var row = table.Rows[0];

// Access typed values
var id = (string)row["id"];           // UUID string
var count = (int)row["count"];       // Parsed int
var price = (double)row["price"];    // Parsed double
var active = (bool)row["active"];    // Parsed bool
var status = (string)row["status"];  // Validated enum

// Find enum fields
foreach (var field in table.Fields.Where(f => f.Type == DtlType.Enum))
{
    Console.WriteLine($"{field.Name} allows: {string.Join(\", \", field.EnumValues!)}");
}