# Generated by tools/build_contracts.py from tools/algoseek_catalog.py -- do not edit by hand.
# Open Data Contract Standard v3.2.0 (https://bitol-io.github.io/open-data-contract-standard/).
apiVersion: v3.2.0
kind: DataContract
id: urn:alphaswarm:datacontract:algoseek:us-equities-announcements
name: AlgoSeek US Equities Announcements
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
- event
description:
  purpose: One row per announced ticker change or delisting of a US exchange-listed equity, with announcement
    date, effective date, old/new tickers or delisting exchange. Used to anticipate and replay symbol
    changes and delistings.
  usage: Point-in-time security identity, corporate-action adjustment, and universe construction for US
    equities.
  limitations: 'Vendor-curated reference data: rows can be restated when AlgoSeek learns of a late or
    corrected event, so land each delivery as a snapshot rather than overwriting history. Point-in-time:
    AnnounceDate is when the event became public and EffectiveDate is when it takes effect; the dataset
    covers announcements of FUTURE changes, so EffectiveDate is usually after AnnounceDate (sample: always
    later). Use AnnounceDate for as-of knowledge, EffectiveDate for the symbol/listing switch. EffectiveDate
    holds the effective date published at first announcement; later rescheduling is not stated to be reflected,
    so treat it as the initially announced date, not a confirmed one. Identity: SecId is the algoseek
    security identifier; Ticker is the symbol at announcement. For TickerChange, Ticker = OldTicker in
    every sample row and NewTicker is the post-change symbol; for Delisting, OldTicker/NewTicker are blank
    and DelistingExchange is set. Field applicability by EventType: TickerChange rows use OldTicker/NewTicker
    (DelistingExchange blank); Delisting rows use DelistingExchange (OldTicker/NewTicker blank). In the
    sample 94 of 100 rows are Delisting and 6 are TickerChange.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-announcements/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.Announcements.pdf
  - type: implementation
    url: https://algoseek.com/docs/rest-api/reference
context:
  instructions: Rows are effective-dated. Answer point-in-time questions with the row in force on the
    as-of date, never the latest row. SecId and ASID are both durable AlgoSeek security keys but different
    values (the ASID lookup links them); tickers are reused across companies, so resolve a ticker to a
    key with a trade date.
  constraints:
  - id: c1
    constraint: 'Licensed vendor data: never export raw rows to a tenant-local destination or include
      them verbatim in a public artifact; serve only through entitlement-checked platform reads.'
  - id: c3
    constraint: Do not treat the vendor's `Ticker` as a stable identity across time; join on an AlgoSeek
      security key (SecId or ASID, which are distinct) or the platform symbol mapping.
servers:
- server: algoseek-s3
  type: s3
  environment: vendor
  description: AlgoSeek flat-file delivery (the layout the schema below describes).
  location: s3://${ALGOSEEK_S3_BUCKET_EQ_ANNOUNCE}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: Plain-text CSV with a fixed header row; by default a single file containing all history.
  - property: compression
    value: gzip
  - property: header
    value: true
  - property: entitlement
    value: Bucket access is granted per subscription; bucket names arrive with license provisioning.
- server: algoseek-rest-api
  type: api
  environment: vendor
  description: AlgoSeek Datasets REST API (X-API-KEY header; JSON, CSV or gzipped CSV). Returns AlgoSeek's
    normalized API layout, which differs from the flat-file columns in this contract's schema.
  location: https://api.algoseek.com/v1/data/us-equity-ref/announce
  customProperties:
  - property: auth
    value: X-API-KEY header issued by AlgoSeek
  - property: columnsEndpoint
    value: https://api.algoseek.com/v1/meta/datasets/{dataset_id}/columns
  - property: statusEndpoint
    value: https://api.algoseek.com/v1/meta/datasets/{dataset_id}/status
  - property: responseFormats
    value:
    - json
    - csv
    - csv_gzip
  - property: pagination
    value: offset + limit; tick endpoints take trade_date and identifier (Ticker or ASID) in the path
schema:
- name: us_equities_announcements
  physicalName: eq_announce
  physicalType: file
  logicalType: object
  businessName: US Equities Announcements
  description: One row per announced ticker change or delisting of a US exchange-listed equity, with announcement
    date, effective date, old/new tickers or delisting exchange. Used to anticipate and replay symbol
    changes and delistings.
  dataGranularityDescription: one announced listing event (TickerChange or Delisting) for one security
  properties:
  - name: AnnounceDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Date on which the event was announced.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: EffectiveDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Initial effective date published in the first announcement; blank when the date is not
      yet set. Not updated if the date later moves.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: SecId
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek unique security identifier.
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol name; for TickerChange rows in the sample it equals OldTicker (the pre-change
      symbol).
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: EventType
    logicalType: string
    physicalType: string (csv text)
    description: Type of announced listing event.
    primaryKey: true
    primaryKeyPosition: 3
    required: true
    enum:
    - value: Delisting
      label: Symbol is delisted from a public exchange
    - value: TickerChange
      label: Symbol name is changed to a new symbol
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OldTicker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol before the change; populated for TickerChange only.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: NewTicker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol after the change; populated for TickerChange only.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: DelistingExchange
    logicalType: string
    physicalType: string (csv text)
    description: Exchange the symbol is delisted from; populated for Delisting only (NASDAQ, NYSE, AMEX
      in sample).
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  quality:
  - id: row_count_positive
    metric: rowCount
    mustBeGreaterThan: 0
    dimension: completeness
    severity: error
    description: Every delivered partition (trade date, or snapshot) carries at least one row.
  - id: primary_key_unique
    metric: duplicateValues
    mustBe: 0
    arguments:
      properties:
      - AnnounceDate
      - SecId
      - EventType
    dimension: uniqueness
    severity: error
    description: The declared primary key is unique within each delivered partition (one file or table
      snapshot).
support:
- channel: algoseek-support
  tool: email
  url: mailto:support@algoseek.com
  scope: issues
  description: Vendor support for data defects, missing days, and entitlement problems.
team:
  name: AlphaSwarm data engineering
slaProperties:
- id: history_start
  property: generalAvailability
  value: '2022-01-01'
  description: First trade date of the vendor history.
- id: update_frequency
  property: frequency
  value: 1
  unit: d
  driver: analytics
- id: retention
  property: retention
  value: license-term
  description: Retention of landed copies is bounded by the AlgoSeek license; purge on termination.
  driver: regulatory
customProperties:
- property: vendor
  value: AlgoSeek
- property: vendorDataGroup
  value: us-equity-ref
- property: vendorDatasetTextId
  value: eq_announce
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_announce.csv
- property: assetClass
  value: equity
- property: venues
  value:
  - NASDAQ
  - NYSE
  - AMEX
- property: coverage
  value: 'All announcements of future symbol changes and delistings on public US exchanges; OTC excluded.
    Built from public sources (page: exchange listing announcements and company SEC filings). Available
    from 2022.'
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: yyyymmdd
- property: priceAdjustment
  value: n/a
- property: licensedData
  value: true
- property: evidenceGrade
  value: vendor-doc
- property: knownIssues
  value:
  - Primary key is inferred; AlgoSeek's guide does not name one.
  - 'Doc discrepancy: Guide Table 3 shows the event name as ''Ticker Change'' (wrapped across two lines);
    the published sample uses TickerChange.'
  - 'Doc discrepancy: Guide says EffectiveDate may be blank when the effective date is not yet defined;
    no sample row has a blank EffectiveDate.'
  - 'Doc discrepancy: Guide does not enumerate DelistingExchange; sample has NASDAQ, NYSE, AMEX (71/21/2
    of 94 delistings) and the guide''s own example uses the same three.'
  - 'Doc discrepancy: Guide intro says the data covers ''announces for symbol''s name changes and Delistings'';
    ''name'' means the ticker symbol, there is no company-name field.'
contractCreatedTs: '2026-11-02T00:00:00Z'