UP

Unified Properties

UP is a modern, human-friendly data serialization format designed to be simpler than YAML, more powerful than JSON, and more readable than TOML. It combines the best features of existing formats while introducing unique capabilities like dedenting and type annotations.

Quick Links:

• Syntax Reference
• Implementations
• Grammar
• Spec Repo

Why UP?

• Simple — Cleaner syntax than YAML, no tricky indentation rules
• Powerful — Type annotations, multiline strings, nested structures, tables
• Readable — Human-friendly format that's easy to write and maintain
• Fast — Simple parser design, efficient implementations
• Flexible — Support for embedded code blocks with language hints
• Unique — Dedenting feature for clean embedded content

Features

Type Annotations

# Single-word values (no quotes needed)
name Alice
age!int 30
active!bool true
url!uri https://example.com
created!ts 2025-10-05T12:00:00Z
timeout!dur 30s

# Multi-word values (two options)
title "Senior Engineer"     # Option 1: Use quotes
description: A modern data serialization format  # Option 2: Use colon suffix

Blocks (Nested Structures)

server {
  host localhost
  port!int 8080
  database {
    host db.example.com
    port!int 5432
  }
}

Lists

# Multiline lists
items [
apple
banana
cherry
]

# Inline lists
colors [red, green, blue]

Line-Oriented Values

# Use : suffix to capture the entire line as a value
name: John Doe
title: Senior Software Engineer
message: Hello, World! This is a complete sentence.

# Works with type annotations
description!string: A modern, human-friendly data serialization format
count!int: 42

# Traditional quoted syntax also works
name "John Doe"

Multiline Strings with Language Hints

script!bash ```bash
#!/bin/bash
echo "Hello, World!"
```

config ```json
{
  "key": "value",
  "number": 42
}
```

Dedenting (Unique Feature!)

# Remove 4 leading spaces from each line
code!4 ```python
    def hello():
        print("world")
```

# Becomes:
# def hello():
#     print("world")

Tables

users!table {
  columns [id, name, email, age]
  rows {
    [1, Alice, alice@example.com, 30]
    [2, Bob, bob@example.com, 25]
    [3, Carol, carol@example.com, 35]
  }
}

Templates & Composition

# base.up - Common configuration
vars {
  app_name MyApp
  default_port!int 8080
}

app_name $vars.app_name
server {
  port $vars.default_port
}

# production.up - Environment-specific
config!base base.up

server!overlay {
  host production.example.com
  replicas!int 10
}

No string templating hell! Just declarative composition using ! annotations. See TEMPLATING.md for full documentation.

Dynamic Namespaces

!use [time, id, faker, random]

test_user {
  id $id.uuid
  name $faker.name
  email $faker.email
  created_at $time.now
  score!int $random.int(1, 100)
}

Schema Validation

# Schema validates structure and constraints
server!file://./schemas/server.up-schema {
  host localhost
  port!int 8080
  timeout!dur 30s
}

# Or use schema registry
server!https://schemas.uplang.org/server/1.0.0 {
  host example.com
  port!int 443
  tls_enabled!bool true
}

Document Lint Directives

!lint {
  no-empty-values!level warning
  no-ambiguous-keys!level warning
  require-type-annotations!level error
}

server {
  host!string: localhost
  port!int: 8080
  enabled!bool: true
}

Implementations

Tooling

Command-Line Tools

Editor Support

Installation

# UP CLI tool
go install github.com/uplang/tools/up@latest

# Language Server
go install github.com/uplang/tools/language-server@latest

Usage

# Parse a UP file and output as JSON
up parse -i config.up --pretty

# Validate UP syntax
up validate -i config.up

# Format a UP file
up format -i config.up -o formatted.up

# Process templates
up template process -i config/production.up -o output.up

Example Document

# Application configuration
app_name MyApp
version 1.0.0
debug!bool false

# Server settings
server {
  host 0.0.0.0
  port!int 8080
  tls_enabled!bool true
}

# Database configuration
database {
  driver postgres
  host db.example.com
  port!int 5432
  max_connections!int 50
}

# Feature flags
features {
  new_ui!bool true
  beta_api!bool false
}

# API endpoints
endpoints [
/health
/api/v1/users
/api/v1/products
]

Comparison with Other Formats

Ecosystem

• spec — Language specification and grammar
• tools — CLI tools and language server
• ns — Official namespace plugins
• vscode-up — VS Code extension
• intellij-up — IntelliJ IDEA plugin

Documentation

Language Specification

• Syntax Reference — Complete syntax guide
• Templating — Template composition and variables
• Schema Validation — Schema definition and validation
• UP-JSON — JSON representation format
• Changelog — Version history
• Contributing — Contribution guidelines

Namespaces

• Built-in Namespaces — time, id, string, etc.
• Dynamic Namespaces — Dynamic variables and list generation
• Namespace Plugins — Creating custom namespaces
• Namespace Security — Security considerations

Grammar Specifications

• EBNF Specification
• Lexer Specification
• ANTLR4 Grammar
• PEG Grammar
• Tree-sitter Grammar

UP: Better than JSON. Simpler than YAML. More powerful than TOML.

License: MIT