Skip to content

Frequently Asked Questions

General Questions

What is USL?

USL (Unified Specification Language) is a policy-driven development framework that combines domain modeling, authorization policies, state machines, and code generation into a unified workflow. Write your specification once, and USL generates secure, correct, and production-ready code for multiple platforms.

How is USL different from...?

Django / Rails / Laravel

Traditional web frameworks provide tools and libraries, but don't enforce architecture or verify correctness. USL:

  • ✅ Enforces layered architecture at compile time
  • ✅ Verifies security policies mathematically
  • ✅ Proves invariants always hold
  • ✅ Prevents architectural erosion
  • ❌ Requires learning a new DSL

Prisma / TypeORM / Entity Framework

ORMs handle database interactions but don't address authorization, state machines, or formal verification. USL:

  • ✅ Includes authorization in the domain model
  • ✅ Verifies state transitions preserve invariants
  • ✅ Generates complete API, not just database layer
  • ❌ Less flexible for ad-hoc queries

AWS CDK / Terraform

Infrastructure-as-code tools define deployment, while USL defines application logic. They complement each other:

  • USL: Application specification and code generation
  • IaC: Infrastructure provisioning and deployment

Use USL to generate code, then deploy with your preferred IaC tool.

Is USL production-ready?

Current Status (v1.0):

✅ Ready for production: - Core compiler and type system - TypeScript code generation - Basic policy enforcement - State machine verification

⚠️ In beta: - Rust code generation - Python code generation - Advanced proof features - Enterprise compliance features

🚧 Coming soon: - Go code generation - GraphQL support - Real-time features

See Roadmap for details.

What are the performance implications?

USL-generated code has minimal overhead:

  • Authorization checks: ~0.1ms per request (cached)
  • Invariant checks: Zero runtime cost (verified at compile time)
  • State transitions: Same as hand-written code
  • Generated code: Comparable to hand-written TypeScript/Rust

Benchmarks show USL apps perform within 5-10% of hand-optimized code.

Technical Questions

Can I use USL with existing code?

Yes! Three integration approaches:

  1. New microservice: Write new services in USL, integrate via API
  2. Gradual migration: Generate code and import into existing project
  3. Escape hatches: Call existing code from USL using escape layer

Example escape hatch:

escape LegacyUser {
  capability Database.Query

  function getUser(id: String) -> Result[User, Error]
    adapter typescript {
      implementation "./legacy/users.ts"
      function "fetchUserById"
    }
}

What databases does USL support?

USL is database-agnostic. Generated code includes:

  • PostgreSQL (recommended)
  • MySQL / MariaDB
  • SQLite
  • MongoDB
  • DynamoDB
  • Cassandra

Specify in usl.toml:

[database]
provider = "postgresql"
url = "postgresql://localhost/mydb"

Can I customize generated code?

Yes, several options:

  1. Templates: Customize code generation templates
  2. Escape hatches: Write custom code where needed
  3. Hooks: Pre/post-generation scripts
  4. Extend generated code: Add methods to generated classes

DO NOT modify generated files directly—changes will be overwritten.

How does USL handle authentication?

USL handles authorization (who can do what), not authentication (who are you).

Use standard auth solutions:

  • Auth0
  • Firebase Auth
  • Keycloak
  • OAuth2 / OIDC
  • Custom JWT

USL policies check the authenticated user:

policy MyPolicy {
  actor user: User  // Assumes authenticated

  rule can_delete(post: Post) {
    user.id == post.authorId
  }
}

Can I write unit tests for USL code?

Yes! USL has built-in testing:

spec MyTests {
  test "users can delete own posts" {
    let user = User { id: "user1" }
    let post = Post { authorId: "user1" }

    assert canDelete(user, post) == true
  }

  property "all posts have authors" {
    forall post in Post {
      exists user in User {
        user.id == post.authorId
      }
    }
  }
}

Run tests:

usl test my-app.usl

Generated code also includes standard unit tests.

How does versioning work?

USL supports API versioning:

@version("1.0")
service BlogServiceV1 {
  action getPosts() -> List[Post]
}

@version("2.0")
service BlogServiceV2 {
  action getPosts(filters: Filters) -> PagedList[Post]
}

Generate both versions simultaneously.

Can I use third-party libraries?

Yes, via escape hatches:

escape Stripe {
  capability Payment.Process

  function charge(amount: Money, token: String) -> Result[Charge, Error]
    adapter typescript {
      implementation "stripe"
      configuration {
        apiKey: env.STRIPE_API_KEY
      }
    }
}

Learning Questions

How long does it take to learn USL?

Depends on background:

  • Familiar with typed languages (TypeScript, Rust): 2-3 days
  • From dynamic languages (Python, Ruby): 1 week
  • New to programming: 2-3 weeks

Our tutorial series takes ~8 hours total.

What background do I need?

Required: - Basic programming (variables, functions, conditionals) - Understanding of web APIs (REST/HTTP)

Helpful: - Typed languages (TypeScript, Java, C#) - Database concepts (SQL, ORMs) - State machines

Not required: - Formal methods or theorem proving - Compiler design - Category theory

Are there example projects?

Yes! See examples repository:

  • Blog: Posts, comments, authentication
  • E-commerce: Orders, payments, inventory
  • Healthcare: HIPAA-compliant records system
  • Task Manager: Projects, tasks, team collaboration
  • Forum: Threads, posts, moderation
  • Banking: Accounts, transactions, compliance

How do I get help?

  1. Documentation: You're reading it! Use search box
  2. Discord: Join our community
  3. GitHub Issues: Report bugs or request features
  4. Stack Overflow: Tag questions with usl-lang
  5. Office Hours: Monthly Q&A sessions (announced on Discord)

Design Questions

Why a DSL instead of a library?

Benefits of DSL: - Static verification (can't be done with runtime library) - Multi-target code generation - Enforced architecture - Better error messages - Tool support (language server, IDE integration)

Trade-offs: - Learning curve - Tooling ecosystem smaller than general-purpose languages - Less flexible for edge cases

We believe compile-time guarantees outweigh the costs for most applications.

Why layered architecture?

Layers enforce separation of concerns:

Domain    → Business logic and invariants
Policy    → Authorization rules
Behavior  → State machines and workflows  
Service   → External API
Escape    → External integrations

Benefits: - Easier to reason about - Prevents mixing concerns - Enables verification - Simplifies testing - Facilitates team collaboration

How does verification work?

USL uses:

  1. Type checking: Ensures type safety
  2. Effect tracking: Tracks side effects
  3. SMT solving: Proves invariants (Z3 solver)
  4. Model checking: Verifies state machines
  5. Policy analysis: Checks authorization completeness

Most verification happens at compile time, with zero runtime cost.

Can I opt out of verification?

Yes, configure in usl.toml:

[compiler]
verification = "none"  # or "basic" or "full"

none: Type checking only
basic: Types + simple invariants
full: Complete formal verification (default)

We strongly recommend keeping verification enabled.

Business Questions

What's the license?

MIT License - fully open source and free for commercial use.

Is there enterprise support?

Yes, we offer:

  • Community (free): Discord, GitHub issues, documentation
  • Professional ($2,500/year): Email support, SLA, training
  • Enterprise (custom): Dedicated support, on-site training, custom features

Contact usl@sshabuj.com for details.

Can I hire USL consultants?

Consultant directory coming soon! For now, post on Discord #jobs channel or contact usl@sshabuj.com.

Who uses USL?

USL is used by: - Startups building compliance-critical applications - Enterprises modernizing legacy systems - Government agencies requiring formal verification - Healthcare organizations needing HIPAA compliance

Case studies coming soon!

What's the business model?

USL is free and open source. Revenue comes from:

  1. Enterprise support subscriptions
  2. Training and certification
  3. Consulting services
  4. Cloud-hosted USL development environment (planned)

Core compiler remains MIT licensed forever.

Troubleshooting

Compilation is slow

Try:

# Enable incremental compilation
usl compile --incremental my-app.usl

# Reduce verification level
usl compile --verify=basic my-app.usl

# Parallel compilation
usl compile --jobs=4 my-app.usl

Generated code is too large

Options:

  1. Tree shaking: Remove unused code
  2. Optimize: Run optimizer pass
  3. Split: Generate multiple modules
usl generate --optimize --tree-shake --target typescript

Error messages are confusing

  1. Check Error Reference
  2. Run with verbose output: usl compile --verbose
  3. Ask on Discord with error code
  4. File issue if error message can be improved

Can't integrate with existing auth

Use escape hatches to call auth middleware:

escape Auth {
  function getCurrentUser() -> Result[User, AuthError]
    adapter typescript {
      implementation "./middleware/auth"
    }
}

Still Have Questions?