# 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-index-components
name: AlgoSeek US Equities Index Components
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
description:
  purpose: Daily membership lists of major US equity indexes (one ticker and name per component, one file
    per index per trading day), plus a separate per-index change file recording additions, removals and
    name changes. Intended for research and historical backtesting.
  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. TWO TABLES:
    (1) Daily membership (matches the sample): columns ConstituentTicker, ConstituentName, one file per
    index per trading day; this is the table described in `columns`. (2) Change history (not in the sample),
    one file per index, columns per Guide Table 3 example: TradeDate (date, yyyymmdd by example), AddedConstituentTicker,
    AddedConstituentName, DroppedConstituentTicker, DroppedConstituentName. No types, missing rules or
    file name are documented for table 2. Change-file semantics from the guide example (S&P 500): each
    row pairs an added and a dropped constituent on a TradeDate (20211220: EPAM/HBI, FDS/LEG, SBNY/WU),
    but a row may have only an addition (SEDG) or only a drop, so rows are not strictly one-for-one. The
    changes file also records name changes: the FRT row on 20220106 lists the same ticker as both added
    and dropped with slightly different names (trailing period), which is a rename, not a membership change.
    Point-in-time: membership is given per trading day, so reconstruct the as-of set by selecting the
    daily file for the date. The guide warns that actual changes in index members might be delayed by
    a few days in this data, so it is NOT an exact effective-date record; use for research and backtesting
    only, not for compliance or replication. Identifiers: ticker and name only. No SecId, ASID, CUSIP
    or ISIN, no weight, share count, sector or index-code column. Tickers are as of the file date, so
    map to securities with a security master on (ticker, date); share-class tickers use a dot in the sample.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-index-components/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Index.Components.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_INDEX_COMP}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: 'Plain-text CSV with a fixed header; by default one file per trading day per index (example:
      all S&P 500 (SPX) components on 2020-03-03 in one file). A separate file per index holds all historical
      changes. The guide does not state bucket/path or file-name conventions; the published sample is
      eq_index_comp_r2000.csv (Russell 2000 daily list).'
  - 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/index-comp
  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_index_components
  physicalName: eq_index_comp
  physicalType: file
  logicalType: object
  businessName: US Equities Index Components
  description: Daily membership lists of major US equity indexes (one ticker and name per component, one
    file per index per trading day), plus a separate per-index change file recording additions, removals
    and name changes. Intended for research and historical backtesting.
  dataGranularityDescription: one component (ticker) of one index on one trading day, in a daily membership
    file where the index and date are carried by the file, not by a column
  properties:
  - name: ConstituentTicker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol name of the index component on the trading day of the file; share classes use
      a dot (e.g. CRD.A, GEF.B, MOG.A in sample).
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: nullMeaning
      value: unstated (always populated in sample)
    - property: evidence
      value: guide+sample
  - name: ConstituentName
    logicalType: string
    physicalType: string (csv text)
    description: Name of the index component security.
    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:
      - ConstituentTicker
    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: '2007-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_index_comp
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_index_comp_r2000.csv
- property: assetClass
  value: index
- property: coverage
  value: 'Dow Jones Industrial Average, Dow Jones Transportation Average, Dow Jones Utility Average, S&P
    500, NASDAQ 100 (page: based on QQQ holdings), Russell 1000 and Russell 2000. History from 2007, Russell
    indexes from July 2009. Guide note: intended solely for research and backtesting; actual index changes
    may be delayed by a few days.'
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: n/a in the daily file (no date column); changes file TradeDate is yyyymmdd by example
- 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 and page describe two tables per index: a daily components list and a separate
    historical changes file. The published sample is only the daily list (Russell 2000, 1917 rows, columns
    ConstituentTicker and ConstituentName); the changes file is shown only as a sample table (Guide Table
    3) with no type/missing/description table.'
  - 'Doc discrepancy: Neither the daily-list sample nor its guide schema (Table 2) has a date or index-identifier
    column; both are implied by the file (guide example: ''all components for SPX on Mar 3, 2020 are stored
    in one CSV file'') and the file-naming scheme is undocumented.'
  - 'Doc discrepancy: The page says NASDAQ 100 membership is ''based on QQQ holdings''; the guide intro
    lists NASDAQ 100 without that qualifier.'
  - 'Doc discrepancy: Guide Table 3 prints the changes-file header wrapped across lines (e.g. ''AddedConst''
    / ''ituentTicker''); the full names AddedConstituentTicker, AddedConstituentName, DroppedConstituentTicker,
    DroppedConstituentName are reconstructed from the wrapped text and are not confirmed by any sample
    CSV.'
contractCreatedTs: '2026-11-02T00:00:00Z'