{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/almanac-ar/json-schema/almanac-ar-dataset-detail-response-schema.json",
  "title": "DatasetDetailResponse",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/almanac-ar-v1-openapi.json#/components/schemas/DatasetDetailResponse",
  "type": "object",
  "properties": {
    "dataset_id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "additionalProperties": false
    },
    "frequency": {
      "type": [
        "string",
        "null"
      ]
    },
    "granularity": {
      "type": [
        "string",
        "null"
      ]
    },
    "historical_depth": {
      "type": [
        "string",
        "null"
      ]
    },
    "tags": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      }
    },
    "access": {
      "type": "string",
      "enum": [
        "included_in_pro"
      ]
    },
    "country": {
      "type": [
        "string",
        "null"
      ]
    },
    "source_native_language": {
      "type": [
        "string",
        "null"
      ]
    },
    "update_pattern": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "incremental_append",
        "full_refresh",
        "scd2_snapshots",
        null
      ]
    },
    "freshness_sla": {
      "$ref": "#/$defs/DatasetFreshnessSla"
    },
    "content_advisory": {
      "type": [
        "string",
        "null"
      ]
    },
    "compliance_notes": {
      "$ref": "#/$defs/DatasetComplianceNotes"
    },
    "snapshot_date": {
      "type": [
        "string",
        "null"
      ],
      "description": "Fecha (YYYY-MM-DD) del snapshot vigente (`is_latest=true`), o null si el dataset todavía no tiene snapshot publicado. Si es una VIEW derivada, hereda la fecha del dataset padre."
    },
    "row_count": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "description": "Cantidad de filas del snapshot vigente, o null si no hay snapshot todavía."
    },
    "ai_metadata": {
      "$ref": "#/$defs/DatasetAiMetadata"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "dataset_id",
    "name",
    "description",
    "source",
    "frequency",
    "granularity",
    "historical_depth",
    "tags",
    "access",
    "country",
    "source_native_language",
    "update_pattern",
    "freshness_sla",
    "content_advisory",
    "compliance_notes",
    "snapshot_date",
    "row_count",
    "ai_metadata",
    "updated_at"
  ],
  "additionalProperties": false,
  "$defs": {
    "DatasetAiMetadata": {
      "type": "object",
      "properties": {
        "llm_intro": {
          "type": [
            "string",
            "null"
          ]
        },
        "business_questions": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        },
        "example_queries": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/DatasetExampleQuery"
          }
        },
        "methodology_notes": {
          "type": [
            "string",
            "null"
          ]
        },
        "gotchas": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/DatasetGotcha"
          }
        },
        "related_datasets": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/DatasetRelated"
          }
        },
        "columns": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/DatasetColumn"
          }
        },
        "summary_columns": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        },
        "explorable_columns": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        },
        "last_updated": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "llm_intro",
        "business_questions",
        "example_queries",
        "methodology_notes",
        "gotchas",
        "related_datasets",
        "columns",
        "summary_columns",
        "explorable_columns",
        "last_updated"
      ],
      "additionalProperties": false
    },
    "DatasetColumn": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "unit": {
          "type": [
            "string",
            "null"
          ]
        },
        "sample_value": {
          "nullable": true
        },
        "nullable": {
          "type": "boolean"
        }
      },
      "required": [
        "name",
        "type",
        "description"
      ],
      "additionalProperties": false
    },
    "DatasetComplianceNotes": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "license": {
          "type": "string"
        },
        "attribution_required": {
          "type": [
            "string",
            "null"
          ]
        },
        "commercial_use": {
          "type": "string",
          "enum": [
            "ok",
            "restricted",
            "prohibited"
          ]
        },
        "notes": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "license",
        "commercial_use"
      ],
      "additionalProperties": false
    },
    "DatasetExampleQuery": {
      "type": "object",
      "properties": {
        "question": {
          "type": "string"
        },
        "approach": {
          "type": "string"
        },
        "polars": {
          "type": [
            "string",
            "null"
          ]
        },
        "sql": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "question",
        "approach"
      ],
      "additionalProperties": false
    },
    "DatasetFreshnessSla": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "declared_frequency": {
          "type": "string",
          "enum": [
            "daily",
            "weekly",
            "monthly",
            "quarterly",
            "annual",
            "irregular",
            "intraday"
          ]
        },
        "max_acceptable_lag_hours": {
          "type": "number"
        }
      },
      "required": [
        "declared_frequency",
        "max_acceptable_lag_hours"
      ],
      "additionalProperties": false
    },
    "DatasetGotcha": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "detail": {
          "type": "string"
        }
      },
      "required": [
        "title",
        "detail"
      ],
      "additionalProperties": false
    },
    "DatasetRelated": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "relation": {
          "type": "string"
        },
        "derived": {
          "type": "boolean",
          "description": "true si ESTE dataset es una VIEW derivada del relacionado (hereda su snapshot)."
        }
      },
      "required": [
        "id",
        "relation"
      ],
      "additionalProperties": false
    }
  }
}