MOTH v1.0 Specification

Full technical specification for implementers and advanced users. This document covers all syntax rules, type systems, validation requirements, and best practices.

Abstract

MOTH (Minimal Overhead Technical Hierarchy) is a line-based notation system for technical documentation optimized for LLM context efficiency. It achieves 70-90% compression versus traditional markdown while preserving full semantic information.

Core Philosophy

MOTH is a BLUEPRINT, not a specification document. It answers "what" and "why", not "how" in exhaustive detail.

Add detail ONLY where ambiguity would cause architectural problems
Trust developers to figure out validation rules, error messages, exact formats
80% compression is the goal - if you're writing more than 200 lines, you're over-specifying
Every line should answer: "What architectural decision does this inform?"

Design Goals

Maximum information density
LLM-native parsing
Human readable/writable
Minimal syntax overhead
Self-documenting structure
Blueprint-level detail, not implementation specs

File Format

Extensions:

.moth - Primary extension
.str - Alternative (STRAND)
.spex - Specification variant

MIME Types:

text/x-moth
text/x-moth+plain

Core Syntax

Comments

# Full line comment
key:value  # Inline comment (after 2+ spaces)

Sections

[SECTION_NAME]           # Top-level, ALL_CAPS
[SECTION.subsection]     # Dot notation for hierarchy
[SECTION.sub.deep]       # Multiple levels

Key-Value Pairs

key:value                     # Primary pattern
multi_word_key:value          # Underscores for spaces
key:"value:with:colons"       # Quotes for special chars

Type System

Primitives:

str; int; float; bool; uuid; ts; hex; vec; bits; blob

Collections:

[type] - Array
{key:type} - Object/map
type|type2 - Union

Need the full spec?

The complete specification with all syntax rules, validation requirements, and examples is available in the documentation repository.

View on GitHub →