Implementation:Ggml org Llama cpp Json Schema To Grammar

Knowledge Sources	Ggml_org_Llama_cpp
Domains	JSON, Grammar
Last Updated	2026-02-15 00:00 GMT

Overview

Converts JSON Schema definitions into GBNF (GGML BNF) grammar rules that constrain LLM token generation to produce valid JSON matching the schema.

Description

This module implements a common_schema_converter that recursively walks JSON Schema structures (objects, arrays, strings, numbers, enums, oneOf/anyOf, etc.) and generates corresponding GBNF grammar rules. It uses helper functions like build_repetition for quantifiers and _build_min_max_int for numeric range constraints. The converter handles $ref resolution, pattern properties, and nested schemas. A TrieNode is used for optimizing literal alternatives into efficient grammar rules.

Usage

Use this module for structured/constrained generation, allowing the server to enforce that model output conforms to a user-specified JSON Schema. This is essential for tool calling and function-calling APIs where outputs must be valid JSON of a specific shape.

Code Reference

Source Location

• Repository: Ggml_org_Llama_cpp
• File: common/json-schema-to-grammar.cpp
• Lines: 1-1153

Signature

static std::string build_repetition(
    const std::string & item_rule,
    int min_items,
    int max_items,
    const std::string & separator_rule = "");

static void _build_min_max_int(
    int64_t min_value,
    int64_t max_value,
    std::stringstream & out,
    int decimals_left = 16,
    bool top_level = true);

// common_schema_converter class (internal)
// Recursively converts JSON Schema to GBNF rules

Import

#include "json-schema-to-grammar.h"
#include "common.h"
#include <nlohmann/json.hpp>
#include <algorithm>
#include <map>
#include <regex>
#include <sstream>

I/O Contract

Inputs

Name	Type	Required	Description
item_rule	std::string	Yes	GBNF rule string for individual items in repetition patterns
min_items	int	Yes	Minimum number of repetitions
max_items	int	Yes	Maximum number of repetitions (INT_MAX for unbounded)
separator_rule	std::string	No	Optional separator rule between items (e.g., comma)
min_value / max_value	int64_t	Yes	Numeric range constraints for integer schema types
json_schema	nlohmann::json	Yes	The JSON Schema object to convert to GBNF grammar

Outputs

Name	Type	Description
grammar	std::string	Complete GBNF grammar string constraining generation to valid JSON matching the schema
repetition_rule	std::string	GBNF repetition pattern string from build_repetition

Usage Examples

#include "json-schema-to-grammar.h"

// Convert a JSON Schema to a GBNF grammar string
nlohmann::json schema = {
    {"type", "object"},
    {"properties", {
        {"name", {{"type", "string"}}},
        {"age", {{"type", "integer"}, {"minimum", 0}, {"maximum", 150}}}
    }},
    {"required", {"name", "age"}}
};

std::string grammar = common_json_schema_to_grammar(schema);
// grammar now contains GBNF rules that constrain generation to valid JSON
// matching the schema: {"name": "<string>", "age": <0-150>}

Related Pages

• Principle:Ggml_org_Llama_cpp_ConstrainedGeneration