{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.org/schemas/web-mapper-gpt-map-lineage.schema.json",
  "title": "Web Mapper GPT — Map Lineage & Prompt Cartography Metadata",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "record_id",
    "map_fingerprint",
    "date",
    "model_info",
    "map_info",
    "datasets",
    "prompt_log"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "description": "Version of this metadata schema used to generate the record.",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "examples": ["1.0.0"]
    },
    "record_id": {
      "type": "string",
      "description": "Unique identifier for this map lineage record (UUID recommended).",
      "examples": ["550e8400-e29b-41d4-a716-446655440000"]
    },
"map_fingerprint": {
  "type": "object",
  "additionalProperties": false,
  "required": ["algorithm", "hash"],
  "properties": {
    "algorithm": {
      "type": "string",
      "enum": ["sha256"],
      "description": "Hash algorithm used."
    },
    "hash": {
      "type": "string",
      "description": "Hash of canonicalized map artifacts and configuration."
    },
    "inputs_summary": {
      "type": "array",
      "description": "What was hashed to create the fingerprint.",
      "items": { "type": "string" },
      "examples": [
        "index.html",
        "script.js",
        "style.css",
        "dataset field schemas",
        "layer configuration",
        "stack versions"
      ]
    },
    "parent_fingerprint": {
      "type": "string",
      "description": "Fingerprint of the map this one was derived from, if any."
    },
    "fingerprint_notes": {
      "type": "string",
      "description": "Optional explanation of how the fingerprint was generated."
    }
  }
},

    "date": {
      "type": "object",
      "additionalProperties": false,
      "required": ["creation_timestamp"],
      "properties": {
        "creation_timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp for when the map artifact was generated."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone name when available (e.g., America/Chicago).",
          "examples": ["America/Chicago"]
        }
      }
    },

    "model_info": {
      "type": "object",
      "additionalProperties": false,
      "required": ["human_user", "llm", "agent"],
      "properties": {
        "human_user": {
          "type": "object",
          "additionalProperties": false,
          "required": ["name"],
          "properties": {
            "name": {
              "type": "string",
              "description": "Name or handle of the human user (as provided)."
            },
            "user_id": {
              "type": "string",
              "description": "Optional internal identifier/handle (if you use one)."
            }
          }
        },
        "llm": {
          "type": "object",
          "additionalProperties": false,
          "required": ["name"],
          "properties": {
            "name": {
              "type": "string",
              "description": "LLM model identifier (e.g., gpt-4.1, gpt-5.2-thinking)."
            },
            "provider": {
              "type": "string",
              "description": "Model provider (e.g., OpenAI, Anthropic)."
            },
            "parameters": {
              "type": "object",
              "description": "Optional inference parameters (temperature, top_p, etc.).",
              "additionalProperties": true
            }
          }
        },
        "agent": {
          "type": "object",
          "additionalProperties": false,
          "required": ["name"],
          "properties": {
            "name": {
              "type": "string",
              "description": "Agent/GPT name (e.g., Web Mapper GPT)."
            },
            "url": {
              "type": "string",
              "format": "uri",
              "description": "URL to the agent, if applicable."
            },
            "agent_version": {
              "type": "string",
              "description": "Your internal agent version or release tag."
            }
          }
        }
      }
    },

    "map_info": {
      "type": "object",
      "additionalProperties": false,
      "required": ["title", "description", "stack"],
      "properties": {
        "title": { "type": "string" },
        "description": {
          "type": "string",
          "description": "Human-readable map description derived from user prompts and agent decisions."
        },

        "outputs": {
          "type": "object",
          "description": "Pointers to produced artifacts, if you want to record them.",
          "additionalProperties": false,
          "properties": {
            "demo_url": { "type": "string", "format": "uri" },
            "repo_url": { "type": "string", "format": "uri" },
            "archive_url": { "type": "string", "format": "uri" },
            "local_paths": {
              "type": "array",
              "items": { "type": "string" }
            }
          }
        },

        "stack": {
          "type": "array",
          "minItems": 1,
          "description": "Technology stack used to build the map.",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["name"],
            "properties": {
              "name": {
                "type": "string",
                "description": "Technology name (e.g., leaflet, maplibre-gl, d3)."
              },
              "url": { "type": "string", "format": "uri" },
              "version": { "type": "string" },
              "role": {
                "type": "string",
                "description": "What this tech did (mapping, charts, geocoding, clustering, etc.)."
              }
            }
          }
        },

        "map_parameters": {
          "type": "object",
          "description": "High-level cartographic choices useful for lineage.",
          "additionalProperties": false,
          "properties": {
            "crs": { "type": "string", "description": "CRS/projection if relevant." },
            "initial_view": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "center": {
                  "type": "array",
                  "items": { "type": "number" },
                  "minItems": 2,
                  "maxItems": 2,
                  "description": "[lat, lon] or [y, x]—be explicit in your conventions."
                },
                "zoom": { "type": "number" }
              }
            },
            "basemap": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "name": { "type": "string" },
                "provider": { "type": "string" },
                "url_template": { "type": "string" },
                "attribution": { "type": "string" }
              }
            },
            "layers_summary": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": ["name", "type"],
                "properties": {
                  "name": { "type": "string" },
                  "type": {
                    "type": "string",
                    "enum": ["point", "line", "polygon", "raster", "tile", "heatmap", "cluster", "choropleth", "other"]
                  },
                  "source_dataset_ref": {
                    "type": "string",
                    "description": "Reference to a dataset_id in datasets[]."
                  },
                  "style_notes": { "type": "string" },
                  "interactions": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": ["popup", "tooltip", "filter", "search", "time_slider", "legend", "hover", "select", "download", "other"]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },

    "datasets": {
      "type": "array",
      "minItems": 1,
      "description": "Datasets used or produced during the workflow.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["dataset_id", "name", "type", "description", "fields"],
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Stable identifier for referencing this dataset within the record.",
            "examples": ["ds_01"]
          },
          "name": { "type": "string" },
          "type": {
            "type": "string",
            "enum": ["CSV", "GeoJSON", "Shapefile", "GeoPackage", "TopoJSON", "KML", "FlatGeobuf", "Parquet", "PMTiles", "TileJSON", "Other"]
          },
          "description": { "type": "string" },
          "source": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "url": { "type": "string", "format": "uri" },
              "citation": { "type": "string", "description": "How to cite the dataset (if known)." },
              "retrieved_timestamp": { "type": "string", "format": "date-time" },
              "license": { "type": "string" }
            }
          },

          "geometry": {
            "type": "object",
            "description": "If spatial, record basic geometry metadata.",
            "additionalProperties": false,
            "properties": {
              "has_geometry": { "type": "boolean" },
              "geometry_type": {
                "type": "string",
                "enum": ["Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", "GeometryCollection", "Mixed", "None"]
              },
              "crs": { "type": "string" },
              "feature_count": { "type": "integer", "minimum": 0 },
              "bbox_wgs84": {
                "type": "array",
                "items": { "type": "number" },
                "minItems": 4,
                "maxItems": 4,
                "description": "[minLon, minLat, maxLon, maxLat]"
              }
            }
          },

          "fields": {
            "type": "array",
            "minItems": 1,
            "description": "Field names and value types.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["name", "type"],
              "properties": {
                "name": { "type": "string" },
                "type": {
                  "type": "string",
                  "enum": ["string", "integer", "number", "boolean", "date", "datetime", "object", "array", "unknown"]
                },
                "nullable": { "type": "boolean" },
                "example_values": {
                  "type": "array",
                  "items": { "type": ["string", "number", "boolean", "null"] }
                }
              }
            }
          },

          "transformations": {
            "type": "array",
            "description": "Any processing steps applied (filtering, joins, geocoding, simplification).",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["step"],
              "properties": {
                "step": { "type": "string" },
                "tool": { "type": "string" },
                "parameters": { "type": "object", "additionalProperties": true },
                "timestamp": { "type": "string", "format": "date-time" },
                "notes": { "type": "string" }
              }
            }
          },

          "integrity_notes": {
            "type": "object",
            "description": "Optional data quality + caveats.",
            "additionalProperties": false,
            "properties": {
              "missingness": { "type": "string" },
              "known_issues": { "type": "string" },
              "privacy_sensitivity": {
                "type": "string",
                "enum": ["none", "low", "medium", "high"]
              }
            }
          }
        }
      }
    },

    "prompt_log": {
      "type": "array",
      "minItems": 1,
      "description": "Chronological log of user prompts and (optionally) agent actions.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["turn_index", "role", "content"],
        "properties": {
          "turn_index": { "type": "integer", "minimum": 1 },
          "role": { "type": "string", "enum": ["user", "assistant", "tool", "system"] },
          "content": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" },

          "derived_intent": {
            "type": "string",
            "description": "Optional: agent’s distilled intent of the turn (useful for historians)."
          },
          "decisions": {
            "type": "array",
            "description": "Optional: key decisions made by agent this turn (e.g., chosen field for symbology).",
            "items": { "type": "string" }
          }
        }
      }
    },

    "reproducibility": {
      "type": "object",
      "description": "Optional but extremely useful metadata to re-run the map build later.",
      "additionalProperties": false,
      "properties": {
        "runtime": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "os": { "type": "string" },
            "node_version": { "type": "string" },
            "python_version": { "type": "string" },
            "package_lock_hash": { "type": "string" }
          }
        },
        "repository": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "git_remote": { "type": "string", "format": "uri" },
            "git_commit": { "type": "string" },
            "git_branch": { "type": "string" }
          }
        },
        "build_steps": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Human-readable steps to reproduce (install, build, run, deploy)."
        }
      }
    },

    "ethics_and_compliance": {
      "type": "object",
      "description": "Optional metadata about constraints, licensing, privacy, and intended use.",
      "additionalProperties": false,
      "properties": {
        "dataset_licenses_summary": { "type": "string" },
        "attribution_notes": { "type": "string" },
        "privacy_notes": { "type": "string" },
        "limitations": { "type": "string" }
      }
    }
  }
}