Welcome to USL - Unified Specification Language¶

What is USL?¶

USL (Unified Specification Language) is a revolutionary policy-driven development framework that brings formal verification, layered architecture, and multi-target code generation into a unified workflow. Write your application specification once, and USL automatically generates secure, correct, and production-ready code.

Core Principles¶

graph LR
    A[Domain<br/>Modeling] --> B[Policy<br/>Enforcement]
    B --> C[Behavior<br/>Definition]
    C --> D[Service<br/>Implementation]
    D --> E[Code<br/>Generation]
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e9
    style E fill:#fce4ec

Policy-First: Authorization is not an afterthought—it's built into every layer of your application.

Formally Verified: Mathematical proofs ensure your invariants always hold, eliminating entire classes of bugs.

Layered Architecture: Clear separation between domain logic, policies, behavior, and services prevents architectural erosion.

Multi-Target: Generate TypeScript, Rust, Python, and more from a single specification.

Quick Example¶

Here's a complete USL application that defines a blog with secure access control:

domain Blog {
  entity Post {
    id: PostId @primary
    title: String
    content: String @secret
    author: UserId
    published: Boolean

    invariant published_has_content {
      this.published -> len(this.content) > 0
    }
  }

  entity User {
    id: UserId @primary
    role: Role
  }

  enum Role { Admin, Author, Reader }
}

policy BlogPolicy {
  actor user: User

  rule create_post {
    user.role == Role.Author || user.role == Role.Admin
  }

  rule edit_post(post: Post) {
    user.id == post.author || user.role == Role.Admin
  }

  rule read_post(post: Post) {
    post.published || user.id == post.author || user.role == Role.Admin
  }
}

behavior PostLifecycle for Post {
  initial state Draft

  state Draft {
    on publish -> Published
      requires len(this.content) > 0
      effects { this.published = true }
  }

  state Published {
    on unpublish -> Draft
      effects { this.published = false }
  }
}

service BlogService {
  action createPost(title: String, content: String) -> Post
    enforces BlogPolicy.create_post
    effects { Write(Post) }

  action editPost(postId: PostId, newContent: String) -> Post
    enforces BlogPolicy.edit_post(post)
    effects { Write(Post) }

  action readPost(postId: PostId) -> Post
    enforces BlogPolicy.read_post(post)
    effects { Read(Post) }
}

This specification:

• ✅ Defines domain entities with type-safe fields
• ✅ Enforces invariants (published posts must have content)
• ✅ Implements role-based access control
• ✅ Models state transitions with guards
• ✅ Exposes a service API with effect tracking
• ✅ Generates production code with all checks built-in

Key Features¶

🔐 Built-in Security¶

• Policy enforcement at compile-time and runtime
• Secret tracking prevents accidental data leaks
• Effect system tracks side effects and data flow
• Escape hatches with capability-based security

🎯 Correctness Guarantees¶

• Formal verification of invariants
• State machine validation ensures valid transitions
• Type safety catches errors before deployment
• Totality checking ensures all cases are covered

🏗️ Clean Architecture¶

• Layered design enforces separation of concerns
• Domain layer for business logic and entities
• Policy layer for authorization rules
• Behavior layer for state machines and workflows
• Service layer for external-facing APIs
• Escape layer for external integrations

🚀 Production Ready¶

• Multi-target code generation (TypeScript, Rust, Python)
• OpenAPI specification generation
• Docker deployment templates
• Kubernetes manifests included
• CI/CD integration examples

Installation¶

curl -fsSL https://raw.githubusercontent.com/shaifulshabuj/USL/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/shaifulshabuj/USL/main/scripts/install.ps1 | iex

git clone https://github.com/shaifulshabuj/USL.git
cd USL/compiler
cargo install --path .

Verify the installation:

usl --version

Next Steps¶

Community & Support¶

• 📖 Documentation
• 💬 Discord Community
• 🐛 Issue Tracker
• 📧 Email Support

License¶

USL is open source software licensed under the MIT License.