Implementation:Guardrails ai Guardrails Rail Schema

Knowledge Sources	Guardrails
Domains	Schema, RAIL Specification, XML Processing
Last Updated	2026-02-14 00:00 GMT

Overview

The Rail Schema module provides bidirectional conversion between the RAIL XML specification and JSON Schema, enabling Guardrails to parse RAIL documents into structured schemas and convert JSON Schemas back into RAIL XML output elements.

Description

This module implements the two fundamental transformation directions of the Guardrails schema system:

RAIL to JSON Schema

The rail_string_to_schema and rail_file_to_schema functions parse RAIL XML documents and produce a ProcessedSchema object containing:

A JSON Schema representation of the output structure.
A list of ValidatorReference objects extracted from RAIL validators attributes.
A ValidatorMap mapping JSON paths to their assigned Validator instances.
GuardExecutionOptions including extracted messages and reask messages.
The determined output type (STRING, LIST, or DICT).

The parse_element function recursively walks RAIL XML elements and maps RAIL type tags (string, integer, float, bool, date, time, datetime, percentage, enum, list, object, choice) to their corresponding JSON Schema ModelSchema representations.

Validator extraction is performed by get_validators and extract_validators, which parse semicolon-delimited validator specifications from RAIL attributes, resolve on-fail handlers, and populate the ProcessedSchema.

JSON Schema to RAIL

The json_schema_to_rail_output function converts a JSON Schema dictionary back into a canonical RAIL XML output string. This uses a suite of builder functions:

build_element -- the main dispatcher that routes to type-specific builders.
build_object_element -- handles objects with support for allOf, oneOf, anyOf, and discriminated unions.
build_list_element -- handles arrays and their item schemas.
build_string_element -- handles strings, enums, dates, times, and formatted types.
build_choice_case / build_choice_case_element_from_if / build_choice_case_element_from_discriminator -- handle conditional schemas and discriminated unions using RAIL's choice/case pattern.

A Format dataclass is used to decompose JSON Schema format strings back into their RAIL internal types and custom format components.

Usage

Use rail_string_to_schema or rail_file_to_schema when parsing RAIL XML into the internal schema representation used by Guards. Use json_schema_to_rail_output when you need to serialize a JSON Schema back to RAIL format for prompt construction or debugging.

Code Reference

Source Location

Repository: Guardrails
File: guardrails/schema/rail_schema.py
Lines: 1-934

Signature

# RAIL to JSON Schema
def rail_string_to_schema(rail_string: str) -> ProcessedSchema: ...
def rail_file_to_schema(file_path: str) -> ProcessedSchema: ...
def parse_element(
    element: _Element, processed_schema: ProcessedSchema, json_path: str = "$"
) -> ModelSchema: ...
def get_validators(element: _Element) -> List[Validator]: ...
def extract_validators(
    element: _Element, processed_schema: ProcessedSchema, json_path: str
) -> None: ...
def extract_format(
    element: _Element, internal_type: RailTypes, internal_format_attr: str
) -> Optional[str]: ...

# JSON Schema to RAIL
def json_schema_to_rail_output(
    json_schema: Dict[str, Any], validator_map: ValidatorMap
) -> str: ...
def build_element(
    json_schema: Dict[str, Any], validator_map: ValidatorMap, *,
    json_path: str = "$", elem=SubElement, tag_override=None,
    parent=None, required="true", attributes=None,
) -> _Element: ...
def build_object_element(...) -> _Element: ...
def build_list_element(...) -> _Element: ...
def build_string_element(...) -> _Element: ...
def build_choice_case(...) -> _Element: ...
def build_choice_case_element_from_if(...) -> _Element: ...
def build_choice_case_element_from_discriminator(...) -> _Element: ...

# Utility
@dataclass
class Format:
    internal_type: Optional[RailTypes] = None
    internal_format_attr: Optional[str] = None
    custom_format: Optional[str] = None

def extract_internal_format(format: str) -> Format: ...
def init_elem(elem=SubElement, *, _tag: str, attrib: Dict, _parent=None) -> _Element: ...

Import

from guardrails.schema.rail_schema import rail_string_to_schema, rail_file_to_schema
from guardrails.schema.rail_schema import json_schema_to_rail_output

I/O Contract

Inputs

rail_string_to_schema

Name	Type	Required	Description
rail_string	`str`	Yes	A valid RAIL XML string containing at minimum an `<output>` element, optionally with `<messages>` and `<reask_messages>`.

rail_file_to_schema

Name	Type	Required	Description
file_path	`str`	Yes	Path to a `.rail` file on disk.

json_schema_to_rail_output

Name	Type	Required	Description
json_schema	`Dict[str, Any]`	Yes	A JSON Schema dictionary (may contain `$ref` pointers).
validator_map	`ValidatorMap`	Yes	A mapping of JSON paths to lists of Validator instances.

Outputs

Function	Return Type	Description
rail_string_to_schema	`ProcessedSchema`	Contains `json_schema`, `validators` list, `validator_map`, `output_type`, and `exec_opts`.
rail_file_to_schema	`ProcessedSchema`	Same as above, loaded from a file path.
json_schema_to_rail_output	`str`	A canonical XML string representing the RAIL `<output>` element.

Usage Examples

from guardrails.schema.rail_schema import rail_string_to_schema

rail_xml = """
<rail version="0.1">
  <output type="object">
    <string name="company_name" description="Name of the company"
            validators="hub://guardrails/regex_match"
            on-fail-regex_match="reask" />
    <integer name="employee_count" description="Number of employees" />
    <list name="products" description="List of products">
      <string description="Product name" />
    </list>
  </output>
</rail>
"""

processed = rail_string_to_schema(rail_xml)
# processed.json_schema -> JSON Schema dict
# processed.validators -> list of ValidatorReference
# processed.validator_map -> {"$.company_name": [RegexMatch(...)]}
# processed.output_type -> OutputTypes.DICT

from guardrails.schema.rail_schema import json_schema_to_rail_output

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "description": "The name"},
        "age": {"type": "integer", "description": "The age"},
    },
    "required": ["name", "age"],
}

rail_output = json_schema_to_rail_output(schema, validator_map={})
# Returns XML string: <output><string name="name" .../><integer name="age" .../></output>

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment