JSON Schema Converter

Converts unstructured text, logs, or informal records into valid, schema-compliant JSON. Ensures exact type mapping, required keys, and deterministic output.

1. Purpose

Turn loose data into machine-readable JSON that validates against a provided JSON Schema (Draft 7 / 2020-12). Enforces data types (string, integer, boolean, array, object).

2. When to Use

Use this skill when:

• Converting email summaries, logs, or transcripts into structured API payloads.
• Normalizing messy data before database ingestion.
• User requests: "Convert this text into JSON matching this schema."

3. When Not to Use

• Do not use for tabular CSV verification; use csv-validator.
• Do not use to extract isolated fields; use field-extractor.

4. Required Inputs

• raw_input: Text, table, or key-value snippets to convert.
• target_schema: JSON schema specification defining expected keys and types.

5. Missing-Input Behavior

1. If raw_input is missing: stop and ask: "Please provide the data to convert."
2. If target_schema is missing: ask for the expected schema or generate a minimal typed schema and request confirmation.
3. If a required schema field is absent in raw_input: set to null if nullable, or list under missing fields. Do not hallucinate values.

6. Procedure

Follow these numbered actions:

1. Action 1: Parse Schema Keys & Types
   • Identify required fields and expected types (integer, boolean, string, array).
2. Action 2: Map Raw Data to Schema Keys
   • Cast strings to numbers/booleans where safe (e.g. "true" -> true, "42" -> 42).
3. Action 3: Validate Against Schema
   • Run validator helper:

     python3 skills/json-schema-converter/scripts/validate_json.py <json_file>

4. Action 4: Emit JSON Payload
   • Output clean, indented JSON per Section 8.

7. Decision Rules

• If raw data contains fields not in schema: omit them if additionalProperties: false, or include under extra_metadata if allowed.
• Dates must be formatted as ISO-8601 (YYYY-MM-DDTHH:MM:SSZ) if schema format is date-time.

8. Output Format

Emit the JSON conversion using this template:

### JSON Conversion Result

- **Validation**: [VALID | INVALID]
- **Target Schema Keys Met**: [Count] / [Total]

```json
{
  "key": "value"
}

Field Mapping Notes

• [key]: [Mapped from raw text]

## 9. Verification Checklist
- [ ] Output is 100% valid JSON (passes `json.loads`).
- [ ] All required schema fields are present.
- [ ] Types conform strictly to schema specifications.
- [ ] Companion script [validate_json.py](./scripts/validate_json.py) confirms syntax.

## 10. Common Failures and Recovery
| Failure Symptom | Cause | Recovery Action |
| :--- | :--- | :--- |
| Trailing comma error | Invalid JSON formatting | Strip trailing commas before returning. |
| Type mismatch (string vs int) | Failing to cast `"10"` to `10` | Check schema type property and cast numeric strings. |

## 11. Stop or Escalation Conditions
Stop and ask the user when:
- Raw input contains none of the required schema fields.

## 12. Examples

### Example 1: Successful Execution
**Input:**
```text
Raw input: Customer Alice Smith (id: 402), signed up 2026-05-10, plan: Pro, active.
Schema: {
  "type": "object",
  "required": ["id", "name", "plan", "is_active"],
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "plan": { "type": "string" },
    "is_active": { "type": "boolean" }
  }
}

Output:

### JSON Conversion Result

- **Validation**: VALID
- **Target Schema Keys Met**: 4 / 4

```json
{
  "id": 402,
  "name": "Alice Smith",
  "plan": "Pro",
  "is_active": true
}

Field Mapping Notes

• id: Cast string 402 to integer 402.
• is_active: Inferred true from "active".

### Example 2: Ambiguous or Missing Input
**Input:**
```text
Raw input: Just a random note without customer data.
Schema: (Requires id, name, plan)

Output:

### JSON Conversion Result

- **Validation**: INVALID - Missing Required Fields
- **Target Schema Keys Met**: 0 / 3

The raw input does not contain the required fields `id`, `name`, or `plan`. Please provide customer data matching the schema.

Example 3: Expected Final Output

Output:

### JSON Conversion Result

- **Validation**: VALID
- **Target Schema Keys Met**: 2 / 2

```json
{
  "event": "user_signup",
  "timestamp": "2026-09-10T12:00:00Z"
}

Field Mapping Notes

• ISO-8601 timestamp formatted per schema date-time requirement.