# 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-opra-options-contracts-security-master
name: AlgoSeek US OPRA Options Contracts Security Master
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- options
- reference
- us
description:
  purpose: Contract-level reference record of every listed and delisted OPRA option contract. One row
    per option contract (ASID) with contract tickers, root and underlying tickers over time, call/put,
    strike, expiration, trade-date ranges and, for non-standard (adjusted) contracts, deliverable components
    and settlement terms.
  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. Contract identity:
    ASID is the persistent key. ContractTickers holds OSI-style tickers (root + yymmdd + C/P + strike
    x 1000 in 8 digits, e.g. AAPL251219C00270000, SPXW261218C04640000; root not space-padded in samples).
    Strike column is the decimal strike in USD per share. To map bar/OI/analytics rows (Ticker, CallPut,
    Strike, expiration) to ASID, build the OSI-style ticker or match root + type + strike + expiry within
    ContractTradeDates. Effective dating: ContractTradeDates lists a ''start:end'' period for each root-ticker
    period of the contract; end 29991231 means still active. OptionRootTickers, ContractTickers and ContractTradeDates
    are aligned by '';''. StartTradeDate is the contract''s first trade date. NonStandardTradeDates lists
    the periods when the contract traded under a non-standard (adjusted) root. Adjustment / deliverable
    semantics: for non-standard options (IsStandard = N) the delivery columns describe the adjusted deliverable,
    one '';''-separated group per non-standard root period and one space-separated entry per component.
    Guide Table 1 example: BABA contract with root BABA2 has TotalDelivComponents 2, DeliveryComponents
    ''BABA USD'', SettlementMethod ''CNS MON'', StrikePercent ''100 0'', DeliverableUnits ''100 100'',
    CashAmount ''0.000000 0.950000''. Available only from 2018.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-opra-options-contracts-security-master/
  - type: implementation
    url: https://algoseek.com/data-docs/options-reference/algoseek.US.OPRA.Options.Contracts.Security.Master.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_OPT_CONTR_SEC_MASTER}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: 'Two aggregation options with identical fields: per-year CSV files opt_contr_sec_master_yyyy.csv.gz
      (yyyy from 2007 to present) or one file opt_contr_sec_master.csv.gz for all years. Gzip-compressed
      (uncompressed about 10x larger). One row per option contract.'
  - 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/contr-sec-master
  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_opra_options_contracts_security_master
  physicalName: opt_contr_sec_master
  physicalType: file
  logicalType: object
  businessName: US OPRA Options Contracts Security Master
  description: Contract-level reference record of every listed and delisted OPRA option contract. One
    row per option contract (ASID) with contract tickers, root and underlying tickers over time, call/put,
    strike, expiration, trade-date ranges and, for non-standard (adjusted) contracts, deliverable components
    and settlement terms.
  dataGranularityDescription: one option contract (ASID), i.e. one underlying x call/put x strike x expiration,
    tracked across root/underlying ticker changes
  properties:
  - name: ASID
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek unique option contract identifier; unchanged through the life of the contract
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: ContractTickers
    logicalType: string
    logicalTypeOptions:
      format: 'OSI-style ticker: root + yymmdd + C/P + 8-digit strike x 1000; '';'' separates successive
        tickers'
    physicalType: string (csv text)
    description: All option contract tickers used for the contract; several when the root ticker changed
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: ContractTradeDates
    logicalType: string
    logicalTypeOptions:
      format: start:end periods separated by ';', end 29991231 = active
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start and end date of each root-ticker period for this contract
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: StartTradeDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: First trade date of the option contract
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: ExpirationDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Expiration date of the option contract (guide table names this column Expiration)
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Type
    logicalType: string
    physicalType: string (csv text)
    description: Option type, C = Call or P = Put
    required: true
    enum:
    - value: C
      label: Call
    - value: P
      label: Put
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Strike
    logicalType: number
    physicalType: decimal (csv text)
    description: Fixed price at which the contract can be exercised, per share of underlying
    required: true
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OptionRootTickers
    logicalType: string
    logicalTypeOptions:
      format: ''';''-separated list'
    physicalType: string (ticker1;ticker2;...) (csv text)
    description: Option root tickers used by the contract, in order; multiple when the root changed (e.g.
      BABA;BABA2)
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UnderASID
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek unique security identifier of the underlying equity
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: UnderTickers
    logicalType: string
    logicalTypeOptions:
      format: ''';''-separated list'
    physicalType: string (ticker1;ticker2;...) (csv text)
    description: Underlying tickers used, multiple when the underlying ticker changed
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: UnderTradeDates
    logicalType: string
    logicalTypeOptions:
      format: start:end periods separated by ';', end 29991231 = active
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start and end dates for each underlying ticker
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: TotalDelivComponents
    logicalType: string
    logicalTypeOptions:
      format: ''';''-separated list per non-standard root period'
    physicalType: string (integer1;integer2;...) (csv text)
    description: Total delivery components for the non-standard root; non-standard options from 2018 only
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: DeliveryComponents
    logicalType: string
    logicalTypeOptions:
      format: space-separated components, ';' between root periods
    physicalType: string (ticker1 USD;ticker2 USD;...) (csv text)
    description: Components of delivery for the non-standard root; USD = US dollar cash; non-standard
      options from 2018 only
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: SettlementMethod
    logicalType: string
    logicalTypeOptions:
      format: space-separated within a period, ';' between periods
    physicalType: string (settl1 settl2;settl1 settl2;...) (csv text)
    description: 'How exercise/assignment is settled per component: MON = cash, CNS = continuous net settlement'
    enum:
    - value: MON
      label: Cash settlement
    - value: CNS
      label: Continuous Net Settlement through a Correspondent Clearing Corporation
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: StrikePercent
    logicalType: string
    logicalTypeOptions:
      format: space-separated within a period, ';' between periods
    physicalType: string (perc1 perc2;perc3 perc4;...) (csv text)
    description: Percentage of the strike allocated to each settlement component
    customProperties:
    - property: unit
      value: percent
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: DeliverableUnits
    logicalType: string
    logicalTypeOptions:
      format: space-separated within a period, ';' between periods
    physicalType: string (unit1 unit2;unit3 unit4;...) (csv text)
    description: Per-contract deliverable units of cash, stocks, bonds or currencies for each component
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: CashAmount
    logicalType: string
    logicalTypeOptions:
      format: space-separated decimals (6 places), ';' between periods
    physicalType: string (cash1 cash2;cash3 cash4;...) (csv text)
    description: Per-contract cash amount allocated upon settlement for each component
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: IsStandard
    logicalType: string
    physicalType: string (csv text)
    description: Whether the contract is standard
    required: true
    enum:
    - value: Y
      label: Standard option
    - value: N
      label: Non-standard (adjusted) option
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: NonStandardTradeDates
    logicalType: string
    logicalTypeOptions:
      format: start:end periods separated by ';'
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start and end dates for each non-standard option root ticker period
    customProperties:
    - property: nullMeaning
      value: Blank
    - 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:
      - ASID
    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-opt-ref
- property: vendorDatasetTextId
  value: opt_contr_sec_master
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.us-east-1.amazonaws.com/sample_data/cloud_storage/opt_contr_sec_master_years.csv
- property: assetClass
  value: reference
- property: coverage
  value: 'All listed and delisted OPRA options on stocks, ETFs, ETNs, indexes etc. Guide: contains data
    from 2010 to present, historical coverage back to 2007, quality not guaranteed before OSI (2010-05-17);
    deliverable/settlement details only for non-standard options from 2018. Page says 2015 to present.'
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: Dates yyyymmdd; date ranges 'yyyymmdd:yyyymmdd' joined by ';'
- property: priceAdjustment
  value: n/a
- property: licensedData
  value: true
- property: evidenceGrade
  value: vendor-doc
- property: knownIssues
  value:
  - 'Doc discrepancy: History start: page says 2015 to present; guide says data from 2010 to present,
    covers history back to 2007, and files by year start in 2007. Quality is not guaranteed before OSI
    (2010-05-17).'
  - 'Doc discrepancy: Guide Table 1/2 name the column ''Expiration''; the published sample header uses
    ''ExpirationDate''.'
  - 'Doc discrepancy: ASID doc type is integer here but string in the options (root) Security Master guide.'
  - 'Doc discrepancy: TotalDelivComponents, DeliveryComponents, SettlementMethod, StrikePercent, DeliverableUnits
    and CashAmount are typed as semicolon/space-delimited strings, not numeric columns; guide Table 2
    has ''tricker'' typos and column names wrap across lines.'
  - 'Doc discrepancy: Sample is a per-year file for ticker PLCE only (100 standard contracts); all delivery/settlement
    columns and NonStandardTradeDates are blank there, so the multi-valued formats come only from guide
    Table 1 (BABA example).'
  - 'Doc discrepancy: Sample ContractTradeDates starts 20250102 for 84 of 100 contracts whose StartTradeDate
    is earlier (e.g. 20230911), and UnderTradeDates is 20250102:20251231 for every row while active contracts
    end 29991231; the ranges in year files appear clipped to the file year, which the guide does not state.'
  - 'Doc discrepancy: Guide intro says dataset ''contains'' options from 2010 but also ''covers historical
    data back to 2007''.'
  - 'Doc discrepancy: Guide columns match the 19-column sample header exactly, in the same order (apart
    from Expiration naming).'
contractCreatedTs: '2026-11-02T00:00:00Z'