# 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:occ-equities-special-settlements
name: AlgoSeek OCC Equities Special Settlements
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- options
- reference
- us
description:
  purpose: 'OCC records for non-standard (adjusted) US equity option roots created by corporate actions:
    for each adjusted option symbol, one row per delivery component showing what is delivered, how it
    settles, the share of strike it carries and any cash amount.'
  usage: Contract identity, lifecycle, and adjusted-deliverable handling for US-listed options.
  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. Identifies the
    adjusted root only (OptionTicker such as AAL1); there is no strike, expiration or call/put. Join to
    contract masters by root and date to get strikes and expirations. Deliverable semantics: each adjusted
    root has TotalDelivComponents rows, one per DeliveryComponents index. In all 69 roots of the sample,
    the row count equals TotalDelivComponents and StrikePercent sums to 100 across components. Cash components
    appear as UnderTicker = USD with SettlementMethod MON and StrikePercent 0 (19 sample rows, DeliverableUnits
    100); stock components use CNS. Twelve other MON rows in the sample carry a non-USD UnderTicker with
    StrikePercent 100. Effective dating: ProcessDate = file/record date; SettlementDate = date delivery
    and payment is due (blank for 52 of 100 sample rows). There are no explicit start/end-date columns
    for the adjustment itself.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/occ-equities-special-settlements/
  - type: implementation
    url: https://algoseek.com/data-docs/options-reference/algoseek.OCC.Equity.Special.Settlements.pdf
  - type: implementation
    url: https://algoseek.com/docs/rest-api/reference
context:
  instructions: Effective-dated contract reference data. Adjusted (non-standard) contracts carry a modified
    deliverable; use the OCC settlement details rather than the standard 100-share multiplier for them.
  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_OCC_EQ_SPEC_SETTL}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: Plain-text CSV with fixed header row, one file per trading day; an all-history single file
      is also offered. Compression and bucket/path not stated.
  - 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-opt-ref/occ-eq-spec-settl
  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: occ_equities_special_settlements
  physicalName: occ_eq_spec_settl
  physicalType: file
  logicalType: object
  businessName: OCC Equities Special Settlements
  description: 'OCC records for non-standard (adjusted) US equity option roots created by corporate actions:
    for each adjusted option symbol, one row per delivery component showing what is delivered, how it
    settles, the share of strike it carries and any cash amount.'
  dataGranularityDescription: one delivery component (DeliveryComponents) of one adjusted option symbol
    (OptionTicker) in a daily OCC file (ProcessDate)
  properties:
  - name: ProcessDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Date on which OCC created the record; equals the file date in the sample
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SettlementDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Date on which delivery and payment for the product is due
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: OptionTicker
    logicalType: string
    physicalType: string (csv text)
    description: Option symbol of the non-standard (adjusted) root, e.g. AAL1
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UnderTicker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol of the deliverable component; USD for cash components in the sample and guide
      Table 1
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UnderType
    logicalType: string
    physicalType: string (csv text)
    description: Type of underlying security; code list not defined in this guide (sample S only)
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: StrikeCurrency
    logicalType: string
    physicalType: string (csv text)
    description: Currency of the strike price, USD = US dollar
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: TotalDelivComponents
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Total number of delivery components for settlement of the option symbol
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: DeliveryComponents
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Index of the delivery component this row represents
    primaryKey: true
    primaryKeyPosition: 3
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SettlementMethod
    logicalType: string
    physicalType: string (csv text)
    description: How exercise and assignment are settled for this component
    required: true
    enum:
    - value: MON
      label: Cash settlement
    - value: CNS
      label: Continuous Net Settlement through a Correspondent Clearing Corporation
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: StrikePercent
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Percentage of the strike price allocated to this settlement component
    customProperties:
    - property: unit
      value: percent
    - property: nullMeaning
      value: '0'
    - property: evidence
      value: guide+sample
  - name: DeliverableUnits
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Per-contract number of deliverable units of cash, stocks, bonds or currencies
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: CashAmount
    logicalType: number
    physicalType: decimal (csv text)
    description: Per-contract cash amount allocated upon settlement
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: '0.000000'
    - 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:
      - ProcessDate
      - OptionTicker
      - DeliveryComponents
    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: '2017-11-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-opt-ref
- property: vendorDatasetTextId
  value: occ_eq_spec_settl
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/occ_eq_spec_settl.csv
- property: assetClass
  value: reference
- property: coverage
  value: Non-standard (adjusted) equity option contracts listed on US public exchanges after corporate
    events (mergers, splits, spin-offs, special dividends); data from 2017-11-01.
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: yyyymmdd dates
- 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: UnderTicker is described as ''underlying symbol name'' but in the sample and guide
    Table 1 it holds the deliverable component symbol (including USD for cash, and different tickers per
    component of one option symbol, e.g. AGEN, USD, INKT for AGEN1).'
  - 'Doc discrepancy: TotalDelivComponents and DeliveryComponents are typed integer but delivered zero-padded
    to 2 digits (01, 02).'
  - 'Doc discrepancy: ProcessDate is defined as the date OCC created the record, yet the sample file dated
    20240315 contains rows with SettlementDate 20150330, so the daily file seems to carry earlier-settled
    records rather than only newly created ones.'
  - 'Doc discrepancy: CashAmount is described as per-contract, but sample values (e.g. 6.850000 with DeliverableUnits
    100 for ACI1; 0.010200 for AGEN1) look like per-unit/per-share amounts; unit basis should be verified.'
  - 'Doc discrepancy: Guide revision table says initial release effective Feb 6, 2024 while the cover
    says Mar 2024.'
  - 'Doc discrepancy: Guide Table 1 shows a different set of tickers (AEMD1, AFMD1, AGEN1 ...) than the
    sample CSV (AAGR1, AAL1, ACB1 ...), both dated 20240315.'
  - 'Doc discrepancy: Guide columns match the 12-column sample header exactly, in the same order.'
contractCreatedTs: '2026-11-02T00:00:00Z'