Implementation:Ollama Ollama Llama Json Schema To Grammar API

Knowledge Sources	Ollama
Domains	Grammar, Structured Output
Last Updated	2025-02-15 00:00 GMT

Overview

Header declaring the public API for converting JSON Schema definitions to GBNF grammar strings, plus helper types for schema probing and custom grammar construction.

Description

Declares json_schema_to_grammar() as the primary conversion function taking a JSON schema and returning a GBNF grammar string. Provides common_schema_info for probing schema structure (ref resolution, string type detection) with a pimpl pattern via common_schema_converter. Defines common_grammar_builder as a callback-based interface for custom grammar construction with add_rule, add_schema, and resolve_refs function objects. Also declares gbnf_format_literal for escaping string literals and build_grammar for building grammars from callbacks.

Usage

Include this header when code needs to convert JSON schemas to grammars for constrained generation, or when building custom grammars programmatically.

Code Reference

Source Location

• Repository: Ollama
• File: llama/llama.cpp/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 {
    std::unique_ptr<common_schema_converter> impl_;
public:
    common_schema_info();
    ~common_schema_info();
    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	nlohmann::ordered_json	Yes	JSON Schema to convert to grammar
force_gbnf	bool	No	Whether to force GBNF format output
literal	std::string	Yes	String literal to escape for GBNF (for gbnf_format_literal)

Outputs

Name	Type	Description
grammar	std::string	GBNF grammar string
resolves_to_string	bool	Whether the schema resolves to a string type

Usage Examples

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

// Simple schema to grammar conversion
nlohmann::ordered_json schema = {{"type", "string"}};
std::string grammar = json_schema_to_grammar(schema);

// Build a custom grammar
std::string custom = build_grammar([](const common_grammar_builder & builder) {
    builder.add_rule("root", "\"hello\" | \"world\"");
});

// Format a literal for GBNF
std::string escaped = gbnf_format_literal("hello world");

Related Pages

• Principle:Ollama_Ollama_Structured_Output