{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vertesiahq/json-schema/vertesiahq-audit-adoption-response-schema.json",
  "title": "AuditAdoptionResponse",
  "description": "Distinct user adoption sets over two equal-duration half-open periods. Ratios use available audit history, not guaranteed historical coverage. No user identities are returned.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vertesiahq-audit-trail-api-openapi.yml#/components/schemas/AuditAdoptionResponse",
  "type": "object",
  "properties": {
    "period": {
      "$ref": "#/$defs/AuditAdoptionPeriod"
    },
    "previous_period": {
      "$ref": "#/$defs/AuditAdoptionPeriod"
    },
    "resolution": {
      "type": "string",
      "enum": [
        "day",
        "week"
      ]
    },
    "active_users": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "previous_active_users": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "retained_users": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "observed_retention": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "returning_user_share": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "repeat_user_share": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "median_active_days": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "active_projects": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "timeline": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AuditAdoptionBucket"
      }
    },
    "active_day_distribution": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AuditAdoptionActiveDays"
      }
    },
    "top_projects": {
      "maxItems": 10,
      "type": "array",
      "items": {
        "$ref": "#/$defs/AuditAdoptionProject"
      }
    },
    "history": {
      "$ref": "#/$defs/AuditAdoptionHistory"
    }
  },
  "required": [
    "period",
    "previous_period",
    "resolution",
    "active_users",
    "previous_active_users",
    "retained_users",
    "observed_retention",
    "returning_user_share",
    "repeat_user_share",
    "median_active_days",
    "active_projects",
    "timeline",
    "active_day_distribution",
    "top_projects",
    "history"
  ],
  "additionalProperties": false,
  "$defs": {
    "AuditAdoptionActiveDays": {
      "type": "object",
      "properties": {
        "days": {
          "type": "integer",
          "minimum": 1,
          "maximum": 367
        },
        "users": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "days",
        "users"
      ],
      "additionalProperties": false
    },
    "AuditAdoptionBucket": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "format": "date-time"
        },
        "to": {
          "type": "string",
          "format": "date-time"
        },
        "partial": {
          "type": "boolean"
        },
        "active_users": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "from",
        "to",
        "partial",
        "active_users"
      ],
      "additionalProperties": false
    },
    "AuditAdoptionHistory": {
      "type": "object",
      "properties": {
        "earliest_observed_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "coverage_from": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "description": "Authoritative complete-history boundary, if known. Earliest observation is not a coverage boundary."
            },
            {
              "type": "null"
            }
          ]
        },
        "completeness": {
          "type": "string",
          "enum": [
            "unknown",
            "insufficient",
            "verified"
          ]
        },
        "retention_unavailable_reason": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "no_previous_users",
                "insufficient_history"
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "earliest_observed_at",
        "coverage_from",
        "completeness",
        "retention_unavailable_reason"
      ],
      "additionalProperties": false
    },
    "AuditAdoptionPeriod": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "format": "date-time"
        },
        "to": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "from",
        "to"
      ],
      "additionalProperties": false
    },
    "AuditAdoptionProject": {
      "type": "object",
      "properties": {
        "project_id": {
          "type": "string"
        },
        "project_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "active_users": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "active_user_days": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "project_id",
        "project_name",
        "active_users",
        "active_user_days"
      ],
      "additionalProperties": false
    }
  }
}