yuho 5.1.0

A domain-specific language for encoding legal statutes

Yuho

Yuho is a domain-specific language dedicated to simplifying legalese by providing a programmatic representation of Singapore Law.

Current applications are focused on Singapore Criminal Law but really can be applied to any jurisdiction that relies on statutes.

Rationale

The law is innately complex.

Statutes are not always easy to understand, especially for incoming law students new to legalese and its logical structure.

Criminal Law is often a foundational module most students take in their first year of law school. In particular, Singapore Criminal Law is nearly entirely statute-based, largely focusing on the Penal Code.

Yuho is a DSL that seeks to help law students better understand statutes by providing a flexible syntax which affords a programmatic representation of Singapore Criminal Law. By allowing users to decide how to represent statutory provisions in .yh code, the hope is that the statute's key elements and its underlying conditional relationships surface themselves. These representations can be coarse or granular, entirely scoped by their use-cases.

Getting into the specifics, Yuho provides the following five products.

1. Yuho, a DSL made to be readable and codeable by law students and lawyers
2. Formalised semantics for legal reasoning modelled after the syntactical patterns of the law
3. CLI tool for interacting with Yuho's primary functions in the CLI
4. LSP for editor integration with diagnostics, completion, and hover
5. Transpiler that transpiles to multiple targets

Output formats

Target	Usage
JSON	Machine-readable structured representation for tooling integration
JSON-LD	Linked data format for semantic web applications
English	Human-readable plain English explanation of statutory logic
LaTeX	PDF generation of formatted statute documents
Alloy	Formal verification with Alloy Analyzer
Mermaid	Diagrammatic representations of statutory logic (mindmap, flowchart)
GraphQL	Schema definitions for building legal statute APIs
Blocks	Visual block-based representation for drag-and-drop editing

Sold on Yuho? Check out the quickstart guide.

[!TIP] More transpilation outputs can be added. Open an issue to contribute suggestions!

Nerd stuff

For those interested, Yuho v5 provides:

• Tree-sitter based parser for robust, incremental parsing with excellent error recovery
• Full LSP implementation with diagnostics, completion, hover, go-to-definition, and references
• Property-based testing with Hypothesis for thorough validation
• Formal verification integration with Alloy and Z3
• LLM integration for statute explanation and analysis (local-first with Ollama, cloud fallback)
• MCP server exposing all functionality via Model Context Protocol

Yuho is grammatically-validated, exception-validated, and language-agnostic, transpiling from one formally-specified source of truth to multiple target outputs.

Want to find out more? See Yuho's documentation.

Documentation

• Language specification
• Grammar specification
• Formal verification
• Library statutes
• Examples

Quickstart

Yuho v5.0: Install via pip and start using immediately:

pip install yuho
yuho --help

Learn Yuho: Understand the basics in 5 minutes at 5_MINUTES.md.

Legacy versions: See archive/ for v1-v4 implementations.

Roadmap

For more details on what's being implemented in the future, refer to ROADMAP.md.

Scope

Development is currently scoped by the following statutes at SCOPE.md.

Contribute

Yuho is open-source. Contribution guidelines are found at CONTRIBUTING.md.

References

Analogues

Yuho takes much inspiration from the following projects.

• Natural L4: Language with an English-like syntax that transpiles to multiple targets, focused on codification of Singapore law at large and Contract Law in specific.
• Catala: Language syntax that explicitly mimicks logical structure of the Law, focused on general Socio-fiscal legislature in most jurisidictions.
• Blawx: User-friendly web-based tool for Rules as Code, a declarative logic knowledge representation tool for encoding, testing and using rules.
• Morphir: Technology agnostic toolkit for digitisation of business models and their underlying decision logic, enabling automation in fintech.
• OpenFisca: Open-source platform for modelling social policies through tax and benefits systems across jurisdictions.
• Docassemble: Document automation system for generating guided interview documents through a question-and-answer interface.
• Akoma Ntoso: Standardised XML schema for representing parliamentary, legislative and judiciary documents across jurisdictions.

Research

Yuho stands on the shoulders of past research and academia.

• A Logic for Statutes by Sarah B Lawsky
• An End-to-End Pipeline from Law Text to Logical Formulas by Aarne Ranta, Inari Listenmaa, Jerrold Soh and Meng Weng Wong
• Symbolic and automatic differentiation of languages by Conal Elliott
• Legal Rules, Legal Reasoning, and Nonmonotonic Logic by Adam W Rigoni
• Law and logic: A review from an argumentation perspective by Henry Prakken and Giovanni Sartor
• Rules as code: Seven levels of digitisation by Meng Weng Wong
• Defeasible semantics for L4 by Guido Governatori and Meng Weng Wong
• CLAWs and Effect by Alexis N Chun
• The LKIF Core Ontology of Basic Legal Concepts by Rinke Hoekstra, Joost Breuker, Marcello Di Bello and Alexander Boer
• ChatGPT, Large Language Models, and Law by Harry Surden
• Scaling Laws for Neural Language Models by Jared Kaplan, Sam McCandlish, Tom Henighan, Tom B Brown, Benjamin Chess, Rewon Child, Scott Gray, Alec Radford, Jeffrey Wu and Dario Amodei
• Large Language Models in Law: A Survey by Jinqi Lai, Wensheng Gan, Jiayang Wu, Zhenlian Qi and Philip S Yu
• Automating Defeasible Reasoning in Law with Answer Set Programming by Lim How Khang, Avishkar Mahajan, Martin Strecker and Meng Weng Wong
• User Guided Abductive Proof Generation for Answer Set Programming Queries by Avishkar Mahajan, Martin Strecker and Meng Weng Wong
• Computer-Readable Legislation Project: What might an IDE-like drafting tool look like? by Matthew Waddington, Laurence Diver and Tin San Leon Qiu
• Normalized Legal Drafting and the Query Method by Layman E Allen and C Rudy Engholm
• An IDE-like tool for legislative drafting by crlp-jerseyldo.github.io
• The Grammar And Structure Of Legal Texts by Risto Hiltunen
• Does Justice Have a Syntax? by Steven L Winter
• The syntax of legal exceptions: how the absence of proof is a proof of absence thereof by Kyriakos N Kotsoglou
• The British Nationality Act as a logic program by M Sergot, F Sadri, R Kowalski, F Kriwaczek, P Hammond and H T Cory