# 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-basic-adjustment-factors
name: AlgoSeek US Equities Basic Adjustment Factors
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
description:
  purpose: One row per corporate event (dividend, split, spin-off, etc.) affecting a US equity SecId,
    giving the multiplicative factor and reason code needed to build forward- or backward-adjusted price
    and volume series. Basic version carries only the essentials; the Detailed version adds name, report
    date, event type, free-text detail and ISIN.
  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. AdjustmentFactor
    is a multiplicative per-event ratio. Backward adjustment (anchored on the latest date): a price dated
    D is multiplied by the product of the AdjustmentFactor of every event whose EffectiveDate is later
    than D; prices on or after the latest EffectiveDate use AF=1. An event therefore changes only dates
    strictly before its EffectiveDate. Guide worked example (formulas are images in the PDF), AAPL 2014
    with f1=0.995050548 (20140807 CashDiv), f2=0.142857143 (20140609 BonusSame), f3=0.994445664 (20140508
    CashDiv): prices from 20140807 use AF=1; 20140609-20140806 use f1 (0.99505); 20140508-20140608 use
    f1*f2 (0.14215); earlier dates use f1*f2*f3 (0.14136). Volume is DIVIDED by the corresponding cumulative
    factor, and only events with Affects Volume = Yes enter that product (BonusSame, CapReduct, Cons,
    ScriptDiv, SecSwap, Reclass, Subdiv). In the guide example only the 20140609 BonusSame touches volume,
    so volumes before 20140609 are divided by 0.142857143 (x7) and later volumes by 1. Price-only reasons
    (CashDiv, Distrib, DeMerg, rights, etc.) must not be applied to volume. Forward adjustment is said
    to be possible (''forward- or backward-adjusted pricing'') but this guide only walks through the backward
    procedure; the Cumulative Adjustment Factors dataset publishes ready-made forward factors.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-basic-adjustment-factors/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.Adjustment.Factors.Basic.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_ADJ_FACTORS_BASIC}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: 'Plain-text CSV files, fixed header row first, one row per corporate event. Two aggregation
      options with identical fields: ''tradedate'' (files per effective date; guide wording ''one CSV
      file with data per symbol per effective date'' is ambiguous, but its example says all events on
      Mar 3, 2020 sit in one separate file) and ''SecId'' (one CSV per SecId per year, e.g. 33449/AAPL).
      Bucket names are not stated for this dataset.'
  - 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/adj-factors-basic
  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
- server: algoseek-ardadb
  type: clickhouse
  environment: vendor
  description: ArdaDB (managed ClickHouse) table named in AlgoSeek's algoseek-connector code.
  host: ${ALGOSEEK_ARDADB_HOST}
  port: ${ALGOSEEK_ARDADB_PORT:-8123}
  database: USEquityReferenceData
  customProperties:
  - property: table
    value: USEquityReferenceData.BasicAdjustments
  - property: client
    value: algoseek-connector / clickhouse-connect
schema:
- name: us_equities_basic_adjustment_factors
  physicalName: eq_adj_factors_basic
  physicalType: file
  logicalType: object
  businessName: US Equities Basic Adjustment Factors
  description: One row per corporate event (dividend, split, spin-off, etc.) affecting a US equity SecId,
    giving the multiplicative factor and reason code needed to build forward- or backward-adjusted price
    and volume series. Basic version carries only the essentials; the Detailed version adds name, report
    date, event type, free-text detail and ISIN.
  dataGranularityDescription: one corporate event (AdjustmentReason + EventId) for one SecId on its EffectiveDate
  properties:
  - name: SecId
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek unique security identifier the event applies to.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: Ticker on the EffectiveDate; may be empty for events that occurred while the security
      was OTC.
    customProperties:
    - property: nullMeaning
      value: 'Blank (FAQ: security was OTC at the time of the event)'
    - property: evidence
      value: guide+sample
  - name: EffectiveDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (YYYYMMDD) (csv text)
    description: Date the corporate event becomes effective; the factor applies to dates before it.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: AdjustmentFactor
    logicalType: number
    physicalType: decimal (csv text)
    description: 'Per-event multiplicative factor: multiply earlier prices by it; divide earlier volumes
      by it when the reason affects volume.'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: AdjustmentReason
    logicalType: string
    physicalType: string (csv text)
    description: Reason for the corporate event; one of 18 codes in the guide's reason table (CashDiv,
      BonusSame, Subdiv, ...). Determines whether price and/or volume is adjusted.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    enum:
    - value: BonusSame
      label: 'Bonus issue in the same class [event type BON; affects price: Yes; affects volume: Yes]'
    - value: BonusDiff
      label: 'Bonus issue in a different class [event type BON; affects price: Yes; affects volume: No]'
    - value: CapReduct
      label: 'Capital reduction [event type CAPRD; affects price: Yes; affects volume: Yes]'
    - value: Cons
      label: 'Consolidation [event type CONSD; affects price: Yes; affects volume: Yes]'
    - value: Distrib
      label: 'Distribution [event type DIST; affects price: Yes; affects volume: No]'
    - value: CashDiv
      label: 'Cash dividend [event type DIV; affects price: Yes; affects volume: No]'
    - value: ScriptDiv
      label: 'Script dividend in the same class [event type DIV; affects price: Yes; affects volume: Yes]'
    - value: ScriptDivDiff
      label: 'Script dividend in a different class [event type DIV; affects price: Yes; affects volume:
        No]'
    - value: ParLiq
      label: 'Partial liquidation [event type LIQ; affects price: Yes; affects volume: No]'
    - value: DeMerg
      label: 'De-merger [event type DMRGR; affects price: Yes; affects volume: No]'
    - value: EntSame
      label: 'Entitlement in the same class [event type ENT; affects price: Yes; affects volume: No]'
    - value: EntDiff
      label: 'Entitlement in a different class [event type ENT; affects price: Yes; affects volume: No]'
    - value: CapRet
      label: 'Capital return [event type RCAP; affects price: Yes; affects volume: No]'
    - value: RightsSame
      label: 'Rights in the same class [event type RTS; affects price: Yes; affects volume: No]'
    - value: RightsDiff
      label: 'Rights in a different class [event type RTS; affects price: Yes; affects volume: No]'
    - value: SecSwap
      label: 'Security swap [event type SCSWP; affects price: Yes; affects volume: Yes]'
    - value: Reclass
      label: 'Reclassification [event type SECRC; affects price: Yes; affects volume: Yes]'
    - value: Subdiv
      label: 'Subdivision (stock split) or combination (reverse split), incl. via stock dividend, reclassification
        or recapitalization [event type SD; affects price: Yes; affects volume: Yes]'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: EventId
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Event id, unique within an AdjustmentReason (each AdjustmentReason+EventId pair is unique).
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    customProperties:
    - 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:
      - AdjustmentReason
      - EventId
    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: 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_adj_factors_basic
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_adj_factors_basic.csv
- property: assetClass
  value: equity
- property: coverage
  value: All US exchange-listed equities (stocks, ETFs, ETNs, ADRs, preferred stock, warrants and similar),
    events from 2007 to present. Sample is AAPL only (32 events, 20120809-20200207).
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: yyyymmdd date strings
- property: priceAdjustment
  value: n/a
- property: licensedData
  value: true
- property: evidenceGrade
  value: vendor-doc
- property: knownIssues
  value:
  - Update cadence and publication latency are not stated in the guide; confirm with AlgoSeek (or GET
    /v1/meta/datasets/{id}/status).
  - 'Doc discrepancy: Guide text says the CSV rows correspond to ''individual bars'' (boilerplate copied
    from price guides); rows are corporate-event records.'
  - 'Doc discrepancy: Guide''s reason table is grouped by Event Type, but the Basic field table and sample
    header have no EventType column (it exists only in Detailed/Cumulative/Daily Cumulative datasets).'
  - 'Doc discrepancy: Guide Table 1 prints AdjustmentFactor rounded to 10 digits (0.9944456637, 0.1428571429)
    and Table 4 to 9 digits; sample delivers 15-16 significant digits (0.994445663734742, 0.142857142857143).'
  - 'Doc discrepancy: tradedate aggregation wording is ambiguous: ''one CSV file with data per symbol
    per effective date'' versus the example of all events on one date in a separate file.'
  - 'Doc discrepancy: Sample is a 32-row AAPL extract ending 20200207: it contains only CashDiv (31) and
    BonusSame (1) and omits AAPL''s 20200831 Subdiv that appears in the Cumulative dataset sample, so
    it is truncated, not a complete history.'
  - 'Doc discrepancy: Guide FAQ concedes that two dividends on the same date for one ticker cannot be
    told apart in Basic (they differ by dividend period only in the Detailed Detail column).'
contractCreatedTs: '2026-11-02T00:00:00Z'