{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://pingcap-datalake.local/schemas/data-product-contract.runtime-view.v0.schema.json",
  "title": "Data Product Runtime-Served Contract View Schema v0.1.0",
  "description": "JSON Schema for runtime-served data product contract views consumed by agents and platform clients.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "view_schema_version",
    "served_at",
    "product",
    "authored_contract",
    "status",
    "assets",
    "schema",
    "freshness",
    "tests",
    "lineage",
    "governance",
    "agent_permissions",
    "observability",
    "compatibility",
    "links"
  ],
  "properties": {
    "view_schema_version": {
      "const": "0.1.0"
    },
    "served_at": {
      "$ref": "#/$defs/dateTime"
    },
    "product": {
      "$ref": "#/$defs/product"
    },
    "authored_contract": {
      "$ref": "#/$defs/authoredContract"
    },
    "status": {
      "$ref": "#/$defs/productStatus"
    },
    "assets": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/runtimeAsset"
      }
    },
    "schema": {
      "$ref": "#/$defs/runtimeSchema"
    },
    "semantics": {
      "$ref": "#/$defs/semantics"
    },
    "freshness": {
      "$ref": "#/$defs/freshnessView"
    },
    "tests": {
      "$ref": "#/$defs/testsView"
    },
    "lineage": {
      "$ref": "#/$defs/lineageView"
    },
    "governance": {
      "$ref": "#/$defs/governanceView"
    },
    "agent_permissions": {
      "$ref": "#/$defs/agentPermissionsView"
    },
    "observability": {
      "$ref": "#/$defs/observabilityView"
    },
    "compatibility": {
      "$ref": "#/$defs/compatibility"
    },
    "links": {
      "$ref": "#/$defs/links"
    },
    "extensions": {
      "type": "object",
      "description": "Namespaced escape hatch for pre-1.0 runtime-view experimentation.",
      "additionalProperties": true
    }
  },
  "$defs": {
    "identifier": {
      "type": "string",
      "pattern": "^[a-z_][a-z0-9_.-]*$"
    },
    "nonEmptyString": {
      "type": "string",
      "minLength": 1
    },
    "semver": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
    },
    "classification": {
      "type": "string",
      "pattern": "^(public|internal|confidential|restricted|pii|financial|customer_data|operational_sensitive|x_[a-z][a-z0-9_]*)(\\.[a-z][a-z0-9_]*)*$"
    },
    "dateTime": {
      "type": "string",
      "format": "date-time"
    },
    "duration": {
      "type": "string",
      "description": "ISO 8601 duration, for example PT24H, P7D, or P90D."
    },
    "urlOrPath": {
      "type": "string",
      "minLength": 1
    },
    "owner": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type", "name"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["team", "user", "service"]
        },
        "name": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "contacts": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["kind", "value"],
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["email", "slack", "github", "url", "other"]
              },
              "value": {
                "$ref": "#/$defs/nonEmptyString"
              }
            }
          }
        }
      }
    },
    "domain": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name"],
      "properties": {
        "name": {
          "$ref": "#/$defs/identifier"
        },
        "description": {
          "$ref": "#/$defs/nonEmptyString"
        }
      }
    },
    "product": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "name", "version", "owner", "domain", "purpose"],
      "allOf": [
        {
          "if": {
            "required": ["kind"],
            "properties": { "kind": { "const": "source" } }
          },
          "then": {
            "properties": { "layer": false }
          },
          "else": {
            "required": ["layer"]
          }
        }
      ],
      "properties": {
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "name": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "version": {
          "$ref": "#/$defs/semver"
        },
        "kind": {
          "type": "string",
          "enum": ["product", "source"],
          "default": "product"
        },
        "layer": {
          "type": "string",
          "enum": ["raw", "staging", "curated", "service"]
        },
        "owner": {
          "$ref": "#/$defs/owner"
        },
        "domain": {
          "$ref": "#/$defs/domain"
        },
        "purpose": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "usage": {
          "$ref": "#/$defs/usage"
        }
      }
    },
    "usage": {
      "type": "object",
      "additionalProperties": false,
      "required": ["intended", "prohibited"],
      "properties": {
        "intended": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/nonEmptyString"
          }
        },
        "prohibited": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/nonEmptyString"
          }
        }
      }
    },
    "authoredContract": {
      "type": "object",
      "additionalProperties": false,
      "required": ["schema_version", "provenance"],
      "properties": {
        "schema_version": {
          "$ref": "#/$defs/semver"
        },
        "provenance": {
          "$ref": "#/$defs/provenance"
        }
      }
    },
    "provenance": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "repository",
        "path",
        "commit_sha",
        "promoted_at",
        "promoter",
        "validation"
      ],
      "properties": {
        "repository": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "path": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "commit_sha": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{40}$"
        },
        "promoted_at": {
          "$ref": "#/$defs/dateTime"
        },
        "promoter": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "validation": {
          "type": "object",
          "additionalProperties": false,
          "required": ["status"],
          "properties": {
            "status": {
              "type": "string",
              "enum": ["passed", "failed", "warning", "unknown"]
            },
            "summary": {
              "$ref": "#/$defs/nonEmptyString"
            },
            "links": {
              "$ref": "#/$defs/links"
            }
          }
        }
      }
    },
    "productStatus": {
      "type": "object",
      "additionalProperties": false,
      "required": ["current"],
      "properties": {
        "current": {
          "type": "string",
          "enum": ["healthy", "degraded", "blocked", "deprecated", "retired", "unknown"]
        },
        "reason": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "updated_at": {
          "$ref": "#/$defs/dateTime"
        },
        "contributors": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["kind", "status"],
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["freshness", "tests", "governance", "lineage", "platform", "compatibility", "other"]
              },
              "status": {
                "$ref": "#/$defs/nonEmptyString"
              },
              "reason": {
                "$ref": "#/$defs/nonEmptyString"
              }
            }
          }
        }
      }
    },
    "runtimeAsset": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "kind", "ref", "status"],
      "properties": {
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "kind": {
          "type": "string",
          "enum": ["table", "view", "model", "file", "api", "notebook", "other"]
        },
        "ref": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "status": {
          "type": "string",
          "enum": ["available", "degraded", "unavailable", "deprecated", "unknown"]
        },
        "description": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "materialization": {
          "type": "string",
          "enum": ["table", "view", "incremental", "external", "ephemeral", "api", "other"]
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "runtimeSchema": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind"],
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["relational", "document", "file", "api", "mixed"]
        },
        "observed_at": {
          "$ref": "#/$defs/dateTime"
        },
        "status": {
          "type": "string",
          "enum": ["matches_contract", "drift_detected", "unknown"]
        },
        "columns": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/column"
          }
        },
        "schema_ref": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "column": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "type"],
      "properties": {
        "name": {
          "$ref": "#/$defs/identifier"
        },
        "type": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "nullable": {
          "type": "boolean"
        },
        "description": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "semantic_type": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "classifications": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/classification"
          }
        }
      }
    },
    "semantics": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "terms": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/semanticTerm"
          }
        },
        "entities": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/semanticTerm"
          }
        },
        "dimensions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/semanticTerm"
          }
        },
        "metrics": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/metric"
          }
        }
      }
    },
    "semanticTerm": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "description"],
      "properties": {
        "name": {
          "$ref": "#/$defs/identifier"
        },
        "description": {
          "$ref": "#/$defs/nonEmptyString"
        }
      }
    },
    "metric": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "expression", "description"],
      "properties": {
        "name": {
          "$ref": "#/$defs/identifier"
        },
        "expression": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "description": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "grain": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "status": {
          "type": "string",
          "enum": ["available", "degraded", "deprecated", "unknown"]
        }
      }
    },
    "freshnessView": {
      "type": "object",
      "additionalProperties": false,
      "required": ["expectation", "current"],
      "properties": {
        "expectation": {
          "type": "object",
          "additionalProperties": false,
          "required": ["max_age"],
          "properties": {
            "max_age": {
              "$ref": "#/$defs/duration"
            },
            "timezone": {
              "$ref": "#/$defs/nonEmptyString"
            },
            "degrade_after": {
              "$ref": "#/$defs/duration"
            }
          }
        },
        "current": {
          "type": "object",
          "additionalProperties": false,
          "required": ["status"],
          "properties": {
            "status": {
              "type": "string",
              "enum": ["fresh", "stale", "missing", "unknown"]
            },
            "observed_at": {
              "$ref": "#/$defs/dateTime"
            },
            "age": {
              "$ref": "#/$defs/duration"
            },
            "reason": {
              "$ref": "#/$defs/nonEmptyString"
            }
          }
        }
      }
    },
    "testsView": {
      "type": "object",
      "additionalProperties": false,
      "required": ["summary", "current"],
      "properties": {
        "summary": {
          "$ref": "#/$defs/testSummary"
        },
        "current": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/testResult"
          }
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "testSummary": {
      "type": "object",
      "additionalProperties": false,
      "required": ["status", "blocking", "degrading", "informational", "experimental"],
      "properties": {
        "status": {
          "type": "string",
          "enum": ["passed", "failed", "degraded", "unknown"]
        },
        "blocking": {
          "$ref": "#/$defs/testCount"
        },
        "degrading": {
          "$ref": "#/$defs/testCount"
        },
        "informational": {
          "$ref": "#/$defs/testCount"
        },
        "experimental": {
          "$ref": "#/$defs/testCount"
        }
      }
    },
    "testCount": {
      "type": "object",
      "additionalProperties": false,
      "required": ["passed", "failed"],
      "properties": {
        "passed": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        },
        "unknown": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "testResult": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "severity", "status"],
      "properties": {
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "severity": {
          "type": "string",
          "enum": ["blocking", "degrading", "informational", "experimental"]
        },
        "status": {
          "type": "string",
          "enum": ["passed", "failed", "skipped", "unknown"]
        },
        "last_run_at": {
          "$ref": "#/$defs/dateTime"
        },
        "message": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "lineageView": {
      "type": "object",
      "additionalProperties": false,
      "required": ["effective"],
      "properties": {
        "effective": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "upstreams": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/lineageRef"
              }
            },
            "downstreams": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/lineageRef"
              }
            }
          }
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "lineageRef": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind", "ref"],
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["data_product", "source", "table", "view", "file", "job", "api", "other"]
        },
        "ref": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "status": {
          "type": "string",
          "enum": ["available", "degraded", "unavailable", "unknown"]
        },
        "contract_version": {
          "$ref": "#/$defs/semver"
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "governanceView": {
      "type": "object",
      "additionalProperties": false,
      "required": ["effective"],
      "properties": {
        "effective": {
          "$ref": "#/$defs/effectiveGovernance"
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "effectiveGovernance": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "classifications": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/classification"
          }
        },
        "inherited_classifications": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/classificationSource"
          }
        },
        "classification_exceptions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/classificationException"
          }
        },
        "access": {
          "$ref": "#/$defs/effectiveAccess"
        },
        "masking": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["field", "policy", "effective_for"],
            "properties": {
              "field": {
                "$ref": "#/$defs/nonEmptyString"
              },
              "policy": {
                "$ref": "#/$defs/nonEmptyString"
              },
              "effective_for": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/identifier"
                }
              }
            }
          }
        },
        "retention": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "period": {
              "$ref": "#/$defs/duration"
            },
            "deletion_policy": {
              "$ref": "#/$defs/nonEmptyString"
            }
          }
        },
        "audit": {
          "type": "object",
          "additionalProperties": false,
          "required": ["required"],
          "properties": {
            "required": {
              "type": "boolean"
            },
            "events": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": ["query", "export", "policy_change", "contract_change", "agent_action", "other"]
              }
            }
          }
        },
        "policy_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/nonEmptyString"
          }
        }
      }
    },
    "classificationSource": {
      "type": "object",
      "additionalProperties": false,
      "required": ["classification", "source_kind", "source_ref"],
      "properties": {
        "classification": {
          "$ref": "#/$defs/classification"
        },
        "source_kind": {
          "type": "string",
          "enum": ["domain", "product", "asset", "field", "policy", "other"]
        },
        "source_ref": {
          "$ref": "#/$defs/nonEmptyString"
        }
      }
    },
    "classificationException": {
      "type": "object",
      "additionalProperties": false,
      "required": ["classification", "reason", "approved_by"],
      "properties": {
        "classification": {
          "$ref": "#/$defs/classification"
        },
        "reason": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "approved_by": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "expires_at": {
          "$ref": "#/$defs/dateTime"
        }
      }
    },
    "effectiveAccess": {
      "type": "object",
      "additionalProperties": false,
      "required": ["default"],
      "properties": {
        "default": {
          "type": "string",
          "enum": ["public", "internal", "restricted", "deny"]
        },
        "allowed_roles": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/identifier"
          }
        },
        "denied_roles": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/identifier"
          }
        },
        "request_policy": {
          "$ref": "#/$defs/nonEmptyString"
        }
      }
    },
    "agentPermissionsView": {
      "type": "object",
      "additionalProperties": false,
      "required": ["effective"],
      "properties": {
        "effective": {
          "$ref": "#/$defs/effectiveAgentPermissions"
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "effectiveAgentPermissions": {
      "type": "object",
      "additionalProperties": false,
      "required": ["default"],
      "properties": {
        "default": {
          "type": "string",
          "enum": ["deny", "observe"]
        },
        "grants": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/agentGrant"
          }
        },
        "denials": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/agentDenial"
          }
        }
      }
    },
    "agentGrant": {
      "type": "object",
      "additionalProperties": false,
      "required": ["principal", "max_risk_tier", "allowed_actions"],
      "properties": {
        "principal": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "max_risk_tier": {
          "type": "string",
          "enum": ["observe", "reversible_workspace", "controlled_operational", "approval_gated"]
        },
        "allowed_actions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/identifier"
          }
        },
        "approval_required_for": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/identifier"
          }
        },
        "constraints": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/nonEmptyString"
          }
        },
        "reason": {
          "$ref": "#/$defs/nonEmptyString"
        }
      }
    },
    "agentDenial": {
      "type": "object",
      "additionalProperties": false,
      "required": ["principal", "actions", "reason"],
      "properties": {
        "principal": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "actions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/identifier"
          }
        },
        "reason": {
          "$ref": "#/$defs/nonEmptyString"
        }
      }
    },
    "observabilityView": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "docs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "url": {
              "$ref": "#/$defs/urlOrPath"
            },
            "generated_at": {
              "$ref": "#/$defs/dateTime"
            }
          }
        },
        "run_history": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "latest_run": {
              "$ref": "#/$defs/runSummary"
            },
            "links": {
              "$ref": "#/$defs/links"
            }
          }
        },
        "incidents": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "open_count": {
              "type": "integer",
              "minimum": 0
            },
            "latest": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/incidentSummary"
              }
            },
            "links": {
              "$ref": "#/$defs/links"
            }
          }
        },
        "metrics": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "links": {
              "$ref": "#/$defs/links"
            }
          }
        }
      }
    },
    "runSummary": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "status"],
      "properties": {
        "id": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "status": {
          "type": "string",
          "enum": ["succeeded", "failed", "running", "canceled", "unknown"]
        },
        "started_at": {
          "$ref": "#/$defs/dateTime"
        },
        "ended_at": {
          "$ref": "#/$defs/dateTime"
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "incidentSummary": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "status", "severity"],
      "properties": {
        "id": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "status": {
          "type": "string",
          "enum": ["open", "mitigated", "resolved", "unknown"]
        },
        "severity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low", "unknown"]
        },
        "summary": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "links": {
          "$ref": "#/$defs/links"
        }
      }
    },
    "compatibility": {
      "type": "object",
      "additionalProperties": false,
      "required": ["change_policy"],
      "properties": {
        "change_policy": {
          "type": "string",
          "enum": ["semver"]
        },
        "deprecation_window": {
          "$ref": "#/$defs/duration"
        },
        "deprecated_at": {
          "$ref": "#/$defs/dateTime"
        },
        "retired_at": {
          "$ref": "#/$defs/dateTime"
        },
        "migration_notes_url": {
          "$ref": "#/$defs/urlOrPath"
        }
      }
    },
    "links": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/urlOrPath"
      }
    }
  }
}