📐 JSON Schema Draft 2020-12

JSON Schemas & Autonomous Healing Engine

Strict validation contracts across 114 deliverables, RFC format enforcement, and the autonomous self-correction loop for AI agents.

Sections: 📖 Developers Hub ⌨️ CLI Tooling & Automation 🐍 Python SDK & API 🔌 MCP Server & IDEs 📐 Schemas & Validation 🤖 Agentic Swarms & CI/CD

1. Why JSON Schema Draft 2020-12?

In regulated enterprise environments, prompt-based LLM generation is inherently non-deterministic: models frequently hallucinate undeclared properties, omit required approvals, or format ISO dates inconsistently. Tasleemat enforces JSON Schema Draft 2020-12 as the authoritative validation contract for every deliverable.

Draft 2020-12 Superpowers:

unevaluatedProperties: false: Strictly forbids any hallucinated keys not explicitly defined in the schema.
dependentRequired: Dynamic constraints (e.g. if has_procurement_impact: true, then procurement_officer_signoff is mandatory).
prefixItems: Tuple-style ordered array validation for chronological stage-gate signoffs.

2. Enforced RFC Formats & Validation Modes

The pure-Python validator executes strict syntactic and semantic checking for the following RFC standards:

RFC Standard	Format Keyword	Validation Semantics
RFC 3339	`date`	Full-date formatted as `YYYY-MM-DD`. Leap years and calendar days are mathematically verified.
RFC 3339	`date-time`	Timestamp formatted as `YYYY-MM-DDTHH:MM:SSZ` with strict UTC offset validation.
RFC 4122	`uuid`	128-bit hexadecimal identifier formatted in 8-4-4-4-12 structure.
RFC 3986	`uri`	Compliant Uniform Resource Identifier with valid scheme, authority, and path syntax.
RFC 5322	`email`	Standard mailbox address syntax with verified username and domain parts.

Strict vs. Draft Validation Modes

mode="strict": Zero tolerance. Enforces all required properties, non-empty string values, and rejects any undeclared fields. Mandatory for formal stage-gate audits and executive reviews.
mode="draft": Permissive progressive elaboration. Allows optional fields to remain null or empty while strictly validating types and RFC formats for any populated fields. Used during early sprint planning.

3. The Autonomous Agent Self-Correction Feedback Loop

Healing Engine

Frontier AI models (Gemini, Claude, GPT-4o) do not need humans to fix slight schema discrepancies. When an LLM produces a payload that violates a constraint, tasleemat.validate_artifact_data returns precise JSON Pointer paths. The agent feeds these exact errors back into the model to heal its output in a single retry turn:


sequenceDiagram
    autonumber
    actor User as Project Manager
    participant Agent as Autonomous PMO Agent
    participant Engine as Tasleemat Validator
    participant LLM as Frontier LLM Model

    User->>Agent: "Draft Risk Register for Cloud Project"
    Agent->>Engine: get_artifact_asset("PMO-04.08.02", "schema")
    Engine-->>Agent: Draft 2020-12 Schema Definition
    Agent->>LLM: Prompt + Schema Constraints
    LLM-->>Agent: Raw JSON Payload (Draft 1)
    Agent->>Engine: validate_artifact_data("PMO-04.08.02", Draft 1, mode="strict")
    Engine-->>Agent: ValidationReport(valid=False, error="At /risks/0/score: missing required property")
    Note over Agent,LLM: Autonomous Healing Turn
    Agent->>LLM: "Previous output failed validation at /risks/0/score. Rectify schema error."
    LLM-->>Agent: Corrected JSON Payload (Draft 2)
    Agent->>Engine: validate_artifact_data("PMO-04.08.02", Draft 2, mode="strict")
    Engine-->>Agent: ValidationReport(valid=True)
    Agent->>User: "Risk Register Generated & 100% Schema Validated"

4. Practical Step-by-Step Tutorials

Tutorial 1: Complete Production Autonomous Healing Loop Implementation

A complete, runnable script implementing the retry loop with convergence telemetry:

import json
import tasleemat

def run_autonomous_synthesis(artifact_id: str, prompt_notes: str, llm_callable, max_retries: int = 3):
    # Synthesizes structured deliverable data with autonomous schema self-healing
    schema = tasleemat.get_artifact_asset(artifact_id, "schema", lang="en")
    current_prompt = prompt_notes
    telemetry = {"attempts": 0, "healed": False}

    for attempt in range(1, max_retries + 1):
        telemetry["attempts"] = attempt
        print(f"Synthesis attempt {attempt} for {artifact_id}...")
        
        # 1. Call your configured LLM
        candidate_json_str = llm_callable(prompt=current_prompt, schema=schema)
        candidate_data = json.loads(candidate_json_str)

        # 2. Validate against Draft 2020-12 companion schema
        report = tasleemat.validate_artifact_data(artifact_id, candidate_data, mode="strict")
        if report.valid:
            print(f"✅ Success! Converged on valid schema payload in {attempt} attempt(s).")
            telemetry["healed"] = attempt > 1
            return candidate_data, telemetry

        # 3. Formulate targeted remediation instructions
        error_lines = [f"- Path '{e.path}': {e.message} (Violated: {e.keyword})" for e in report.errors]
        current_prompt = (
            f"{prompt_notes}\n\n"
            f"[CRITICAL VALIDATION FEEDBACK - ATTEMPT {attempt} FAILED]:\n"
            + "\n".join(error_lines)
            + "\nFix these exact JSON paths and return the corrected JSON object."
        )

    raise RuntimeError(f"Failed to converge on valid schema payload after {max_retries} retries.")

Tutorial 2: Authoring a Custom Deliverable Schema

Design a custom Draft 2020-12 schema for enterprise deliverables (e.g. Security Audit Sign-off):

custom_schema = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://company.org/schemas/pmo-sec-01.json",
    "title": "Cloud Security Sign-off",
    "type": "object",
    "required": ["project_id", "security_officer", "signoff_date", "vulnerability_count"],
    "properties": {
        "project_id": {"type": "string", "pattern": "^PRJ-[0-9]{4}-[A-Z]+$"},
        "security_officer": {"type": "string", "minLength": 3},
        "signoff_date": {"type": "string", "format": "date"},
        "vulnerability_count": {"type": "integer", "minimum": 0, "maximum": 0},
        "audit_passed": {"type": "boolean", "const": True}
    },
    "unevaluatedProperties": False
}