# 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-cumulative-adjustment-factors
name: AlgoSeek US Equities Cumulative Adjustment Factors
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
description:
  purpose: Event-dated table of forward and backward cumulative price and volume adjustment factors per
    SecId, with the adjustment reason and event type of each corporate action, so raw prices and volumes
    can be converted to adjusted series in one multiplication/division. Rows exist only on event effective
    dates plus an initial START row.
  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. Backward factors
    (guide Table 5 and steps): for a trade date D, find the first row whose EffectiveDate is later than
    D; use that row''s CumulativeFactorPriceBackward to MULTIPLY prices and CumulativeFactorVolumeBackward
    to DIVIDE volumes. Each row''s factor therefore covers dates from the previous row''s EffectiveDate
    up to the day before its own EffectiveDate; dates on or after the last EffectiveDate use AF=1. Worked
    example in guide: all prices from 20141106 on x1; 20141105-20140807 x0.910220291174414; 20140806-20140609
    x0.905715199168812; 20140608-20140508 x0.129387885595545; and volumes before 20140609 divided by 0.142857142857143,
    volumes from 20140609 divided by 1. Derived (matches Table 5 and the sample): backward factor of a
    row = AdjustmentFactor of that row''s event times the backward factor of the next row = product of
    event factors from this event forward to the latest event, own event included. Volume factors multiply
    only volume-affecting events, so CashDiv rows leave them unchanged (1, 0.25 or 0.0357 in the sample).
    Forward factors (inferred from sample): CumulativeFactor*Forward at a row = running product of event
    factors from the first event up to and including this row (e.g. 20121107 forward price 0.991197650405165
    = 0.99572484109315 x 0.995453371753772; forward volume becomes 0.142857142857143 from the 20140609
    BonusSame). Apparent coverage: from this EffectiveDate until the next event. Direction of application
    is not stated in the guide.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-cumulative-adjustment-factors/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.Adjustment.Factors.Cumulative.pdf
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_CUMUL}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: 'Plain-text CSV files with fixed header and one row per corporate-event effective date (plus
      a START row) per SecId. Two aggregation options with identical fields: tradedate (one file per effective
      date covering all symbols) and SecId (one file per SecId per year, or one file with all history
      from 2007). S3 buckets: us-equity-cumulative-adjustment-secid-all, us-equity-cumulative-adjustment-secid-yyyy,
      us-equity-cumulative-adjustment-tradedate-yyyy (yyyy = year); SecId files at NN/NNNNN.csv (NN =
      first two digits of the SecId); daily-changes/yyyymmdd.csv lists files updated on a date.'
  - property: compression
    value: gzip
  - property: header
    value: true
  - property: entitlement
    value: Bucket access is granted per subscription; bucket names arrive with license provisioning.
schema:
- name: us_equities_cumulative_adjustment_factors
  physicalName: eq_adj_factors_cumul
  physicalType: file
  logicalType: object
  businessName: US Equities Cumulative Adjustment Factors
  description: Event-dated table of forward and backward cumulative price and volume adjustment factors
    per SecId, with the adjustment reason and event type of each corporate action, so raw prices and volumes
    can be converted to adjusted series in one multiplication/division. Rows exist only on event effective
    dates plus an initial START row.
  dataGranularityDescription: one SecId x corporate-event effective date (plus one START row per SecId);
    several rows may share a date
  properties:
  - name: SecId
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek unique security identifier.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: Ticker on the EffectiveDate.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: EffectiveDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (YYYYMMDD) (csv text)
    description: Date a corporate event becomes effective; for the START row, the date the SecId begins
      in algoseek's records.
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: CumulativeFactorPriceBackward
    logicalType: number
    physicalType: decimal (csv text)
    description: 'Backward cumulative price factor: product of event factors from this row''s event to
      the latest; multiply prices dated before EffectiveDate by it.'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: CumulativeFactorPriceForward
    logicalType: number
    physicalType: decimal (csv text)
    description: 'Forward cumulative price factor: running product of event factors up to and including
      this event (inferred from sample); covers events since 2007 only.'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: CumulativeFactorVolumeBackward
    logicalType: number
    physicalType: decimal (csv text)
    description: Backward cumulative volume factor built only from volume-affecting events; divide volumes
      dated before EffectiveDate by it.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: CumulativeFactorVolumeForward
    logicalType: number
    physicalType: decimal (csv text)
    description: 'Forward cumulative volume factor: running product of volume-affecting event factors
      up to and including this event (inferred).'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: AdjustmentReason
    logicalType: string
    physicalType: string (csv text)
    description: Reason for the corporate event (18 codes) or START for the initial row.
    primaryKey: true
    primaryKeyPosition: 3
    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]'
    - value: START
      label: Initial row for a SecId (EventType also START); all factors equal 1; EffectiveDate/TradeDate
        is the SecId's first date in algoseek records
    customProperties:
    - property: evidence
      value: guide+sample
  - name: EventType
    logicalType: string
    physicalType: string (csv text)
    description: Event type for the reason (e.g. DIV, BON, SD) or START for the initial row.
    enum:
    - value: BON
      label: Bonus issue (reasons BonusSame, BonusDiff)
    - value: CAPRD
      label: Capital reduction (CapReduct)
    - value: CONSD
      label: Consolidation (Cons)
    - value: DIST
      label: Distribution (Distrib)
    - value: DIV
      label: Dividend (CashDiv, ScriptDiv, ScriptDivDiff); the guide glosses DIV=Dividend
    - value: LIQ
      label: Liquidation, partial (ParLiq)
    - value: DMRGR
      label: De-merger (DeMerg)
    - value: ENT
      label: Entitlement (EntSame, EntDiff)
    - value: RCAP
      label: Capital return (CapRet)
    - value: RTS
      label: Rights (RightsSame, RightsDiff)
    - value: SCSWP
      label: Security swap (SecSwap)
    - value: SECRC
      label: Reclassification (Reclass)
    - value: SD
      label: Subdivision / combination (Subdiv)
    - value: START
      label: Initial row for a SecId (AdjustmentReason also START)
    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:
      - SecId
      - EffectiveDate
      - AdjustmentReason
    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_adj_factors_cumul
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_adj_factors_cumul.csv
- property: assetClass
  value: equity
- property: coverage
  value: All US exchange-listed equities, adjustment history from 2007 to present; forward factors ignore
    events before 2007. Sample is AAPL only (36 rows, 20070103-20200831).
- 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:
  - Primary key is inferred; AlgoSeek's guide does not name one.
  - 'Doc discrepancy: Guide Table 1 shows CumulativeFactorPriceBackward 0.128669221770296 for the 20140609
    row, identical to the 20140508 value; Table 5 gives 0.129387885595545 for the same row (= 0.142857143
    x 0.905715199, the 20140807 row), so Table 1''s third column is a copy error.'
  - 'Doc discrepancy: Guide worked example calls 20141106 the last corporate event and gives its backward
    price factor as 0.910220291174414, but that event''s own factor is 0.9957 (Basic sample), so the value
    must include later events; Table 5 is a truncated 2012-2014 view of a later snapshot (inferred).'
  - 'Doc discrepancy: Guide Table 5 volume-backward is 0.142857 for 2012-2014 rows; the published sample
    shows 0.0357142857142858 (=1/28) for the same rows because the 20200831 Subdiv (4-for-1, backward
    volume 0.25) was added later - an observed case of retroactive restatement.'
  - 'Doc discrepancy: Guide Table 1 forward price 0.961154487257303 (20140206) differs from the sample''s
    0.961154487257304 in the last digit (rebuild rounding).'
  - 'Doc discrepancy: START-row date: guide Table 3 note says EffectiveDate shows ''the date when the
    security was listed'' while the FAQ says ''when the SecId was assigned''; sample START for AAPL is
    20070103 (start of algoseek coverage), not its 1980 listing (ListDate 19801212 in the Shares Outstanding
    sample).'
  - 'Doc discrepancy: Guide says data files hold ''rows corresponding to individual daily bars'' (boilerplate);
    rows are event dates, not daily bars.'
  - 'Doc discrepancy: Guide never states how to apply the forward factors (multiply or divide) and gives
    no forward worked example; forward semantics here are inferred from sample numbers.'
  - 'Doc discrepancy: Sample is a 36-row AAPL extract; it covers reasons START, CashDiv, BonusSame and
    Subdiv only, and ends at the 20200831 Subdiv (backward price factor exactly 0.25) so later AAPL dividends
    are absent from the extract.'
contractCreatedTs: '2026-11-02T00:00:00Z'