# 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-detailed-adjustment-factors
name: AlgoSeek US Equities Detailed Adjustment Factors
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
description:
  purpose: 'Event-level, fully attributed list of corporate actions affecting US equity price and volume
    history: the multiplicative adjustment factor and reason plus security name, report date, event type,
    event id, free-text event detail and ISIN. Supports audit and reconstruction of adjusted series.'
  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-detailed-adjustment-factors/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.Adjustment.Factors.Detailed.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_DETAIL}/
  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-detail
  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_detailed_adjustment_factors
  physicalName: eq_adj_factors_detail
  physicalType: file
  logicalType: object
  businessName: US Equities Detailed Adjustment Factors
  description: 'Event-level, fully attributed list of corporate actions affecting US equity price and
    volume history: the multiplicative adjustment factor and reason plus security name, report date, event
    type, event id, free-text event detail and ISIN. Supports audit and reconstruction of adjusted series.'
  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: Name
    logicalType: string
    physicalType: string (csv text)
    description: Name of the company (security).
    customProperties:
    - property: evidence
      value: guide+sample
  - name: ReportDate
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd with optional _N version suffix, e.g. 20180511_03
    physicalType: string (YYYYMMDD[_N]) (csv text)
    description: Date and version (_N suffix) of the algoseek event report file that carried the event;
      can be later than EffectiveDate.
    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: EventType
    logicalType: string
    logicalTypeOptions:
      format: short upper-case code
    physicalType: string (csv text)
    description: Event type grouping the reason (e.g. DIV for CashDiv, BON for BonusSame, SD for Subdiv).
    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)
    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
  - name: Detail
    logicalType: string
    logicalTypeOptions:
      format: free text with [KEY=value] tokens; e.g. 'INT Dividend (cash) of USD0.470000000/EQS [DIVPAYRATE=0.470000000]
        [DIVCURRENCY=USD] [DIVPERIOD=INT] [OPTION=1] [EXCHGCD=USNASD]'
    physicalType: string (csv text)
    description: 'Human-readable event description: dividend amount, period, currency, bonus/split/demerger
      terms and exchange code.'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: ISIN
    logicalType: string
    logicalTypeOptions:
      format: 12-char ISIN
    physicalType: string (csv text)
    description: ISIN of the security.
    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_detail
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_adj_factors_detail.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 (ReportDate may add _N version suffix)
- 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 rows correspond to ''individual bars'' (boilerplate from price guides);
    rows are corporate-event records.'
  - 'Doc discrepancy: In the Detailed guide the Adjustment Reason table (Table 3) is garbled by plain
    text extraction (price/volume columns interleaved); reading it with table-aware extraction gives exactly
    the same 18 reasons and Yes/No flags as the Basic guide.'
  - 'Doc discrepancy: Guide Table 1 prints ReportDate = EffectiveDate for the 2014 events shown; in the
    sample ReportDate is later than EffectiveDate for the first three rows (20130208 for events effective
    20120809, 20121107 and 20130207) and carries _02/_03/_04 suffixes from 20180511 onward.'
  - 'Doc discrepancy: Guide''s Detail example for a split says ''Subdivision of 2 for 1'' means holders
    receive two ADDITIONAL shares per share held, which reads as a 3-for-1; the standard reading of 2-for-1
    is one additional share. The sample''s ''Bonus of 6 ... for 1'' has factor 1/7 (six additional shares).
    Do not derive factors from Detail text; use AdjustmentFactor.'
  - 'Doc discrepancy: Guide''s Detail example for a demerger ends with '',US03965L1008'' after the bracket
    tokens, a trailing ISIN that the sample rows (dividends and one bonus) do not show.'
  - 'Doc discrepancy: Sample is a 32-row AAPL extract ending 20200207 (CashDiv 31, BonusSame 1) and omits
    the 20200831 Subdiv shown in the Cumulative sample, so it is truncated.'
  - '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.'
contractCreatedTs: '2026-11-02T00:00:00Z'