api.truthbear.co

{
  "properties": {
    "official": {
      "additionalProperties": true,
      "conditionalProperties": {
        "decision_points": {
          "description": "Swappable decision points for this entity, attached centrally: {count, points:[{tag,current,swappable,how}], note}. Present only when the entity has at least one swappable tag in the index, so bundles for entities without one omit it",
          "type": [
            "object",
            "null"
          ]
        },
        "last_fact": {
          "description": "Most recent qualifying fact for this line and entity, attached centrally (may be absent when the line has no qualifying fact yet)",
          "type": [
            "object",
            "null"
          ]
        },
        "leg_availability": {
          "description": "Per-leg degradation disclosure: which legs are present, which are degraded and why. Present only when at least one leg is degraded",
          "type": [
            "object",
            "null"
          ]
        },
        "record_hash_verifiable": {
          "description": "Whether this response can recompute its own record_hash offline. Present only when the payload carries a top-level record_hash; may be absent on list-shaped deliveries where verifiability is stated per row instead",
          "type": [
            "object",
            "null"
          ]
        }
      },
      "properties": {
        "_citation": {
          "description": "Offline-verifiable citation: {statement_type, not_advice:bool, claim, fact, source, record_hash, signature(Ed25519), key_id, issuer_DID(did:key), verify_url} - the trust root for zero-trust self-verification",
          "type": [
            "object",
            "null"
          ]
        },
        "change": {
          "description": "Change, nested per metric: change.<metric> = {delta, direction, direction_reason?}, plus the scalar change.period (e.g. \"vs_previous\"). direction is one of rising/falling/stable/unknown - unknown means the direction CANNOT BE DETERMINED, it does not mean stable; in that case direction_reason carries a machine-readable cause: no-previous-record / metric-absent-in-previous / metric-absent-in-current / non-numeric-value",
          "type": [
            "object",
            "null"
          ]
        },
        "current": {
          "description": "Current reading. The inner metric structure varies by signal (crypto -> {price_usd, volume_24h, ...}; shipping -> {wind_kmh, wave_height_m, ...}). Units are carried in the field-name suffix; see also standard_ruler.unit",
          "type": [
            "object",
            "null"
          ]
        },
        "data_age_hours": {
          "description": "Age frozen at collection time (0 = same hour), for reference only - if a collector stalls this field stops moving. For freshness always use provenance.age_hours_now (computed at request time) and provenance.freshness; the threshold basis is in provenance.freshness_basis",
          "type": [
            "number",
            "null"
          ]
        },
        "decision_points": {
          "description": "{count, points:[{tag,current,swappable,how}], note} - decision points you can re-run with a swapped tag (one swapped tag = one call); leave it alone and the original context is the default, at no extra charge",
          "type": [
            "object",
            "null"
          ]
        },
        "entity": {
          "description": "Monitored object id (e.g. btc / us / hormuz); full list at free /gauge/catalog or /gauge/preview",
          "type": "string"
        },
        "entity_name": {
          "description": "Human-readable name of the object",
          "type": [
            "string",
            "null"
          ]
        },
        "grade": {
          "description": "Honest data-grade disclosure (e.g. \"screening-level, not decision-grade\")",
          "type": [
            "string",
            "null"
          ]
        },
        "hash_core_version": {
          "description": "Core-contract version of record_hash (currently 3); use it to pick the right core composition when recomputing offline",
          "type": [
            "integer",
            "null"
          ]
        },
        "lifecycle": {
          "description": "Lifecycle block (state / birth_at / end_at / death_type / context). Part of the record_hash v3 core, so offline recomputation must include it; null for non-lifecycle lines",
          "type": [
            "object",
            "null"
          ]
        },
        "nature": {
          "description": "Neutrality statement: GAUGE supplies observations and trend description only - no judgement, no prediction, no recommendation",
          "type": "string"
        },
        "observed_at": {
          "description": "Actual observation time of the data, ISO-8601",
          "type": "string"
        },
        "ots_status": {
          "description": "RETIRED FIELD - always \"pending\" or null; this field is no longer updated and is kept only for older parsers. Anchoring itself resumed on 2026-08-15 as a daily Merkle root stamped via OpenTimestamps - it proves the day set existed no later than the stamp time, and is exposed at free /gauge/anchor (not here). For per-record self-verification use record_hash (canonical sha256, recomputable offline) plus free /gauge/verify",
          "type": [
            "string",
            "null"
          ]
        },
        "previous": {
          "description": "Previous-period reading (a subset of the metrics in current; or {note} explaining that there is no previous value)",
          "type": [
            "object",
            "null"
          ]
        },
        "provenance": {
          "description": "Data lineage: {served_from, data_as_of, oldest_leg_as_of, data_age_hours (frozen age, reference only), age_hours_now (age computed at request time - the real basis for freshness), freshness(fresh|recent|stale), freshness_basis (the cadence and threshold used for this row, as a string), dead_source (optional: upstream frozen or discontinued), data_lineage:[{signal,traceable_to,uncertainty,record_hash,...}], validation_status}. Freshness is cadence-aware, so monthly/quarterly/annual official lines are not misjudged against a 24h rule; the same basis is used by free /gauge/coverage. Buyers can trace back to the official source",
          "type": [
            "object",
            "null"
          ]
        },
        "record_hash": {
          "description": "sha256:<64hex> (contract A v3, binds the values plus provenance)",
          "type": [
            "string",
            "null"
          ]
        },
        "record_hash_verifiable": {
          "description": "{mode:offline|via-endpoint, note}",
          "type": [
            "object",
            "null"
          ]
        },
        "scope": {
          "description": "Honest statement of scope and limits: monitoring is not forecasting, intelligence is not instruction, and the boundary of what is verifiable",
          "type": [
            "string",
            "null"
          ]
        },
        "signal_id": {
          "description": "Signal id in genus.species ASCII binomial form (e.g. crypto.spot / macro.unemployment / shipping.route-disruption); full list at free /gauge/catalog",
          "type": "string"
        },
        "snapshot_date": {
          "description": "ISO-8601 date-time in UTC (e.g. 2026-07-24T00:00:00.000Z; aligned to midnight of that day)",
          "type": "string"
        },
        "source_agreement_cv": {
          "description": "Multi-source agreement, coefficient of variation (smaller = closer agreement). Present ONLY when two or more CONFIRMED-INDEPENDENT sources measure the same fact at the same time - see sources[].independent. Same source relayed through two channels does not count as independent, and two different time bases (daily mean vs spot) do not count as agreement. Single-source / unconfirmed independence / not applicable -> null",
          "type": [
            "number",
            "null"
          ]
        },
        "source_ref": {
          "description": "Official source URL (provenance)",
          "type": [
            "string",
            "null"
          ]
        },
        "source_tier": {
          "description": "Source tier: T1 (first-hand official) / T2 or T2-<subtype, e.g. T2-exchange> (observable, curated) / screen-viewpoint; null = untiered (see unverified)",
          "type": [
            "string",
            "null"
          ]
        },
        "sources": {
          "description": "Source list [{name, value, weight, as_of, role, independent, relay_of?}]. independent:true = confirmed independent source; false = confirmed relay channel of another source (relay_of names the origin); null = independence unconfirmed (neither denied nor claimed). name/weight/independent/relay_of are record_hash core fields, so tampering with an independence claim breaks self-verification; as_of/value/role drift easily and are not hashed",
          "items": {
            "type": "object"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "standard_ruler": {
          "description": "Official standard ruler (band / thresholds / normalized_index / pct_to_action, with unit and provenance); null when the line has no official ruler. Inner structure varies by signal",
          "type": [
            "object",
            "null"
          ]
        },
        "stat_ruler": {
          "description": "Statistical ruler: empirical percentile position across the last 5 same-season years; null when there are no statistics",
          "type": [
            "object",
            "null"
          ]
        },
        "strata": {
          "description": "Statistical strata: share of each official band over the last 5 same-season years plus the band the current value falls in; null when there are no statistics",
          "type": [
            "object",
            "null"
          ]
        },
        "summary_en": {
          "description": "Conditional - English one-line verdict derived at request time from this same record: reading + where it sits on the official ruler (distance to the first official alert) + seasonal percentile + direction, and staleness only when the data is actually old. Purely descriptive, never advice or forecast. Absent when this line carries no official ruler and no seasonal statistics (there is then nothing to conclude beyond the raw upstream reading). Not part of the record_hash core",
          "type": "string"
        },
        "summary_zh": {
          "description": "Human-readable one-line summary, IN CHINESE (zh-TW): reading + where it sits on the official ruler + statistical position. This is the HUMAN front-desk copy - machine consumers should read summary_en (English verdict) instead",
          "type": [
            "string",
            "null"
          ]
        },
        "tier": {
          "description": "Marker for the main single-point or history-series response (full / history-series); mutually exclusive with dim/addon",
          "type": "string"
        },
        "trend_7d": {
          "description": "Array of the last 7 trend points; [] means this signal has no series yet or the series does not apply - it is not an error",
          "items": {
            "type": "object"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "unverified": {
          "description": "true = the source is untiered (source_tier is null); buyers and agents can filter on this",
          "type": "boolean"
        },
        "update_status": {
          "description": "Did the OFFICIAL source keep its own declared publication cadence? Separate dimension from freshness: a record can be freshness=recent and update_status=overdue at the same time. state: on_schedule | overdue | not_published | unknown",
          "properties": {
            "official_cadence": {
              "description": "The cadence the official source declares for this line (hourly/daily/weekly/monthly/quarterly/yearly/as-events)",
              "type": [
                "string",
                "null"
              ]
            },
            "overdue_days": {
              "description": "How many days past that cadence; null when it cannot be determined",
              "type": [
                "integer",
                "null"
              ]
            },
            "state": {
              "description": "on_schedule | overdue | not_published | unknown",
              "type": "string"
            },
            "text": {
              "description": "One-line human-readable form of the same fact",
              "type": "string"
            }
          },
          "type": "object"
        }
      },
      "required": [
        "nature"
      ],
      "type": "object"
    },
    "separation": {
      "description": "{rule, why} - machine-readable statement of the isolation guarantee, so a buyer never has to infer it from prose",
      "type": "object"
    },
    "unverified": {
      "description": "UNVERIFIED half, structurally separated: public-channel chatter from the last 48h plus a non-reproducible LLM trend summary. Never merged into the authoritative half and never part of its hash",
      "type": "object"
    }
  },
  "required": [
    "official",
    "unverified",
    "separation"
  ],
  "type": "object"
}