# 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-ipo
name: AlgoSeek US Equities IPO
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
- event
description:
  purpose: One record per newly listing (or planned) US exchange-traded security, tracking the IPO status
    from rumour through first trading day with the security's SecId, ticker, ISIN and first trading date.
    Used for early identification of new listings and security-master upkeep.
  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. Row grain is
    one mutable record per security: the guide says each row is an individual security record and the
    file is rewritten (3 times daily) whenever an IPO event is new or modified, so a point-in-time history
    of Status transitions is NOT retained in the file; snapshot it yourself if you need as-of replay.
    CreatedDate = trading date the record first appeared; ModifiedDate = trading date of the last change
    with an optional _n version suffix (basic sample uses _1/_2/_3; many detailed-sample rows carry a
    bare yyyymmdd). Treat ModifiedDate as a string, not a date. Status NEW and HISTORY are date-driven
    (NEW while listing date is today/yesterday, HISTORY once it is more than 2 days old), so a record''s
    Status can change without a new IPO event; the lifecycle in the guide is RUMOUR -> PENDING -> NEW
    -> HISTORY, with POSTPONED, WITHDRAWN and DLP as other outcomes. SecId is algoseek''s security id
    and is already assigned to PENDING/POSTPONED IPOs; USIdentifier, ISIN and FirstTradingDate are blank
    until known (basic sample: blank in 68, 66 and 75 of 100 rows respectively).'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-ipo/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.IPO.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_IPO}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: Single CSV file (ipo_basic.csv) with a fixed header; one row per security record. The detailed
      variant is a separate file (ipo_detailed.csv). No per-date partitioning stated.
  - 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/ipo
  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_ipo
  physicalName: eq_ipo
  physicalType: file
  logicalType: object
  businessName: US Equities IPO
  description: One record per newly listing (or planned) US exchange-traded security, tracking the IPO
    status from rumour through first trading day with the security's SecId, ticker, ISIN and first trading
    date. Used for early identification of new listings and security-master upkeep.
  dataGranularityDescription: one IPO record per security (SecId), updated in place as the IPO progresses
  properties:
  - name: CreatedDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Trading date on which the IPO record was first created.
    customProperties:
    - property: nullMeaning
      value: unstated (always populated in sample)
    - property: evidence
      value: guide+sample
  - name: ModifiedDate
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd[_n]
    physicalType: string (yyyymmdd[_n]) (csv text)
    description: Trading date of the latest update plus optional _n suffix giving the update version within
      that date.
    customProperties:
    - property: nullMeaning
      value: unstated (always populated in sample)
    - property: evidence
      value: guide+sample
  - name: SecId
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek unique security identifier; present even for pending IPOs.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: nullMeaning
      value: unstated (always populated in sample)
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol name of the security.
    customProperties:
    - property: nullMeaning
      value: unstated (always populated in basic sample)
    - property: evidence
      value: guide+sample
  - name: Name
    logicalType: string
    physicalType: string (csv text)
    description: Security name.
    customProperties:
    - property: nullMeaning
      value: unstated (always populated in sample)
    - property: evidence
      value: guide+sample
  - name: USIdentifier
    logicalType: string
    logicalTypeOptions:
      format: 9-character CUSIP/CINS-style code (per sample)
    physicalType: string (csv text)
    description: Identifier for US securities; blank until assigned.
    customProperties:
    - property: nullMeaning
      value: unstated; blank in 68 of 100 sample rows
    - property: evidence
      value: guide+sample
  - name: ISIN
    logicalType: string
    logicalTypeOptions:
      format: 12-character ISIN
    physicalType: string (csv text)
    description: ISIN code; blank for most PENDING records.
    customProperties:
    - property: nullMeaning
      value: unstated; blank in 66 of 100 sample rows
    - property: evidence
      value: guide+sample
  - name: FirstTradingDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: First trading date of the security; blank until scheduled or for postponed IPOs.
    customProperties:
    - property: nullMeaning
      value: unstated; blank in 75 of 100 sample rows
    - property: evidence
      value: guide+sample
  - name: ExchangeCode
    logicalType: string
    physicalType: string (csv text)
    description: Code identifying the exchange of the IPO listing; values are not enumerated in the guide.
    customProperties:
    - property: nullMeaning
      value: unstated (always populated in sample)
    - property: evidence
      value: guide+sample
  - name: Status
    logicalType: string
    physicalType: string (csv text)
    description: Stage of the IPO event; see Status values.
    enum:
    - value: NEW
      label: IPO is complete or in action; listing date is today or yesterday
    - value: RUMOUR
      label: Company or another respected source announced intent to IPO, before necessary approval
    - value: PENDING
      label: IPO is confirmed and the necessary approval has been made
    - value: HISTORY
      label: IPO has taken place; listing date is more than 2 days earlier
    - value: POSTPONED
      label: IPO temporarily suspended pending further announcement on the placement
    - value: WITHDRAWN
      label: IPO permanently stopped by company or regulator decision
    - value: DLP
      label: Direct Listing Process
    customProperties:
    - property: nullMeaning
      value: unstated (always populated in sample)
    - 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:
      - SecId
    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: 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_ipo
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/ipo_basic.csv
- property: assetClass
  value: equity
- property: venues
  value:
  - USNASD
  - USNYSE
  - USAMEX
  - IRIFX
- property: coverage
  value: IPO data for the whole US market excluding OTC; gathered from local stock exchanges (primary)
    and newspapers/news agencies (secondary). Page says records typically exist several days before the
    first trading day. Guide gives no history start date.
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: yyyymmdd; ModifiedDate = yyyymmdd[_n]
- 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 says IPOs are captured at ''six different stages'' but Table 4 defines seven
    Status values (NEW, RUMOUR, PENDING, HISTORY, POSTPONED, WITHDRAWN, DLP).'
  - 'Doc discrepancy: Guide and page scope the dataset to US exchanges excluding OTC, but the published
    basic sample contains two DLP rows with ExchangeCode IRIFX, ISIN prefix IRO3 and blank USIdentifier
    (non-US listings).'
  - 'Doc discrepancy: Guide Table 1 shows a record with Status NEW and a blank FirstTradingDate, although
    NEW is defined as ''listing date is today or yesterday''.'
  - 'Doc discrepancy: Guide does not list ExchangeCode values; the sample uses USNASD, USNYSE, USAMEX,
    IRIFX.'
  - 'Doc discrepancy: Guide intro says the detailed variant includes Shares Outstanding information, but
    neither the detailed schema (Table 3) nor the detailed sample has a shares-outstanding column (see
    us-equities-ipo-detailed).'
  - 'Doc discrepancy: Guide Table 1 sample rows carry 6-digit SecIds (e.g. 120884) and ModifiedDate values
    without suffix for some rows; published sample SecIds are 7-digit and every ModifiedDate has an _n
    suffix. Not a conflict, only an example-format difference.'
contractCreatedTs: '2026-11-02T00:00:00Z'