api.locus.report

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "A `kind`-discriminated union: `local_trend_brief` for paid cited trend context, or `coverage_diagnostic` for a free pre-charge coverage diagnostic.",
  "oneOf": [
    {
      "additionalProperties": {},
      "properties": {
        "caveats": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "chargeable": {
          "type": "boolean"
        },
        "citations": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "datasetId": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "sourceName": {
                "type": "string"
              },
              "sourceUrl": {
                "type": "string"
              }
            },
            "required": [
              "label",
              "sourceName",
              "sourceUrl",
              "datasetId"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "citedCards": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "cardId": {
                "type": "string"
              },
              "category": {
                "type": "string"
              },
              "jurisdictionId": {
                "type": "string"
              },
              "sourceUrl": {
                "type": "string"
              }
            },
            "required": [
              "cardId",
              "jurisdictionId",
              "category",
              "sourceUrl"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "communitySignal": {
          "items": {
            "additionalProperties": {},
            "properties": {
              "body": {
                "type": "string"
              },
              "claimType": {
                "type": "string"
              },
              "evidenceUrl": {
                "format": "uri",
                "type": "string"
              },
              "jurisdictionId": {
                "type": "string"
              },
              "label": {
                "const": "contested",
                "type": "string"
              },
              "observationId": {
                "type": "string"
              },
              "placeLabel": {
                "type": "string"
              },
              "status": {
                "type": "string"
              }
            },
            "required": [
              "label",
              "observationId",
              "jurisdictionId",
              "claimType",
              "body",
              "status",
              "placeLabel"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "coverage": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "datasetId": {
                "type": "string"
              },
              "lookbackCovered": {
                "type": "boolean"
              },
              "recordCount": {
                "type": "number"
              },
              "source": {
                "enum": [
                  "permits",
                  "code_violations",
                  "service_requests_311",
                  "crimes"
                ],
                "type": "string"
              },
              "sourceUrl": {
                "type": "string"
              },
              "status": {
                "enum": [
                  "ok",
                  "empty",
                  "unavailable"
                ],
                "type": "string"
              }
            },
            "required": [
              "source",
              "datasetId",
              "status",
              "recordCount",
              "lookbackCovered",
              "sourceUrl"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "generatedAt": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "intent": {
          "type": "string"
        },
        "intentRulesetVersion": {
          "type": "string"
        },
        "kind": {
          "const": "local_trend_brief",
          "type": "string"
        },
        "lookbackMonths": {
          "type": "number"
        },
        "place": {
          "additionalProperties": false,
          "properties": {
            "coverageStatus": {
              "enum": [
                "supported",
                "supported_partial",
                "discovery_only",
                "unsupported"
              ],
              "type": "string"
            },
            "input": {
              "type": "string"
            },
            "jurisdictionId": {
              "type": "string"
            },
            "resolved": {
              "type": "string"
            }
          },
          "required": [
            "input",
            "jurisdictionId",
            "coverageStatus"
          ],
          "type": "object"
        },
        "questionsToAsk": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "refinement": {
          "additionalProperties": {},
          "properties": {
            "context": {
              "additionalProperties": false,
              "properties": {
                "emphasizedSources": {
                  "items": {
                    "enum": [
                      "permits",
                      "code_violations",
                      "service_requests_311",
                      "crimes"
                    ],
                    "type": "string"
                  },
                  "type": "array"
                },
                "input": {
                  "type": "string"
                },
                "rationale": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "required": [
                "input",
                "emphasizedSources",
                "rationale"
              ],
              "type": "object"
            },
            "followUp": {
              "additionalProperties": false,
              "properties": {
                "answer": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "caveats": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "citations": {
                  "items": {
                    "additionalProperties": false,
                    "properties": {
                      "datasetId": {
                        "type": "string"
                      },
                      "label": {
                        "type": "string"
                      },
                      "sourceName": {
                        "type": "string"
                      },
                      "sourceUrl": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "label",
                      "sourceName",
                      "sourceUrl",
                      "datasetId"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "gatedReason": {
                  "type": "string"
                },
                "gatedReasonCode": {
                  "type": "string"
                },
                "question": {
                  "type": "string"
                },
                "status": {
                  "enum": [
                    "answered",
                    "gated",
                    "unsupported"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "question",
                "status",
                "answer",
                "citations",
                "caveats"
              ],
              "type": "object"
            }
          },
          "type": "object"
        },
        "series": {
          "items": {
            "additionalProperties": {},
            "properties": {
              "bucket": {
                "enum": [
                  "monthly",
                  "quarterly"
                ],
                "type": "string"
              },
              "categoryBreakdown": {
                "additionalProperties": false,
                "properties": {
                  "top": {
                    "items": {
                      "additionalProperties": false,
                      "properties": {
                        "baselineCount": {
                          "type": "number"
                        },
                        "count": {
                          "type": "number"
                        },
                        "delta": {
                          "type": "number"
                        },
                        "label": {
                          "type": "string"
                        },
                        "recentCount": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "label",
                        "count",
                        "recentCount",
                        "baselineCount",
                        "delta"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "totalCategorized": {
                    "type": "number"
                  },
                  "uncategorized": {
                    "type": "number"
                  }
                },
                "required": [
                  "top",
                  "totalCategorized",
                  "uncategorized"
                ],
                "type": "object"
              },
              "change": {
                "additionalProperties": false,
                "properties": {
                  "absoluteDelta": {
                    "type": "number"
                  },
                  "direction": {
                    "enum": [
                      "up",
                      "down",
                      "flat"
                    ],
                    "type": "string"
                  },
                  "method": {
                    "enum": [
                      "first-half-vs-second-half",
                      "year-over-year"
                    ],
                    "type": "string"
                  },
                  "pctChange": {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "direction",
                  "absoluteDelta",
                  "pctChange",
                  "method"
                ],
                "type": "object"
              },
              "confidence": {
                "enum": [
                  "low",
                  "medium",
                  "high"
                ],
                "type": "string"
              },
              "key": {
                "type": "string"
              },
              "points": {
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "count": {
                      "type": "number"
                    },
                    "periodStart": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "periodStart",
                    "count"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "source": {
                "enum": [
                  "permits",
                  "code_violations",
                  "service_requests_311",
                  "crimes"
                ],
                "type": "string"
              }
            },
            "required": [
              "key",
              "source",
              "bucket",
              "points",
              "change",
              "confidence"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "storage": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "contentHash": {
                "type": "string"
              },
              "locator": {
                "type": "string"
              },
              "pinned": {
                "type": "boolean"
              },
              "provider": {
                "type": "string"
              }
            },
            "required": [
              "provider",
              "locator",
              "contentHash"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "verifyNext": {
          "items": {
            "additionalProperties": {},
            "properties": {
              "source": {
                "type": "string"
              },
              "step": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            },
            "required": [
              "step"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "whatThisDoesNotProve": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "whatThisMayMean": {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "kind",
        "id",
        "generatedAt",
        "place",
        "intent",
        "intentRulesetVersion",
        "lookbackMonths",
        "coverage",
        "series",
        "whatThisMayMean",
        "whatThisDoesNotProve",
        "questionsToAsk",
        "citations",
        "caveats",
        "citedCards",
        "chargeable"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "candidateSources": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "category": {
                "type": "string"
              },
              "sourceName": {
                "type": "string"
              },
              "sourceUrl": {
                "type": "string"
              }
            },
            "required": [
              "category",
              "sourceName",
              "sourceUrl"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "caveats": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "charged": {
          "const": false,
          "type": "boolean"
        },
        "intent": {
          "type": "string"
        },
        "kind": {
          "const": "coverage_diagnostic",
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "place": {
          "additionalProperties": false,
          "properties": {
            "coverageStatus": {
              "enum": [
                "discovery_only",
                "unsupported",
                "insufficient_data",
                "source_unavailable"
              ],
              "type": "string"
            },
            "input": {
              "type": "string"
            },
            "jurisdictionId": {
              "type": "string"
            },
            "resolved": {
              "type": "string"
            }
          },
          "required": [
            "input",
            "coverageStatus"
          ],
          "type": "object"
        },
        "preflight": {
          "additionalProperties": false,
          "properties": {
            "note": {
              "type": "string"
            },
            "tool": {
              "type": "string"
            },
            "url": {
              "type": "string"
            }
          },
          "required": [
            "tool",
            "url",
            "note"
          ],
          "type": "object"
        },
        "requestCoverage": {
          "additionalProperties": false,
          "properties": {
            "endpoint": {
              "type": "string"
            },
            "note": {
              "type": "string"
            },
            "tool": {
              "type": "string"
            }
          },
          "required": [
            "tool",
            "endpoint",
            "note"
          ],
          "type": "object"
        },
        "sourceCounts": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "recordCount": {
                "type": "number"
              },
              "source": {
                "type": "string"
              }
            },
            "required": [
              "source",
              "recordCount"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "whatWeWouldNeed": {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "kind",
        "place",
        "intent",
        "charged",
        "message",
        "candidateSources",
        "whatWeWouldNeed",
        "caveats"
      ],
      "type": "object"
    }
  ]
}