Implementation:Ggml org Llama cpp Json Schema To Grammar Header

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

Overview

Declares the public interface for converting JSON Schemas to GBNF grammars and for probing schema structure.

Description

This header exposes `json_schema_to_grammar()` for direct schema-to-grammar conversion, `common_schema_info` for probing schema type constraints (e.g., whether it resolves to a string), `common_grammar_builder` with function callbacks for incrementally adding rules and schemas, and `build_grammar()` for constructing a complete grammar via a builder callback pattern. It also provides `gbnf_format_literal()` for escaping literal strings in GBNF format. The `common_grammar_options` struct allows configuring grammar generation behavior such as dotall mode.

Usage

Use this header when implementing constrained generation from JSON Schema. It is used by the server and chat subsystems to enforce structured output from models, ensuring that generated tokens conform to a specified JSON Schema.

Code Reference

Source Location

• Repository: Ggml_org_Llama_cpp
• File: common/json-schema-to-grammar.h
• Lines: 1-43

Signature

std::string json_schema_to_grammar(const nlohmann::ordered_json & schema,
                                   bool force_gbnf = false);

class common_schema_info {
public:
    common_schema_info();
    ~common_schema_info();
    common_schema_info(common_schema_info &&) noexcept;
    common_schema_info & operator=(common_schema_info &&) noexcept;
    void resolve_refs(nlohmann::ordered_json & schema);
    bool resolves_to_string(const nlohmann::ordered_json & schema);
};

struct common_grammar_builder {
    std::function<std::string(const std::string &, const std::string &)> add_rule;
    std::function<std::string(const std::string &, const nlohmann::ordered_json &)> add_schema;
    std::function<void(nlohmann::ordered_json &)> resolve_refs;
};

struct common_grammar_options {
    bool dotall = false;
};

std::string gbnf_format_literal(const std::string & literal);

std::string build_grammar(const std::function<void(const common_grammar_builder &)> & cb,
                           const common_grammar_options & options = {});

Import

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

I/O Contract

Inputs

Name	Type	Required	Description
schema	const nlohmann::ordered_json &	Yes	JSON Schema object to convert to GBNF grammar
force_gbnf	bool	No	Force GBNF output format (default false)
literal	const std::string &	Yes	Literal string to escape for GBNF format
cb	const std::function<void(const common_grammar_builder &)> &	Yes	Builder callback for incremental grammar construction
options	const common_grammar_options &	No	Grammar generation options (default: dotall=false)

Outputs

Name	Type	Description
json_schema_to_grammar return	std::string	GBNF grammar string that enforces the JSON Schema
resolves_to_string return	bool	True if the schema ultimately resolves to a string type
gbnf_format_literal return	std::string	Escaped literal string suitable for use in GBNF rules
build_grammar return	std::string	Complete GBNF grammar built via the builder callback

Usage Examples

#include "json-schema-to-grammar.h"
#include <nlohmann/json.hpp>

// Convert a JSON Schema to GBNF grammar
nlohmann::ordered_json schema = {
    {"type", "object"},
    {"properties", {
        {"name", {{"type", "string"}}},
        {"age", {{"type", "integer"}}}
    }},
    {"required", {"name", "age"}}
};
std::string grammar = json_schema_to_grammar(schema);

// Probe schema structure
common_schema_info info;
info.resolve_refs(schema);
bool is_string = info.resolves_to_string(schema);

// Build grammar incrementally
std::string custom_grammar = build_grammar([](const common_grammar_builder & builder) {
    builder.add_rule("root", "object");
    // ... add more rules
});

Related Pages

• Principle:Ggml_org_Llama_cpp_Constrained_Generation