פורמטים של נתונים מובנים כמו JSON ו-YAML הם חיוניים לבניית יישומים שצורכים פלטי AI באופן תכנותי. פרק זה מכסה טכניקות ליצירת פלט מובנה אמין.

<Callout type="info" title="מטקסט לנתונים">
JSON ו-YAML הופכים פלטי AI מטקסט חופשי לנתונים מובנים ובטוחי-טיפוסים שקוד יכול לצרוך ישירות.
</Callout>

## למה פורמטים מובנים?

<JsonYamlDemo />

## יסודות הנחיית JSON

JSON (JavaScript Object Notation) הוא הפורמט הנפוץ ביותר לפלטי AI תכנותיים. התחביר הקפדני שלו מקל על הניתוח, אך גם אומר ששגיאות קטנות יכולות לשבור את כל הצינור שלכם.

### מה כן ומה לא: בקשת JSON

<Compare 
  before={{ label: "❌ לא: בקשה מעורפלת", content: "תן לי את פרטי המשתמש כ-JSON." }}
  after={{ label: "✓ כן: הצג את הסכמה", content: "חלץ פרטי משתמש כ-JSON התואם לסכמה זו:\n\n{\n  \"name\": \"string\",\n  \"age\": number,\n  \"email\": \"string\"\n}\n\nהחזר רק JSON תקין, ללא markdown." }}
/>

### פלט JSON פשוט

התחילו עם סכמה המציגה את המבנה הצפוי. המודל ימלא ערכים על בסיס טקסט הקלט.

```
Extract the following information as JSON:

{
  "name": "string",
  "age": number,
  "email": "string"
}

Text: "Contact John Smith, 34 years old, at john@example.com"
```

פלט:
```json
{
  "name": "John Smith",
  "age": 34,
  "email": "john@example.com"
}
```

### מבני JSON מקוננים

נתונים מהעולם האמיתי לעתים קרובות כוללים קשרים מקוננים. הגדירו כל רמה בסכמה שלכם בבירור, במיוחד עבור מערכים של אובייקטים.

```
Parse this order into JSON:

{
  "order_id": "string",
  "customer": {
    "name": "string",
    "email": "string"
  },
  "items": [
    {
      "product": "string",
      "quantity": number,
      "price": number
    }
  ],
  "total": number
}

Order: "Order #12345 for Jane Doe (jane@email.com): 2x Widget ($10 each), 
1x Gadget ($25). Total: $45"
```

### הבטחת JSON תקין

<Callout type="warning" title="נקודת כשל נפוצה">
מודלים לעתים קרובות עוטפים JSON בבלוקי קוד של markdown או מוסיפים טקסט הסברתי. היו מפורשים לגבי הרצון ב-JSON גולמי בלבד.
</Callout>

הוסיפו הוראות מפורשות:

```
CRITICAL: Return ONLY valid JSON. No markdown, no explanation, 
no additional text before or after the JSON object.

If a field cannot be determined, use null.
Ensure all strings are properly quoted and escaped.
Numbers should not be quoted.
```

## יסודות הנחיית YAML

YAML קריא יותר לבני אדם מ-JSON ותומך בהערות. הוא הסטנדרט לקבצי תצורה, במיוחד ב-DevOps (Docker, Kubernetes, GitHub Actions).

### פלט YAML פשוט

YAML משתמש בהזחה במקום סוגריים מסולסלים. ספקו תבנית המציגה את המבנה הצפוי.

```
Generate a configuration file in YAML format:

server:
  host: string
  port: number
  ssl: boolean
database:
  type: string
  connection_string: string

Requirements: Production server on port 443 with SSL, PostgreSQL database
```

פלט:
```yaml
server:
  host: "0.0.0.0"
  port: 443
  ssl: true
database:
  type: "postgresql"
  connection_string: "postgresql://user:pass@localhost:5432/prod"
```

### מבני YAML מורכבים

לתצורות מורכבות, היו ספציפיים לגבי הדרישות. המודל מכיר דפוסים נפוצים לכלים כמו GitHub Actions, Docker Compose ו-Kubernetes.

```
Generate a GitHub Actions workflow in YAML:

Requirements:
- Trigger on push to main and pull requests
- Run on Ubuntu latest
- Steps: checkout, setup Node 18, install dependencies, run tests
- Cache npm dependencies
```

## הגדרות טיפוסים בהנחיות

הגדרות טיפוסים נותנות למודל חוזה מדויק למבנה הפלט. הן יותר מפורשות מדוגמאות וקלות יותר לאימות תכנותי.

### שימוש בטיפוסים בסגנון TypeScript

ממשקי TypeScript מוכרים למפתחים ומתארים במדויק שדות אופציונליים, טיפוסי union ומערכים. פלטפורמת prompts.chat משתמשת בגישה זו להנחיות מובנות.

<TryIt 
  title="חילוץ עם ממשק TypeScript"
  description="השתמשו בממשק TypeScript לחילוץ נתונים מובנים."
  prompt={`Extract data according to this type definition:

interface ChatPersona {
    name?: string;
    role?: string;
    tone?: "professional" | "casual" | "friendly" | "technical";
    expertise?: string[];
    personality?: string[];
    background?: string;
}

Return as JSON matching this interface.

Description: "A senior software engineer named Alex who reviews code. They're analytical and thorough, with expertise in backend systems and databases. Professional but approachable tone."`}
/>

### הגדרת JSON Schema

<Callout type="info" title="סטנדרט תעשייתי">
JSON Schema היא מפרט פורמלי לתיאור מבנה JSON. היא נתמכת על ידי ספריות אימות וכלי API רבים.
</Callout>

JSON Schema מספקת אילוצים כמו ערכי מינימום/מקסימום, שדות חובה ותבניות regex:

```
Extract data according to this JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["title", "author", "year"],
  "properties": {
    "title": { "type": "string" },
    "author": { "type": "string" },
    "year": { "type": "integer", "minimum": 1000, "maximum": 2100 },
    "genres": { 
      "type": "array", 
      "items": { "type": "string" }
    },
    "rating": { 
      "type": "number", 
      "minimum": 0, 
      "maximum": 5 
    }
  }
}

Book: "1984 by George Orwell (1949) - A dystopian masterpiece. 
Genres: Science Fiction, Political Fiction. Rated 4.8/5"
```

## טיפול במערכים

מערכים דורשים תשומת לב מיוחדת. ציינו האם אתם צריכים מספר קבוע של פריטים או רשימה באורך משתנה, וכיצד לטפל במקרים ריקים.

### מערכים באורך קבוע

כשאתם צריכים בדיוק N פריטים, ציינו זאת במפורש. המודל יוודא שלמערך יש את האורך הנכון.

```
Extract exactly 3 key points as JSON:

{
  "key_points": [
    "string (first point)",
    "string (second point)", 
    "string (third point)"
  ]
}

Article: [article text]
```

### מערכים באורך משתנה

למערכים באורך משתנה, ציינו מה לעשות כשאין פריטים. הכללת שדה ספירה עוזרת לאמת את שלמות החילוץ.

```
Extract all mentioned people as JSON:

{
  "people": [
    {
      "name": "string",
      "role": "string or null if not mentioned"
    }
  ],
  "count": number
}

If no people are mentioned, return empty array.

Text: [text]
```

## ערכי Enum ואילוצים

Enums מגבילים ערכים לקבוצה מוגדרת מראש. זה קריטי למשימות סיווג ובכל מקום שבו אתם צריכים פלטים עקביים וניתנים לחיזוי.

### מה כן ומה לא: ערכי Enum

<Compare 
  before={{ label: "❌ לא: קטגוריות פתוחות", content: "סווג את הטקסט הזה לקטגוריה.\n\n{\n  \"category\": \"string\"\n}" }}
  after={{ label: "✓ כן: הגבל לערכים תקינים", content: "סווג את הטקסט הזה. הקטגוריה חייבת להיות בדיוק אחת מ:\n- \"technical\"\n- \"business\"\n- \"creative\"\n- \"personal\"\n\n{\n  \"category\": \"אחד מהערכים למעלה\"\n}" }}
/>

### Enums של מחרוזות

רשמו ערכים מותרים במפורש. השתמשו בשפת "חייב להיות אחד מ" לאכיפת התאמה קפדנית.

```
Classify this text. The category MUST be one of these exact values:
- "technical"
- "business" 
- "creative"
- "personal"

Return JSON:
{
  "text": "original text (truncated to 50 chars)",
  "category": "one of the enum values above",
  "confidence": number between 0 and 1
}

Text: [text to classify]
```

### מספרים מאומתים

אילוצים מספריים מונעים ערכים מחוץ לטווח. ציינו את הטיפוס (integer לעומת float) והטווח התקין.

```
Rate these aspects. Each score MUST be an integer from 1 to 5.

{
  "quality": 1-5,
  "value": 1-5,
  "service": 1-5,
  "overall": 1-5
}

Review: [review text]
```

## טיפול בנתונים חסרים

טקסט מהעולם האמיתי לעתים קרובות חסר מידע מסוים. הגדירו כיצד המודל צריך לטפל בנתונים חסרים כדי למנוע ערכים מומצאים.

### מה כן ומה לא: מידע חסר

<Compare 
  before={{ label: "❌ לא: לתת ל-AI לנחש", content: "חלץ את כל פרטי החברה כ-JSON:\n{\n  \"revenue\": number,\n  \"employees\": number\n}" }}
  after={{ label: "✓ כן: לאפשר null במפורש", content: "חלץ פרטי חברה. השתמש ב-null עבור כל שדה שאינו מוזכר במפורש. אל תמציא או תעריך ערכים.\n\n{\n  \"revenue\": \"number or null\",\n  \"employees\": \"number or null\"\n}" }}
/>

### ערכי Null

אפשרו null במפורש והורו למודל לא להמציא מידע. זה בטוח יותר מלתת למודל לנחש.

```
Extract information. Use null for any field that cannot be 
determined from the text. Do NOT invent information.

{
  "company": "string or null",
  "revenue": "number or null",
  "employees": "number or null",
  "founded": "number (year) or null",
  "headquarters": "string or null"
}

Text: "Apple, headquartered in Cupertino, was founded in 1976."
```

פלט:
```json
{
  "company": "Apple",
  "revenue": null,
  "employees": null,
  "founded": 1976,
  "headquarters": "Cupertino"
}
```

### ערכי ברירת מחדל

כאשר ברירות מחדל הגיוניות, ציינו אותן בסכמה. זה נפוץ לחילוץ תצורות.

```
Extract settings with these defaults if not specified:

{
  "theme": "light" (default) | "dark",
  "language": "en" (default) | other ISO code,
  "notifications": true (default) | false,
  "fontSize": 14 (default) | number
}

User preferences: "I want dark mode and larger text (18px)"
```

## תגובות מרובות-אובייקטים

לעתים קרובות אתם צריכים לחלץ פריטים מרובים מקלט יחיד. הגדירו את מבנה המערך וכל דרישות מיון/קיבוץ.

### מערך של אובייקטים

לרשימות של פריטים דומים, הגדירו את סכמת האובייקט פעם אחת וציינו שזה מערך.

```
Parse this list into JSON array:

[
  {
    "task": "string",
    "priority": "high" | "medium" | "low",
    "due": "ISO date string or null"
  }
]

Todo list:
- Finish report (urgent, due tomorrow)
- Call dentist (low priority)
- Review PR #123 (medium, due Friday)
```

### אובייקטים מקובצים

משימות קיבוץ דורשות לוגיקת קטגוריזציה. המודל ימיין פריטים לקטגוריות שהגדרתם.

```
Categorize these items into JSON:

{
  "fruits": ["string array"],
  "vegetables": ["string array"],
  "other": ["string array"]
}

Items: apple, carrot, bread, banana, broccoli, milk, orange, spinach
```

## YAML ליצירת תצורות

YAML מצטיין בתצורות DevOps. המודל מכיר דפוסים סטנדרטיים לכלים נפוצים ויכול ליצור תצורות מוכנות לייצור.

### מה כן ומה לא: תצורות YAML

<Compare 
  before={{ label: "❌ לא: דרישות מעורפלות", content: "צור קובץ docker-compose ליישום שלי." }}
  after={{ label: "✓ כן: ציין רכיבים וצרכים", content: "צור docker-compose.yml עבור:\n- יישום Node.js (פורט 3000)\n- מסד נתונים PostgreSQL\n- מטמון Redis\n\nכלול: בדיקות תקינות, אחסון מתמיד, סביבה מקובץ .env" }}
/>

### Docker Compose

ציינו את השירותים שאתם צריכים וכל דרישות מיוחדות. המודל יטפל בתחביר YAML ובשיטות עבודה מומלצות.

```
Generate a docker-compose.yml for:
- Node.js app on port 3000
- PostgreSQL database
- Redis cache
- Nginx reverse proxy

Include:
- Health checks
- Volume persistence
- Environment variables from .env file
- Network isolation
```

### Manifests של Kubernetes

Manifests של Kubernetes הם מפורטים אך עוקבים אחר דפוסים צפויים. ספקו את הפרמטרים המרכזיים והמודל ייצור YAML תואם.

```
Generate Kubernetes deployment YAML:

Deployment:
- Name: api-server
- Image: myapp:v1.2.3
- Replicas: 3
- Resources: 256Mi memory, 250m CPU (requests)
- Health checks: /health endpoint
- Environment from ConfigMap: api-config

Also generate matching Service (ClusterIP, port 8080)
```

## אימות וטיפול בשגיאות

למערכות ייצור, בנו אימות לתוך ההנחיות שלכם. זה תופס שגיאות לפני שהן מתפשטות בצינור שלכם.

### הנחיית אימות עצמי

בקשו מהמודל לאמת את הפלט שלו מול כללים שאתם מציינים. זה תופס שגיאות פורמט וערכים לא תקינים.

```
Extract data as JSON, then validate your output.

Schema:
{
  "email": "valid email format",
  "phone": "E.164 format (+1234567890)",
  "date": "ISO 8601 format (YYYY-MM-DD)"
}

After generating JSON, check:
1. Email contains @ and valid domain
2. Phone starts with + and contains only digits
3. Date is valid and parseable

If validation fails, fix the issues before responding.

Text: [contact information]
```

### פורמט תגובת שגיאה

הגדירו פורמטים נפרדים להצלחה ושגיאה. זה מקל בהרבה על הטיפול התכנותי.

```
Attempt to extract data. If extraction fails, return error format:

Success format:
{
  "success": true,
  "data": { ... extracted data ... }
}

Error format:
{
  "success": false,
  "error": "description of what went wrong",
  "partial_data": { ... any data that could be extracted ... }
}
```

## JSON לעומת YAML: מתי להשתמש במה

<div className="my-4 grid md:grid-cols-2 gap-4">
  <div className="p-4 bg-amber-50 dark:bg-amber-950/30 rounded-lg border border-amber-200 dark:border-amber-800">
    <div className="font-semibold text-amber-700 dark:text-amber-300 mb-2">השתמשו ב-JSON כאשר</div>
    <div className="text-sm space-y-1">
      <p className="m-0!">נדרש ניתוח תכנותי</p>
      <p className="m-0!">תגובות API</p>
      <p className="m-0!">דרישות טיפוסים קפדניות</p>
      <p className="m-0!">אינטגרציה עם JavaScript/Web</p>
      <p className="m-0!">ייצוג קומפקטי</p>
    </div>
  </div>
  <div className="p-4 bg-purple-50 dark:bg-purple-950/30 rounded-lg border border-purple-200 dark:border-purple-800">
    <div className="font-semibold text-purple-700 dark:text-purple-300 mb-2">השתמשו ב-YAML כאשר</div>
    <div className="text-sm space-y-1">
      <p className="m-0!">קריאות אנושית חשובה</p>
      <p className="m-0!">קבצי תצורה</p>
      <p className="m-0!">נדרשות הערות</p>
      <p className="m-0!">DevOps/תשתית</p>
      <p className="m-0!">מבנים מקוננים עמוקים</p>
    </div>
  </div>
</div>

## הנחיות מובנות ב-Prompts.chat

ב-prompts.chat, אתם יכולים ליצור הנחיות עם פורמטים של פלט מובנה:

```
When creating a prompt on prompts.chat, you can specify:

Type: STRUCTURED
Format: JSON or YAML

The platform will:
- Validate outputs against your schema
- Provide syntax highlighting
- Enable easy copying of structured output
- Support template variables in your schema
```

## מלכודות נפוצות

<Callout type="warning" title="בדקו את אלה קודם">
שלוש הבעיות האלה גורמות לרוב כשלי ניתוח JSON. חפשו אותן כשהקוד שלכם לא מצליח לנתח פלט AI.
</Callout>

### 1. בלוקי קוד של Markdown

**בעיה:** המודל עוטף JSON בבלוקי ```json

**פתרון:** 
```
Return ONLY the JSON object. Do not wrap in markdown code blocks.
Do not include ```json or ``` markers.
```

### 2. פסיקים מסיימים

**בעיה:** JSON לא תקין בגלל פסיקים מסיימים

**פתרון:**
```
Ensure valid JSON syntax. No trailing commas after the last 
element in arrays or objects.
```

### 3. מחרוזות לא מוברחות

**בעיה:** מרכאות או תווים מיוחדים שוברים JSON

**פתרון:**
```
Properly escape special characters in strings:
- \" for quotes
- \\ for backslashes
- \n for newlines
```

## סיכום

<Callout type="tip" title="טכניקות מפתח">
הגדירו סכמות במפורש באמצעות ממשקי TypeScript או JSON Schema. ציינו טיפוסים ואילוצים, טפלו ב-nulls וברירות מחדל, בקשו אימות עצמי, ובחרו את הפורמט הנכון לשימוש שלכם.
</Callout>

<Quiz 
  question="מתי עדיף להעדיף YAML על פני JSON לפלטי AI?"
  options={[
    "כשבונים REST APIs",
    "כשהפלט צריך להיות קריא לבני אדם ועשוי לכלול הערות",
    "כשעובדים עם יישומי JavaScript",
    "כשצריכים את הייצוג הכי קומפקטי"
  ]}
  correctIndex={1}
  explanation="YAML מועדף כאשר קריאות אנושית חשובה, כמו בקבצי תצורה, manifests של DevOps ותיעוד. הוא גם תומך בהערות, בניגוד ל-JSON."
/>

זה משלים את חלק II על טכניקות. בחלק III, נחקור יישומים מעשיים בתחומים שונים.
