EventDetail

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/nordic-financial-news/main/json-schema/nordic-financial-news-event-detail-schema.json",
  "title": "EventDetail",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nordic-financial-news-openapi.yml#/components/schemas/EventDetail",
  "allOf": [
    {
      "$ref": "#/$defs/EventSummary"
    },
    {
      "type": "object",
      "properties": {
        "summary": {
          "type": [
            "string",
            "null"
          ],
          "description": "Event summary (omitted on a tombstone). Null when no summary has been generated for the event yet."
        },
        "article_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "IDs of this event's live articles that your plan can fetch, oldest first by publication time (omitted on a tombstone). May be shorter than `article_count` on a plan with age or source restrictions. That gap is not an error."
        },
        "primary_disclosure_article_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "The primary disclosure among this event's live articles your plan can fetch: the earliest one from a primary-disclosure source (wire service, stock exchange feed, PR platform, or government body). Null when the event has none. Always an element of `article_ids`, or null; omitted on a tombstone. A plan with age or source restrictions may see a later official copy of the same disclosure, or null, instead of the true earliest one."
        },
        "member_figures_disagree": {
          "type": "boolean",
          "description": "True when this event's own member articles report divergent values for the same headline figure (e.g. one source reports operating profit as −2.2m, another as −2.4m). A signal that the single consolidated summary hides a source-level disagreement. Omitted on a tombstone."
        },
        "figure_divergence": {
          "type": [
            "object",
            "null"
          ],
          "description": "Detail behind `member_figures_disagree`: the specific metrics whose values disagree across member articles, with the per-source figures and range. Null when there is no disagreement; omitted on a tombstone.",
          "properties": {
            "groups": {
              "type": "array",
              "description": "One entry per disagreeing metric.",
              "items": {
                "type": "object",
                "properties": {
                  "concept": {
                    "type": "string",
                    "description": "The canonical measure that disagrees"
                  },
                  "basis": {
                    "type": "string",
                    "description": "Whether the measure is as-reported or an adjusted/alternative one"
                  },
                  "role": {
                    "type": "string",
                    "description": "Whether the figure is an outcome, forecast, or comparative"
                  },
                  "period": {
                    "type": "string",
                    "description": "The reporting period the figure covers"
                  },
                  "currency": {
                    "type": "string",
                    "description": "ISO currency of the figures"
                  },
                  "labels": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The source's own wording(s) for the measure"
                  },
                  "min": {
                    "type": "number",
                    "description": "Smallest reported value (absolute base units)"
                  },
                  "max": {
                    "type": "number",
                    "description": "Largest reported value (absolute base units)"
                  },
                  "values": {
                    "type": "array",
                    "description": "The reported figure per member article.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The reporting article's id"
                        },
                        "source": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The reporting source's name"
                        },
                        "normalized_value": {
                          "type": "number",
                          "description": "The figure in absolute base units"
                        },
                        "value": {
                          "type": "string",
                          "description": "The figure as originally stated"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "companies": {
          "type": "array",
          "description": "The same companies as `company_ids`, with detail per company: name, ticker, primary flag, association tier. Primary company first; omitted on a tombstone.",
          "items": {
            "type": "object",
            "required": [
              "id",
              "name",
              "is_primary",
              "association_tier"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique company identifier"
              },
              "name": {
                "type": "string",
                "description": "Company name"
              },
              "ticker": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Primary stock ticker"
              },
              "is_primary": {
                "type": "boolean",
                "description": "Whether this company is the primary subject of the event"
              },
              "association_tier": {
                "type": "string",
                "enum": [
                  "principal",
                  "peripheral"
                ],
                "description": "How the company relates to the event. `principal` (subject, acquirer, target, investor, issuer, partner) is the default set; `peripheral` (advisor, speaker, passing mention) appears only when `include_peripheral=true`. Always present."
              }
            }
          }
        }
      }
    }
  ],
  "$defs": {
    "EventSummary": {
      "type": "object",
      "required": [
        "id",
        "status",
        "updated_at"
      ],
      "description": "An event: one real-world development, grouping the articles that report it. A `merged` or `removed` event (see `status`) returns only the minimal tombstone fields (`id`, `status`, `merged_into`, `updated_at`). Title, significance, event_type, counts, and every id array are omitted, never null-but-present, so a tombstone carries no content.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique event identifier"
        },
        "title": {
          "type": "string",
          "description": "Event title (omitted on a tombstone)"
        },
        "status": {
          "type": "string",
          "description": "Lifecycle status. `active`/`closed` are live (closed = coverage window lapsed but the event stays visible and can reopen). `merged` = absorbed into another event (see `merged_into`); `removed` = withdrawn from the feed (no live articles remain, or it was found to be incorrect). `merged`/`removed` never appear in the default list and carry only the tombstone fields.",
          "enum": [
            "active",
            "closed",
            "merged",
            "removed"
          ]
        },
        "significance": {
          "type": "string",
          "description": "Editorial importance (omitted on a tombstone). `notable` = front-page-worthy; `routine` = factual ledger record; `commentary` = single-article opinion/analysis.",
          "enum": [
            "notable",
            "routine",
            "commentary"
          ]
        },
        "event_type": {
          "type": [
            "object",
            "null"
          ],
          "description": "The kind of event (omitted on a tombstone)",
          "properties": {
            "slug": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "category": {
              "type": "string"
            }
          }
        },
        "article_count": {
          "type": "integer",
          "description": "Number of live articles reporting this event (omitted on a tombstone). This is the total count. Your plan's age and source restrictions do not reduce it; use GET on the event to see which of them your plan can fetch."
        },
        "first_reported_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When this event was first reported (ISO 8601, omitted on a tombstone): the earliest known publication time among this event's member articles. Falls back to `last_article_at` for ordering when null. This is editorial time, not the time the record reached this API."
        },
        "last_article_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Publication time of the newest article reporting this event (ISO 8601, omitted on a tombstone)."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "When this record last changed (ISO 8601). This is the clock incremental sync runs on. Pass your last completed sync time as `updated_after`, drain every page via `pagination.next_cursor`, and only then advance your stored timestamp."
        },
        "company_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "IDs of companies associated with this event, verified and visible only (omitted on a tombstone). Restricted to companies with an active-involvement role (subject, acquirer, target, investor, issuer, partner) unless `include_peripheral=true`."
        },
        "story_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "IDs of published stories generated from this event, if any (omitted on a tombstone)"
        },
        "merged_into": {
          "type": [
            "string",
            "null"
          ],
          "description": "ID of the surviving event this one was merged into. Present only when `status` is `merged`; null for every other status, including `removed` and on some older merged events."
        },
        "related_to": {
          "type": [
            "string",
            "null"
          ],
          "description": "Commentary-only metadata: the `id` of the factual event this commentary event comments on or reacts to, when the piece is about a specific factual event. Always null for non-commentary events, and often null for commentary events too (the piece may not be about a specific event). Filter with `related_to=<id>` to find commentary reacting to a given event."
        }
      }
    }
  }
}