# String Schema
A simple, LLM-friendly schema definition library for Python that converts intuitive string syntax into structured data schemas.
## 🚀 Quick Start
### Installation
```bash
pip install string-schema
```
### 30-Second Example
```python
from string_schema import string_to_json_schema
# Define a schema with simple, readable syntax
schema = string_to_json_schema("name:string, email:email, age:int?")
# Get a complete JSON Schema ready for validation
print(schema)
# {
# "type": "object",
# "properties": {
# "name": {"type": "string"},
# "email": {"type": "string", "format": "email"},
# "age": {"type": "integer"}
# },
# "required": ["name", "email"]
# }
```
### Create Pydantic Models Directly
```python
from string_schema import string_to_model
# Create Pydantic model from string syntax
UserModel = string_to_model("name:string, email:email, age:int?")
# Use immediately
user = UserModel(name="Alice", email="alice@example.com")
print(user.model_dump_json()) # {"name": "Alice", "email": "alice@example.com"}
```
## 🎯 What String Schema Does
String Schema takes human-readable text descriptions and converts them into structured schemas for data validation, extraction, and API documentation. Perfect for LLM data extraction, API development, and configuration validation.
**Input:** Human-readable string syntax
**Output:** JSON Schema, Pydantic models, or OpenAPI specifications
## 🚀 Core Functions & Use Cases
### 📝 Schema Conversion Matrix
**Forward Conversions (Source → Target):**
| Function | Input | Output | Use Case |
| -------------------------- | ---------------- | -------------------- | ------------------------------------------- |
| `string_to_json_schema()` | String syntax | JSON Schema dict | **Main conversion** - string to JSON Schema |
| `string_to_model()` | String syntax | Pydantic model class | **Direct path** - string to Pydantic model |
| `string_to_model_code()` | String syntax | Python code string | **Code generation** - for templates |
| `string_to_openapi()` | String syntax | OpenAPI schema dict | **Direct path** - string to OpenAPI |
| `json_schema_to_model()` | JSON Schema dict | Pydantic model class | When you already have JSON Schema |
| `json_schema_to_openapi()` | JSON Schema dict | OpenAPI schema dict | When you already have JSON Schema |
**Reverse Conversions (Target → Source):**
| Function | Input | Output | Use Case |
| -------------------------- | ---------------- | ---------------- | ------------------------------------------ |
| `model_to_string()` | Pydantic model | String syntax | **Schema introspection** - model to string |
| `model_to_json_schema()` | Pydantic model | JSON Schema dict | **Export** - model to JSON Schema |
| `json_schema_to_string()` | JSON Schema dict | String syntax | **Migration** - JSON Schema to string |
| `openapi_to_string()` | OpenAPI schema | String syntax | **Import** - OpenAPI to string |
| `openapi_to_json_schema()` | OpenAPI schema | JSON Schema dict | **Conversion** - OpenAPI to JSON Schema |
### 🔍 Data Validation Functions
| Function | Input | Output | Use Case |
| -------------------------- | ------------- | ----------------- | --------------------------------- |
| `validate_to_dict()` | Data + schema | Validated dict | **API responses** - clean dicts |
| `validate_to_model()` | Data + schema | Pydantic model | **Business logic** - typed models |
| `validate_string_syntax()` | String syntax | Validation result | Check syntax and get feedback |
### 🎨 Function Decorators
| Decorator | Purpose | Returns | Use Case |
| ------------------ | ---------------------- | -------------- | ------------------ |
| `@returns_dict()` | Auto-validate to dict | Validated dict | **API endpoints** |
| `@returns_model()` | Auto-validate to model | Pydantic model | **Business logic** |
### 🔧 Utility Functions
| Function | Purpose | Returns | Use Case |
| --------------------------------- | ------------------- | ------------------ | ------------------------ |
| `get_model_info()` | Model introspection | Model details dict | **Debugging & analysis** |
| `validate_schema_compatibility()` | Schema validation | Compatibility info | **Schema validation** |
### 🎯 Key Scenarios
- **🤖 LLM Data Extraction**: Define extraction schemas that LLMs can easily follow
- **🔧 API Development**: Generate Pydantic models and OpenAPI docs from simple syntax
- **✅ Data Validation**: Create robust validation schemas with minimal code
- **🌍 Timezone-Aware APIs**: Automatic UTC conversion for consistent datetime handling
- **📋 Configuration**: Define and validate application configuration schemas
- **🔄 Data Transformation**: Convert between different schema formats
### ✅ Validate Data
```python
from string_schema import validate_to_dict, validate_to_model
# Example raw data (from API, user input, etc.)
raw_data = {
"name": "John Doe",
"email": "john@example.com",
"age": "25", # String that needs conversion
"extra_field": "ignored" # Will be filtered out
}
# Validate to clean dictionaries (perfect for API responses)
user_dict = validate_to_dict(raw_data, "name:string, email:email, age:int?")
print(user_dict) # {"name": "John Doe", "email": "john@example.com", "age": 25}
# Validate to typed models (perfect for business logic)
user_model = validate_to_model(raw_data, "name:string, email:email, age:int?")
print(user_model.name) # "John Doe" - Full type safety
print(user_model.age) # 25 - Converted to int
# 🌍 Automatic timezone handling for datetime fields
from datetime import datetime
event_data = {"name": "Meeting", "start_time": datetime(2025, 8, 13, 14, 30)}
event_dict = validate_to_dict(event_data, "name:string, start_time:datetime")
print(event_dict) # {"name": "Meeting", "start_time": "2025-08-13T14:30:00+00:00"}
```
### 🎨 Function Decorators
```python
from string_schema import returns_dict, returns_model
import uuid
# Auto-validate function returns to dicts
@returns_dict("id:string, name:string, active:bool")
def create_user(name):
# Input: "Alice"
# Function returns unvalidated dict
return {"id": str(uuid.uuid4()), "name": name, "active": True, "extra": "ignored"}
# Output: {"id": "123e4567-...", "name": "Alice", "active": True}
# Note: 'extra' field filtered out, types validated
# Auto-validate function returns to models
@returns_model("name:string, email:string")
def process_user(raw_input):
# Input: {"name": "Bob", "email": "bob@test.com", "junk": "data"}
# Function returns unvalidated dict
return {"name": raw_input["name"], "email": raw_input["email"], "junk": "data"}
# Output: UserModel(name="Bob", email="bob@test.com")
# Note: Returns typed Pydantic model, 'junk' field filtered out
# Usage examples:
user_dict = create_user("Alice") # Returns validated dict
user_model = process_user({"name": "Bob", "email": "bob@test.com"}) # Returns Pydantic model
print(user_model.name) # "Bob" - Full type safety
```
### 🌐 FastAPI Integration
```python
from string_schema import string_to_model, returns_dict
# Create models for FastAPI
UserRequest = string_to_model("name:string, email:email")
@app.post("/users")
@returns_dict("id:int, name:string, email:string")
def create_user_endpoint(user: UserRequest):
return {"id": 123, "name": user.name, "email": user.email}
```
**Features**: Arrays `[{name:string}]`, nested objects `{profile:{bio:text?}}`, enums, constraints, decorators.
[📖 **Complete Documentation**](docs/pydantic-utilities.md)
## 🎓 More Examples
### 🌱 Simple Example - Basic User Data
```python
from string_schema import string_to_json_schema
# Define schema using intuitive string syntax
schema = string_to_json_schema("""
name:string(min=1, max=100),
email:email,
age:int(0, 120)?,
active:bool
""")
# Result: JSON Schema dictionary ready for validation
print(schema)
# {
# "type": "object",
# "properties": {
# "name": {"type": "string", "minLength": 1, "maxLength": 100},
# "email": {"type": "string", "format": "email"},
# "age": {"type": "integer", "minimum": 0, "maximum": 120},
# "active": {"type": "boolean"}
# },
# "required": ["name", "email", "active"]
# }
```
### 🌳 Moderately Complex Example - Product Data
```python
# Product with arrays and nested objects
schema = string_to_json_schema("""
{
id:uuid,
name:string,
price:number(min=0),
tags:[string]?,
inventory:{
in_stock:bool,
quantity:int?
}
}
""")
# Result: Complete JSON Schema with nested objects and arrays
print(schema) # Full JSON Schema ready for validation
```
> 📚 **For more examples and advanced syntax**, see our [detailed documentation](docs/string-syntax.md)
## 🔄 Output Formats & Results
### 🐍 Pydantic Models (Python Classes)
```python
from string_schema import string_to_model
# Direct conversion: String syntax → Pydantic model
UserModel = string_to_model("name:string, email:email, active:bool")
# Use the model for validation
user = UserModel(name="John Doe", email="john@example.com", active=True)
print(user.model_dump_json()) # {"name": "John Doe", "email": "john@example.com", "active": true}
```
### 🔧 Code Generation (For Templates & Tools)
```python
from string_schema import string_to_model_code
# Generate Pydantic model code as a string
code = string_to_model_code("User", "name:string, email:email, active:bool")
print(code)
# Output:
# from pydantic import BaseModel
# from typing import Optional
#
# class User(BaseModel):
# name: str
# email: str
# active: bool
# Perfect for code generators, templates, or saving to files
with open('models.py', 'w') as f:
f.write(code)
```
### 🌐 OpenAPI Schemas (API Documentation)
```python
from string_schema import string_to_openapi
# Direct conversion: String syntax → OpenAPI schema
openapi_schema = string_to_openapi("name:string, email:email")
print(openapi_schema)
# {
# "type": "object",
# "properties": {
# "name": {"type": "string"},
# "email": {"type": "string", "format": "email"}
# },
# "required": ["name", "email"]
# }
```
## 🔄 Reverse Conversions (Universal Schema Converter)
String Schema provides complete bidirectional conversion between all schema formats!
> **⚠️ Information Loss Notice**: Reverse conversions (from JSON Schema/OpenAPI/Pydantic back to string syntax) may lose some information due to format differences. However, the resulting schemas are designed to cover the most common use cases and maintain functional equivalence for typical validation scenarios.
### 🔍 Schema Introspection
```python
from string_schema import model_to_string, string_to_model
# Create a model first
UserModel = string_to_model("name:string, email:email, active:bool")
# Reverse engineer it back to string syntax
schema_string = model_to_string(UserModel)
print(f"Model schema: {schema_string}")
# Output: "name:string, email:email, active:bool"
```
### 📦 Migration & Import
```python
from string_schema import json_schema_to_string
# Example: Convert existing JSON Schema to String Schema syntax
json_schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"email": {"type": "string", "format": "email"},
"age": {"type": "integer"}
},
"required": ["name", "email"]
}
simple_syntax = json_schema_to_string(json_schema)
print(f"Converted: {simple_syntax}")
# Output: "name:string, email:email, age:int?"
```
### 🔧 Schema Comparison & Analysis
```python
from string_schema import string_to_model, model_to_string
# Create two versions of a model
UserV1 = string_to_model("name:string, email:email")
UserV2 = string_to_model("name:string, email:email, active:bool")
# Compare them
v1_str = model_to_string(UserV1)
v2_str = model_to_string(UserV2)
print("Schema changes:")
print(f"V1: {v1_str}") # "name:string, email:email"
print(f"V2: {v2_str}") # "name:string, email:email, active:bool"
```
## 🎨 String Syntax Reference
### Basic Types
- `string`, `int`, `number`, `bool` → Basic data types
- `email`, `url`, `datetime`, `date`, `uuid`, `phone` → Special validated types
### Field Modifiers
- `field_name:type` → Required field
- `field_name:type?` → Optional field
- `field_name:type(constraints)` → Field with validation
### Common Patterns
- `string(min=1, max=100)` → Length constraints
- `int(0, 120)` → Range constraints
- `[string]` → Simple arrays
- `[{name:string, email:email}]` → Object arrays
- `status:enum(active, inactive)` → Enum values
- `id:string|uuid` → Union types
> 📖 **Complete syntax guide**: See [docs/string-syntax.md](docs/string-syntax.md) for full reference
## ✅ Validation
```python
from string_schema import validate_string_syntax
# Validate your schema syntax
result = validate_string_syntax("name:string, email:email, age:int?")
print(f"Valid: {result['valid']}") # True
print(f"Features used: {result['features_used']}") # ['basic_types', 'optional_fields']
print(f"Field count: {len(result['parsed_fields'])}") # 3
# Example with invalid syntax
bad_result = validate_string_syntax("name:invalid_type")
print(f"Valid: {bad_result['valid']}") # False
print(f"Errors: {bad_result['errors']}") # ['Unknown type: invalid_type']
```
## 🏗️ Common Use Cases
### 🤖 LLM Data Extraction
```python
from string_schema import string_to_json_schema
# Define what data to extract
schema = string_to_json_schema("company:string, employees:[{name:string, email:email}], founded:int?")
# Use schema in LLM prompts for structured data extraction
```
### 🔧 FastAPI Development
```python
from string_schema import string_to_model
# Create model for FastAPI
UserModel = string_to_model("name:string, email:email")
# Use in FastAPI endpoints
@app.post("/users/")
async def create_user(user: UserModel):
return {"id": 123, "name": user.name, "email": user.email}
```
### 🏗️ Code Generation & Templates
```python
from string_schema import string_to_model_code
# Generate model code
code = string_to_model_code("User", "name:string, email:email")
print(code)
# Output: Complete Pydantic model class as string
# Save to file
with open('user_model.py', 'w') as f:
f.write(code)
```
### 📋 Configuration Validation
```python
from string_schema import string_to_json_schema
# Validate app configuration
config_schema = string_to_json_schema("database:{host:string, port:int}, debug:bool")
# Use for validating config files
```
## 📚 Documentation
- **[Getting Started](docs/getting-started.md)** - Quick start guide and installation
- **[String Syntax Guide](docs/string-syntax.md)** - Complete syntax reference
- **[API Reference](docs/api-reference.md)** - Full API documentation
- **[Examples](docs/examples.md)** - Practical examples and patterns
## 📋 Example Schemas
Ready-to-use schema examples are available in the `examples/` directory:
```python
# Import example schemas if needed
from string_schema.examples.presets import user_schema, product_schema
from string_schema.examples.recipes import create_ecommerce_product_schema
# Or better yet, use string syntax directly:
user_schema = string_to_json_schema("name:string, email:email, age:int?")
```
## 🧪 Testing
The library includes comprehensive tests covering all functionality:
```bash
# Run tests (requires pytest)
pip install pytest
pytest tests/
# Results: 66 tests passed, 3 skipped (Pydantic tests when not installed)
```
## 🤝 Contributing
Contributions are welcome! The codebase is well-organized and documented:
```
string_schema/
├── core/ # Core functionality (fields, builders, validators)
├── parsing/ # String parsing and syntax
├── integrations/ # Pydantic, JSON Schema, OpenAPI
└── examples/ # Built-in schemas and recipes
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
**String Schema** - Making data validation simple, intuitive, and LLM-friendly! 🚀
Raw data
{
"_id": null,
"home_page": "https://github.com/xychenmsn/string-schema",
"name": "string-schema",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Michael Chen <xychen@msn.com>",
"keywords": "schema, validation, json, llm, ai, data-extraction, pydantic",
"author": "Michael Chen",
"author_email": "Michael Chen <xychen@msn.com>",
"download_url": "https://files.pythonhosted.org/packages/82/46/e046b0bffc0aa59f0cba18c96153cab7e1fb8de3d02a0e4b4b1d918db04a/string_schema-0.1.6.tar.gz",
"platform": null,
"description": "# String Schema\n\nA simple, LLM-friendly schema definition library for Python that converts intuitive string syntax into structured data schemas.\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install string-schema\n```\n\n### 30-Second Example\n\n```python\nfrom string_schema import string_to_json_schema\n\n# Define a schema with simple, readable syntax\nschema = string_to_json_schema(\"name:string, email:email, age:int?\")\n\n# Get a complete JSON Schema ready for validation\nprint(schema)\n# {\n# \"type\": \"object\",\n# \"properties\": {\n# \"name\": {\"type\": \"string\"},\n# \"email\": {\"type\": \"string\", \"format\": \"email\"},\n# \"age\": {\"type\": \"integer\"}\n# },\n# \"required\": [\"name\", \"email\"]\n# }\n```\n\n### Create Pydantic Models Directly\n\n```python\nfrom string_schema import string_to_model\n\n# Create Pydantic model from string syntax\nUserModel = string_to_model(\"name:string, email:email, age:int?\")\n\n# Use immediately\nuser = UserModel(name=\"Alice\", email=\"alice@example.com\")\nprint(user.model_dump_json()) # {\"name\": \"Alice\", \"email\": \"alice@example.com\"}\n```\n\n## \ud83c\udfaf What String Schema Does\n\nString Schema takes human-readable text descriptions and converts them into structured schemas for data validation, extraction, and API documentation. Perfect for LLM data extraction, API development, and configuration validation.\n\n**Input:** Human-readable string syntax\n**Output:** JSON Schema, Pydantic models, or OpenAPI specifications\n\n## \ud83d\ude80 Core Functions & Use Cases\n\n### \ud83d\udcdd Schema Conversion Matrix\n\n**Forward Conversions (Source \u2192 Target):**\n\n| Function | Input | Output | Use Case |\n| -------------------------- | ---------------- | -------------------- | ------------------------------------------- |\n| `string_to_json_schema()` | String syntax | JSON Schema dict | **Main conversion** - string to JSON Schema |\n| `string_to_model()` | String syntax | Pydantic model class | **Direct path** - string to Pydantic model |\n| `string_to_model_code()` | String syntax | Python code string | **Code generation** - for templates |\n| `string_to_openapi()` | String syntax | OpenAPI schema dict | **Direct path** - string to OpenAPI |\n| `json_schema_to_model()` | JSON Schema dict | Pydantic model class | When you already have JSON Schema |\n| `json_schema_to_openapi()` | JSON Schema dict | OpenAPI schema dict | When you already have JSON Schema |\n\n**Reverse Conversions (Target \u2192 Source):**\n\n| Function | Input | Output | Use Case |\n| -------------------------- | ---------------- | ---------------- | ------------------------------------------ |\n| `model_to_string()` | Pydantic model | String syntax | **Schema introspection** - model to string |\n| `model_to_json_schema()` | Pydantic model | JSON Schema dict | **Export** - model to JSON Schema |\n| `json_schema_to_string()` | JSON Schema dict | String syntax | **Migration** - JSON Schema to string |\n| `openapi_to_string()` | OpenAPI schema | String syntax | **Import** - OpenAPI to string |\n| `openapi_to_json_schema()` | OpenAPI schema | JSON Schema dict | **Conversion** - OpenAPI to JSON Schema |\n\n### \ud83d\udd0d Data Validation Functions\n\n| Function | Input | Output | Use Case |\n| -------------------------- | ------------- | ----------------- | --------------------------------- |\n| `validate_to_dict()` | Data + schema | Validated dict | **API responses** - clean dicts |\n| `validate_to_model()` | Data + schema | Pydantic model | **Business logic** - typed models |\n| `validate_string_syntax()` | String syntax | Validation result | Check syntax and get feedback |\n\n### \ud83c\udfa8 Function Decorators\n\n| Decorator | Purpose | Returns | Use Case |\n| ------------------ | ---------------------- | -------------- | ------------------ |\n| `@returns_dict()` | Auto-validate to dict | Validated dict | **API endpoints** |\n| `@returns_model()` | Auto-validate to model | Pydantic model | **Business logic** |\n\n### \ud83d\udd27 Utility Functions\n\n| Function | Purpose | Returns | Use Case |\n| --------------------------------- | ------------------- | ------------------ | ------------------------ |\n| `get_model_info()` | Model introspection | Model details dict | **Debugging & analysis** |\n| `validate_schema_compatibility()` | Schema validation | Compatibility info | **Schema validation** |\n\n### \ud83c\udfaf Key Scenarios\n\n- **\ud83e\udd16 LLM Data Extraction**: Define extraction schemas that LLMs can easily follow\n- **\ud83d\udd27 API Development**: Generate Pydantic models and OpenAPI docs from simple syntax\n- **\u2705 Data Validation**: Create robust validation schemas with minimal code\n- **\ud83c\udf0d Timezone-Aware APIs**: Automatic UTC conversion for consistent datetime handling\n- **\ud83d\udccb Configuration**: Define and validate application configuration schemas\n- **\ud83d\udd04 Data Transformation**: Convert between different schema formats\n\n### \u2705 Validate Data\n\n```python\nfrom string_schema import validate_to_dict, validate_to_model\n\n# Example raw data (from API, user input, etc.)\nraw_data = {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"age\": \"25\", # String that needs conversion\n \"extra_field\": \"ignored\" # Will be filtered out\n}\n\n# Validate to clean dictionaries (perfect for API responses)\nuser_dict = validate_to_dict(raw_data, \"name:string, email:email, age:int?\")\nprint(user_dict) # {\"name\": \"John Doe\", \"email\": \"john@example.com\", \"age\": 25}\n\n# Validate to typed models (perfect for business logic)\nuser_model = validate_to_model(raw_data, \"name:string, email:email, age:int?\")\nprint(user_model.name) # \"John Doe\" - Full type safety\nprint(user_model.age) # 25 - Converted to int\n\n# \ud83c\udf0d Automatic timezone handling for datetime fields\nfrom datetime import datetime\nevent_data = {\"name\": \"Meeting\", \"start_time\": datetime(2025, 8, 13, 14, 30)}\nevent_dict = validate_to_dict(event_data, \"name:string, start_time:datetime\")\nprint(event_dict) # {\"name\": \"Meeting\", \"start_time\": \"2025-08-13T14:30:00+00:00\"}\n```\n\n### \ud83c\udfa8 Function Decorators\n\n```python\nfrom string_schema import returns_dict, returns_model\nimport uuid\n\n# Auto-validate function returns to dicts\n@returns_dict(\"id:string, name:string, active:bool\")\ndef create_user(name):\n # Input: \"Alice\"\n # Function returns unvalidated dict\n return {\"id\": str(uuid.uuid4()), \"name\": name, \"active\": True, \"extra\": \"ignored\"}\n # Output: {\"id\": \"123e4567-...\", \"name\": \"Alice\", \"active\": True}\n # Note: 'extra' field filtered out, types validated\n\n# Auto-validate function returns to models\n@returns_model(\"name:string, email:string\")\ndef process_user(raw_input):\n # Input: {\"name\": \"Bob\", \"email\": \"bob@test.com\", \"junk\": \"data\"}\n # Function returns unvalidated dict\n return {\"name\": raw_input[\"name\"], \"email\": raw_input[\"email\"], \"junk\": \"data\"}\n # Output: UserModel(name=\"Bob\", email=\"bob@test.com\")\n # Note: Returns typed Pydantic model, 'junk' field filtered out\n\n# Usage examples:\nuser_dict = create_user(\"Alice\") # Returns validated dict\nuser_model = process_user({\"name\": \"Bob\", \"email\": \"bob@test.com\"}) # Returns Pydantic model\nprint(user_model.name) # \"Bob\" - Full type safety\n```\n\n### \ud83c\udf10 FastAPI Integration\n\n```python\nfrom string_schema import string_to_model, returns_dict\n\n# Create models for FastAPI\nUserRequest = string_to_model(\"name:string, email:email\")\n\n@app.post(\"/users\")\n@returns_dict(\"id:int, name:string, email:string\")\ndef create_user_endpoint(user: UserRequest):\n return {\"id\": 123, \"name\": user.name, \"email\": user.email}\n```\n\n**Features**: Arrays `[{name:string}]`, nested objects `{profile:{bio:text?}}`, enums, constraints, decorators.\n\n[\ud83d\udcd6 **Complete Documentation**](docs/pydantic-utilities.md)\n\n## \ud83c\udf93 More Examples\n\n### \ud83c\udf31 Simple Example - Basic User Data\n\n```python\nfrom string_schema import string_to_json_schema\n\n# Define schema using intuitive string syntax\nschema = string_to_json_schema(\"\"\"\nname:string(min=1, max=100),\nemail:email,\nage:int(0, 120)?,\nactive:bool\n\"\"\")\n\n# Result: JSON Schema dictionary ready for validation\nprint(schema)\n# {\n# \"type\": \"object\",\n# \"properties\": {\n# \"name\": {\"type\": \"string\", \"minLength\": 1, \"maxLength\": 100},\n# \"email\": {\"type\": \"string\", \"format\": \"email\"},\n# \"age\": {\"type\": \"integer\", \"minimum\": 0, \"maximum\": 120},\n# \"active\": {\"type\": \"boolean\"}\n# },\n# \"required\": [\"name\", \"email\", \"active\"]\n# }\n```\n\n### \ud83c\udf33 Moderately Complex Example - Product Data\n\n```python\n# Product with arrays and nested objects\nschema = string_to_json_schema(\"\"\"\n{\n id:uuid,\n name:string,\n price:number(min=0),\n tags:[string]?,\n inventory:{\n in_stock:bool,\n quantity:int?\n }\n}\n\"\"\")\n\n# Result: Complete JSON Schema with nested objects and arrays\nprint(schema) # Full JSON Schema ready for validation\n```\n\n> \ud83d\udcda **For more examples and advanced syntax**, see our [detailed documentation](docs/string-syntax.md)\n\n## \ud83d\udd04 Output Formats & Results\n\n### \ud83d\udc0d Pydantic Models (Python Classes)\n\n```python\nfrom string_schema import string_to_model\n\n# Direct conversion: String syntax \u2192 Pydantic model\nUserModel = string_to_model(\"name:string, email:email, active:bool\")\n\n# Use the model for validation\nuser = UserModel(name=\"John Doe\", email=\"john@example.com\", active=True)\nprint(user.model_dump_json()) # {\"name\": \"John Doe\", \"email\": \"john@example.com\", \"active\": true}\n```\n\n### \ud83d\udd27 Code Generation (For Templates & Tools)\n\n```python\nfrom string_schema import string_to_model_code\n\n# Generate Pydantic model code as a string\ncode = string_to_model_code(\"User\", \"name:string, email:email, active:bool\")\nprint(code)\n\n# Output:\n# from pydantic import BaseModel\n# from typing import Optional\n#\n# class User(BaseModel):\n# name: str\n# email: str\n# active: bool\n\n# Perfect for code generators, templates, or saving to files\nwith open('models.py', 'w') as f:\n f.write(code)\n```\n\n### \ud83c\udf10 OpenAPI Schemas (API Documentation)\n\n```python\nfrom string_schema import string_to_openapi\n\n# Direct conversion: String syntax \u2192 OpenAPI schema\nopenapi_schema = string_to_openapi(\"name:string, email:email\")\nprint(openapi_schema)\n# {\n# \"type\": \"object\",\n# \"properties\": {\n# \"name\": {\"type\": \"string\"},\n# \"email\": {\"type\": \"string\", \"format\": \"email\"}\n# },\n# \"required\": [\"name\", \"email\"]\n# }\n```\n\n## \ud83d\udd04 Reverse Conversions (Universal Schema Converter)\n\nString Schema provides complete bidirectional conversion between all schema formats!\n\n> **\u26a0\ufe0f Information Loss Notice**: Reverse conversions (from JSON Schema/OpenAPI/Pydantic back to string syntax) may lose some information due to format differences. However, the resulting schemas are designed to cover the most common use cases and maintain functional equivalence for typical validation scenarios.\n\n### \ud83d\udd0d Schema Introspection\n\n```python\nfrom string_schema import model_to_string, string_to_model\n\n# Create a model first\nUserModel = string_to_model(\"name:string, email:email, active:bool\")\n\n# Reverse engineer it back to string syntax\nschema_string = model_to_string(UserModel)\nprint(f\"Model schema: {schema_string}\")\n# Output: \"name:string, email:email, active:bool\"\n```\n\n### \ud83d\udce6 Migration & Import\n\n```python\nfrom string_schema import json_schema_to_string\n\n# Example: Convert existing JSON Schema to String Schema syntax\njson_schema = {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n \"email\": {\"type\": \"string\", \"format\": \"email\"},\n \"age\": {\"type\": \"integer\"}\n },\n \"required\": [\"name\", \"email\"]\n}\n\nsimple_syntax = json_schema_to_string(json_schema)\nprint(f\"Converted: {simple_syntax}\")\n# Output: \"name:string, email:email, age:int?\"\n```\n\n### \ud83d\udd27 Schema Comparison & Analysis\n\n```python\nfrom string_schema import string_to_model, model_to_string\n\n# Create two versions of a model\nUserV1 = string_to_model(\"name:string, email:email\")\nUserV2 = string_to_model(\"name:string, email:email, active:bool\")\n\n# Compare them\nv1_str = model_to_string(UserV1)\nv2_str = model_to_string(UserV2)\n\nprint(\"Schema changes:\")\nprint(f\"V1: {v1_str}\") # \"name:string, email:email\"\nprint(f\"V2: {v2_str}\") # \"name:string, email:email, active:bool\"\n```\n\n## \ud83c\udfa8 String Syntax Reference\n\n### Basic Types\n\n- `string`, `int`, `number`, `bool` \u2192 Basic data types\n- `email`, `url`, `datetime`, `date`, `uuid`, `phone` \u2192 Special validated types\n\n### Field Modifiers\n\n- `field_name:type` \u2192 Required field\n- `field_name:type?` \u2192 Optional field\n- `field_name:type(constraints)` \u2192 Field with validation\n\n### Common Patterns\n\n- `string(min=1, max=100)` \u2192 Length constraints\n- `int(0, 120)` \u2192 Range constraints\n- `[string]` \u2192 Simple arrays\n- `[{name:string, email:email}]` \u2192 Object arrays\n- `status:enum(active, inactive)` \u2192 Enum values\n- `id:string|uuid` \u2192 Union types\n\n> \ud83d\udcd6 **Complete syntax guide**: See [docs/string-syntax.md](docs/string-syntax.md) for full reference\n\n## \u2705 Validation\n\n```python\nfrom string_schema import validate_string_syntax\n\n# Validate your schema syntax\nresult = validate_string_syntax(\"name:string, email:email, age:int?\")\n\nprint(f\"Valid: {result['valid']}\") # True\nprint(f\"Features used: {result['features_used']}\") # ['basic_types', 'optional_fields']\nprint(f\"Field count: {len(result['parsed_fields'])}\") # 3\n\n# Example with invalid syntax\nbad_result = validate_string_syntax(\"name:invalid_type\")\nprint(f\"Valid: {bad_result['valid']}\") # False\nprint(f\"Errors: {bad_result['errors']}\") # ['Unknown type: invalid_type']\n```\n\n## \ud83c\udfd7\ufe0f Common Use Cases\n\n### \ud83e\udd16 LLM Data Extraction\n\n```python\nfrom string_schema import string_to_json_schema\n\n# Define what data to extract\nschema = string_to_json_schema(\"company:string, employees:[{name:string, email:email}], founded:int?\")\n# Use schema in LLM prompts for structured data extraction\n```\n\n### \ud83d\udd27 FastAPI Development\n\n```python\nfrom string_schema import string_to_model\n\n# Create model for FastAPI\nUserModel = string_to_model(\"name:string, email:email\")\n\n# Use in FastAPI endpoints\n@app.post(\"/users/\")\nasync def create_user(user: UserModel):\n return {\"id\": 123, \"name\": user.name, \"email\": user.email}\n```\n\n### \ud83c\udfd7\ufe0f Code Generation & Templates\n\n```python\nfrom string_schema import string_to_model_code\n\n# Generate model code\ncode = string_to_model_code(\"User\", \"name:string, email:email\")\nprint(code)\n# Output: Complete Pydantic model class as string\n\n# Save to file\nwith open('user_model.py', 'w') as f:\n f.write(code)\n```\n\n### \ud83d\udccb Configuration Validation\n\n```python\nfrom string_schema import string_to_json_schema\n\n# Validate app configuration\nconfig_schema = string_to_json_schema(\"database:{host:string, port:int}, debug:bool\")\n# Use for validating config files\n```\n\n## \ud83d\udcda Documentation\n\n- **[Getting Started](docs/getting-started.md)** - Quick start guide and installation\n- **[String Syntax Guide](docs/string-syntax.md)** - Complete syntax reference\n- **[API Reference](docs/api-reference.md)** - Full API documentation\n- **[Examples](docs/examples.md)** - Practical examples and patterns\n\n## \ud83d\udccb Example Schemas\n\nReady-to-use schema examples are available in the `examples/` directory:\n\n```python\n# Import example schemas if needed\nfrom string_schema.examples.presets import user_schema, product_schema\nfrom string_schema.examples.recipes import create_ecommerce_product_schema\n\n# Or better yet, use string syntax directly:\nuser_schema = string_to_json_schema(\"name:string, email:email, age:int?\")\n```\n\n## \ud83e\uddea Testing\n\nThe library includes comprehensive tests covering all functionality:\n\n```bash\n# Run tests (requires pytest)\npip install pytest\npytest tests/\n\n# Results: 66 tests passed, 3 skipped (Pydantic tests when not installed)\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! The codebase is well-organized and documented:\n\n```\nstring_schema/\n\u251c\u2500\u2500 core/ # Core functionality (fields, builders, validators)\n\u251c\u2500\u2500 parsing/ # String parsing and syntax\n\u251c\u2500\u2500 integrations/ # Pydantic, JSON Schema, OpenAPI\n\u2514\u2500\u2500 examples/ # Built-in schemas and recipes\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**String Schema** - Making data validation simple, intuitive, and LLM-friendly! \ud83d\ude80\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple, LLM-friendly schema definition library for converting string syntax to structured schemas",
"version": "0.1.6",
"project_urls": {
"Bug Reports": "https://github.com/xychenmsn/string-schema/issues",
"Changelog": "https://github.com/xychenmsn/string-schema/releases",
"Documentation": "https://github.com/xychenmsn/string-schema#readme",
"Homepage": "https://github.com/xychenmsn/string-schema",
"Repository": "https://github.com/xychenmsn/string-schema"
},
"split_keywords": [
"schema",
" validation",
" json",
" llm",
" ai",
" data-extraction",
" pydantic"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bdd4c6eac343b008c722e21fd3626690efda74c2af817389f460448c9d574557",
"md5": "00ae96a394cfaa9f55bb2f4c603b2139",
"sha256": "8b8a690f3ff374573405bfe1db534f17010a44e28ef16a0f36f2616a52e9036c"
},
"downloads": -1,
"filename": "string_schema-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00ae96a394cfaa9f55bb2f4c603b2139",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 52794,
"upload_time": "2025-08-18T01:32:32",
"upload_time_iso_8601": "2025-08-18T01:32:32.775296Z",
"url": "https://files.pythonhosted.org/packages/bd/d4/c6eac343b008c722e21fd3626690efda74c2af817389f460448c9d574557/string_schema-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8246e046b0bffc0aa59f0cba18c96153cab7e1fb8de3d02a0e4b4b1d918db04a",
"md5": "021147d9a6eb16f79c1a3330ba4557f5",
"sha256": "a366efdcae99760978990e4ddaee43497d7b515e80e308c3bf208bbabacbc843"
},
"downloads": -1,
"filename": "string_schema-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "021147d9a6eb16f79c1a3330ba4557f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 74755,
"upload_time": "2025-08-18T01:32:34",
"upload_time_iso_8601": "2025-08-18T01:32:34.200649Z",
"url": "https://files.pythonhosted.org/packages/82/46/e046b0bffc0aa59f0cba18c96153cab7e1fb8de3d02a0e4b4b1d918db04a/string_schema-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 01:32:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xychenmsn",
"github_project": "string-schema",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "email-validator",
"specs": [
[
">=",
"2.0.0"
]
]
}
],
"lcname": "string-schema"
}
JSON
