# 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-asid-lookup
name: AlgoSeek US Equities ASID Lookup
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
description:
  purpose: One row per persistent algoseek security id (ASID) listing the ticker history and the chain
    of SecIds, with date ranges, that belong to that one security. Lets users stitch price and reference
    history together across SecId changes caused by restructurings such as reclassifications.
  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. ASID vs SecId:
    SecId stays unchanged through name and ticker changes but may change on certain restructurings (guide
    example: reclassification). ASID is the higher-level identifier that stays constant for the whole
    life of the security and links all its SecIds, letting you build uninterrupted price/reference history.
    SecIds and SecIdsStartToEndDate are chronological and positionally aligned; e.g. ASID 1010000000001003
    (ticker AAA) = SecIds 6561562 (20200909:20221014) then 7680133 (20221017:29991231). Boundaries fall
    on consecutive trading days and end dates read as inclusive. Tickers are aggregated across the whole
    SecId chain (e.g. YHOO;AABA for ASID 1010000000001006), so ticker history here can be longer than
    for any single SecId in the ticker Lookup File. A ticker can recur under different ASIDs: AAA 20070103:20070521
    (SecId 78768) is ASID 1010000000001002, while the later AAA (SecIds 6561562, 7680133) is ASID 1010000000001003
    - a ticker is not a security key.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-asid-lookup/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.SecId.Chains.Lookup.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_SECID_CHAINS_LOOKUP}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: Single CSV file (guide names it equity_asid_lookup.csv; published sample is eq_secid_chains_lookup.csv),
      header row first, one row per security record.
  - 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/secid-chains-lookup
  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_asid_lookup
  physicalName: eq_secid_chains_lookup
  physicalType: file
  logicalType: object
  businessName: US Equities ASID Lookup
  description: One row per persistent algoseek security id (ASID) listing the ticker history and the chain
    of SecIds, with date ranges, that belong to that one security. Lets users stitch price and reference
    history together across SecId changes caused by restructurings such as reclassifications.
  dataGranularityDescription: one ASID (one security across its whole life; SecIds and tickers are packed
    into semicolon-delimited lists)
  properties:
  - name: ASID
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek persistent security identifier that stays constant for the whole economic life
      of a security across SecId changes.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: LastTicker
    logicalType: string
    physicalType: string (csv text)
    description: Current ticker, or the last available one if the security no longer trades; in the sample
      always equals the last entry of Tickers.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Tickers
    logicalType: string
    logicalTypeOptions:
      format: semicolon-delimited list, oldest first
    physicalType: string (ticker1;ticker2;...) (csv text)
    description: All ticker symbols used by the security across its SecId chain, chronological; aligned
      with TickersStartToEndDates.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: TickersStartToEndDates
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (29991231 = open-ended)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end date of each ticker. Header is plural here; the guide spells the field TickersStartToEndDate.
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SecIds
    logicalType: string
    logicalTypeOptions:
      format: semicolon-delimited list of SecIds, oldest first
    physicalType: string (secid1;secid2;...) (csv text)
    description: The SecIds that together make up the security (one entry unless a SecId change/restructuring
      occurred), chronological.
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SecIdsStartToEndDate
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (29991231 = open-ended)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end date during which each SecId in SecIds identified the security; last end date
      29991231 if still current.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - 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:
      - ASID
    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_secid_chains_lookup
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_secid_chains_lookup.csv
- property: assetClass
  value: equity
- property: coverage
  value: All listed and delisted US equity securities (stocks, ETFs, ETNs, ADRs, preferred stock, warrants
    and similar) from 2007 to present, with ticker changes and their date ranges. Complementary dataset
    for securities whose SecId changed.
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: yyyymmdd date strings; periods written yyyymmdd:yyyymmdd joined by ';'; end date 29991231 = open-ended
- 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: Header vs guide: sample header (and JSON keys) use TickersStartToEndDates (plural);
    both the ASID guide and the Security Master guide''s Table 10 spell it TickersStartToEndDate.'
  - 'Doc discrepancy: ASID type: this guide (Table 2) says integer, but the Security Master and Lookup
    Files guide (Table 10, v1.7 Oct 2023) says string; sample values are 16-digit numerics. Decision rule:
    treat as an opaque identifier; it fits a signed 64-bit integer.'
  - 'Doc discrepancy: Guide Table 2 typo ''tricker1;ticker2''; Security Master guide Table 10 capitalises
    String for SecIds. Cosmetic only.'
  - 'Doc discrepancy: Same dataset is documented in two guides (this one, v1.1 Jun 2023, and Tables 9-10
    of the Security Master/Lookup guide v1.7 Oct 2023); the field tables agree except for the ASID type
    and the header plural noted above.'
  - 'Doc discrepancy: Guide has no Missing/null column beyond ''Never'' for every field; sample has no
    blanks.'
contractCreatedTs: '2026-11-02T00:00:00Z'