FreshnessReport

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pepbank-io/json-schema/pepbank-io-freshness-report-schema.json",
  "title": "FreshnessReport",
  "description": "When sources last succeeded. Extraction uses timestamps from stored study results. lag_hours measures elapsed time, not upstream backlog.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pepbank-io-account-api-openapi.yml#/components/schemas/FreshnessReport",
  "type": "object",
  "properties": {
    "credit": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "enum": [
            "Data from PepBank"
          ]
        },
        "line": {
          "type": "string",
          "description": "Credit sentence. Copy it as written."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "PepBank page for this result. The home page applies when no single page fits."
        },
        "license_url": {
          "type": "string",
          "enum": [
            "https://creativecommons.org/licenses/by/4.0/"
          ]
        }
      },
      "required": [
        "text",
        "url",
        "license_url"
      ]
    },
    "record_type": {
      "type": "string",
      "enum": [
        "freshness_report"
      ]
    },
    "generated_at": {
      "type": "string"
    },
    "data_seq": {
      "type": "integer"
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "last_success_at": {
            "type": "string"
          },
          "watermark": {
            "type": "string"
          },
          "source_latest_known": {
            "type": [
              "string",
              "null"
            ],
            "description": "Upstream latest time is not reported yet. This field is null."
          },
          "lag_hours": {
            "type": "number",
            "description": "Elapsed hours since the last recorded success, not upstream backlog. 9999 means no recorded success."
          },
          "state": {
            "type": "string",
            "enum": [
              "fresh",
              "behind",
              "failing"
            ]
          },
          "open_failed_items": {
            "type": "integer"
          },
          "label": {
            "type": "string"
          },
          "records": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "source",
          "last_success_at",
          "watermark",
          "lag_hours",
          "state"
        ],
        "additionalProperties": {}
      }
    }
  },
  "required": [
    "credit",
    "record_type",
    "generated_at",
    "data_seq",
    "sources"
  ]
}