# 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-listed-options-daily
name: AlgoSeek OCC Listed Options Daily
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- options
- reference
- us
description:
  purpose: 'Daily snapshot of every option root listed on US public exchanges according to the OCC Directory
    of Listed Products: option symbol, underlying symbol and type, name, listing exchanges and position
    limit. Used to track which option roots exist on each day.'
  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. Root-level directory,
    not contract-level: no strike, expiration or call/put. OptionTicker is the OCC option symbol (root);
    UnderTicker can differ for adjusted roots (e.g. AAL1 -> AALPH, ACGN1 -> ACGN in the sample). Daily
    snapshot: a root''s presence on a TradeDate means it was listed in that day''s OCC directory; effective
    dating is by file date, not by explicit start/end columns. Use the Options Security Master for ASID
    and trade-date ranges. Adjusted (non-standard) roots appear with a numeric suffix and a descriptive
    Name such as ''(merger)'', ''(Cash Dist)'' or ''(1:20 Rev Split)'' in the sample; the guide does not
    document these naming conventions. PositionLimit: all zeros means not available (guide: not available
    for most non-equity options, e.g. index DJX). Sample values look like contract limits with three implied
    decimals (000025000000 for a 25,000-contract limit) - an inference, not stated in the guide.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/occ-listed-options-daily/
  - type: implementation
    url: https://algoseek.com/data-docs/options-reference/algoseek.OCC.Daily.Listed.Options.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_LIST_OPT_DAILY}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: Plain-text CSV with fixed header row, one file per trading day named yyyymmdd.csv (e.g. 20240104.csv);
      one row per option root ticker. 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-list-opt-daily
  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_listed_options_daily
  physicalName: occ_list_opt_daily
  physicalType: file
  logicalType: object
  businessName: OCC Listed Options Daily
  description: 'Daily snapshot of every option root listed on US public exchanges according to the OCC
    Directory of Listed Products: option symbol, underlying symbol and type, name, listing exchanges and
    position limit. Used to track which option roots exist on each day.'
  dataGranularityDescription: one option root ticker per trading day (TradeDate)
  properties:
  - name: TradeDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Trading date of the daily OCC directory snapshot
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OptionTicker
    logicalType: string
    physicalType: string (csv text)
    description: Option root ticker; adjusted roots carry a numeric suffix (e.g. AAL1) in the sample
    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: Ticker of the underlying security
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UnderType
    logicalType: string
    physicalType: string (csv text)
    description: Type of underlying security
    required: true
    enum:
    - value: S
      label: Equity
    - value: I
      label: Index
    - value: F
      label: Currency
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Name
    logicalType: string
    physicalType: string (csv text)
    description: Security name from the OCC directory; adjusted roots can carry a note such as '(merger)'
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Exchange
    logicalType: string
    logicalTypeOptions:
      format: ''';''-separated exchange codes, e.g. AM;BO;CB;ME'
    physicalType: string (csv text)
    description: Exchanges listing the option root, as codes joined by ';'
    enum:
    - value: AM
      label: AMEX
    - value: AR
      label: ARCA
    - value: BA
      label: BATS
    - value: BY
      label: BATS_Y
    - value: BO
      label: BOSTON
    - value: C2
      label: C2
    - value: CB
      label: CBOE
    - value: CS
      label: CSE
    - value: EA
      label: EDGA
    - value: EX
      label: EDGX
    - value: FI
      label: FINRA
    - value: IE
      label: IEX OPTIONS
    - value: IS
      label: ISE
    - value: IG
      label: ISE_GEMINI
    - value: IM
      label: ISE_MERCURY
    - value: LT
      label: LTSE
    - value: MI
      label: MIAX
    - value: MP
      label: MIAX_PEARL
    - value: ME
      label: MIAX_EMERALD
    - value: MS
      label: MIAX_SAPPHIRE
    - value: MX
      label: MEMX
    - value: M2
      label: MX2 OPTIONS
    - value: NA
      label: NASDAQ
    - value: NB
      label: NASDAQ_BX
    - value: NP
      label: NASDAQ_PSX
    - value: NS
      label: NSE
    - value: NY
      label: NYSE
    - value: OP
      label: OPRA
    - value: SI
      label: SIAC
    - value: TH
      label: THOMSON
    - value: UN
      label: UNKNOWN
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: PositionLimit
    logicalType: string
    logicalTypeOptions:
      format: 12-digit zero-padded string, e.g. 000025000000
    physicalType: string (csv text)
    description: OCC position limit; all zeros when not available (most non-equity options); scale not
      stated
    customProperties:
    - property: nullMeaning
      value: '000000000000'
    - 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:
      - TradeDate
      - OptionTicker
    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: '2023-07-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_list_opt_daily
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/occ_list_opt_daily.csv
- property: assetClass
  value: reference
- property: venues
  value:
  - AM (AMEX)
  - AR (ARCA)
  - BA (BATS)
  - BY (BATS_Y)
  - BO (BOSTON)
  - C2 (C2)
  - CB (CBOE)
  - CS (CSE)
  - EA (EDGA)
  - EX (EDGX)
  - FI (FINRA)
  - IE (IEX OPTIONS)
  - IS (ISE)
  - IG (ISE_GEMINI)
  - IM (ISE_MERCURY)
  - LT (LTSE)
  - MI (MIAX)
  - MP (MIAX_PEARL)
  - ME (MIAX_EMERALD)
  - MS (MIAX_SAPPHIRE)
  - MX (MEMX)
  - M2 (MX2 OPTIONS)
  - NA (NASDAQ)
  - NB (NASDAQ_BX)
  - NP (NASDAQ_PSX)
  - NS (NSE)
  - NY (NYSE)
  - OP (OPRA)
  - SI (SIAC)
  - TH (THOMSON)
  - UN (UNKNOWN)
- property: coverage
  value: All equity, index and currency options listed on US public exchanges per the OCC Directory of
    Listed Products; daily files from July 2023.
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: TradeDate yyyymmdd
- 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 sample is dated 20230615 (AADI, XDB, DJX) while the published sample
    CSV is 20230712 (A, AA, AAC ...).'
  - 'Doc discrepancy: Product page says daily data starts July 2023; the guide gives no start date.'
  - 'Doc discrepancy: Guide Table 2 gives no format for PositionLimit beyond the 12-zero default; sample
    values are 12-digit zero-padded strings (e.g. 000025000000, 000007500000, 000036325000), scale/units
    not stated.'
  - 'Doc discrepancy: Exchange codes in the sample (AM, BO, CB, ME, EX, IG, IS, IM, MI, AR, NA, MP, NB,
    C2, NP, BA) are a subset of the 31 codes in Table 3.'
  - 'Doc discrepancy: Guide columns match the 7-column sample header exactly, in the same order.'
contractCreatedTs: '2026-11-02T00:00:00Z'