# 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-options-security-master
name: AlgoSeek US Options Security Master
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- options
- reference
- us
description:
  purpose: Root-level reference catalogue of listed and delisted OPRA option roots. One row per option
    root security (ASID) with underlying, option and settlement type, exercise style, weekly flag, close
    time, listing status, trade-date ranges and whether analytics exist. It defines the root, not individual
    strikes or expirations.
  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 only:
    no strike, expiration or call/put. A bar/OI/analytics row is tied to a root via its Ticker (assumed
    to equal OptionTicker; the guide does not say so) and a trade date inside OptionTradeDates. Effective
    dating: OptionTradeDates holds one or more ''start:end'' periods separated by '';'' (example 20120103:20130318;20130415:29991231);
    end 29991231 means still active/no end date. A new range is created when the gap between consecutive
    dates exceeds 7 days. Because tickers are reused (guide example: S for Sprint Nextel, Sprint, then
    SentinelOne), resolving ticker -> ASID needs a trade date via the lookup file opt_ticker_to_asid.csv
    (columns ASID, OptionTicker, UnderTicker, UnderSecId, OptionTradeDates). ASID assignment: test tickers
    keep one ASID for all history. Non-standard (adjusted) tickers get a new ASID if the underlying ticker
    changes, the underlying SecId changes, or there is no underlying SecId / it stopped trading, for each
    new date range. Standard tickers get a new ASID if the underlying ticker or SecId changes or two date
    ranges are 30 or more days apart.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-options-security-master/
  - type: implementation
    url: https://algoseek.com/data-docs/options-reference/algoseek.US.Options.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_SEC_MASTER}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: Single flat CSV (guide names it eq_opt_sec_master.csv; published sample is opt_sec_master.csv)
      delivered as one consolidated file, one row per option root ASID. Companion lookup file opt_ticker_to_asid.csv
      maps ASID <-> option ticker, underlying ticker, underlying SecId and trade dates. Compression 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/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_options_security_master
  physicalName: opt_sec_master
  physicalType: file
  logicalType: object
  businessName: US Options Security Master
  description: Root-level reference catalogue of listed and delisted OPRA option roots. One row per option
    root security (ASID) with underlying, option and settlement type, exercise style, weekly flag, close
    time, listing status, trade-date ranges and whether analytics exist. It defines the root, not individual
    strikes or expirations.
  dataGranularityDescription: one option root ticker security (ASID); a ticker reused by another company
    or after a long gap gets a separate ASID row
  properties:
  - name: ASID
    logicalType: string
    logicalTypeOptions:
      format: 16-digit identifier, e.g. 1110000000001005
    physicalType: string (csv text)
    description: algoseek unique option root security identifier
    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 (e.g. AAPL, SPXW); the same ticker can map to different ASIDs over
      time
    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
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: UnderType
    logicalType: string
    physicalType: string (csv text)
    description: Type of underlying
    enum:
    - value: S
      label: Option on stock
    - value: I
      label: Option on index
    - value: F
      label: Option on forex (currency)
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: OptionType
    logicalType: string
    physicalType: string (csv text)
    description: Option type
    enum:
    - value: BI
      label: Binary option
    - value: VA
      label: Vanilla option
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: OptionStyle
    logicalType: string
    physicalType: string (csv text)
    description: Exercise style
    enum:
    - value: A
      label: American
    - value: E
      label: European
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: IsWeekly
    logicalType: string
    physicalType: string (csv text)
    description: Whether the root covers only weekly options
    enum:
    - value: Y
      label: 'Yes'
    - value: N
      label: 'No'
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: MarketClose
    logicalType: time
    logicalTypeOptions:
      format: HH:MM
    physicalType: String (HH:MM) (csv text)
    description: Market close time for this root symbol (16:00 or 16:15 in guide/sample)
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: SettlType
    logicalType: string
    physicalType: string (csv text)
    description: Settlement type of the option
    enum:
    - value: PM
      label: Option expires at the close of the market
    - value: AM
      label: Option expires on the morning of the last trading day
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: SettlTicker
    logicalType: string
    physicalType: string (csv text)
    description: Ticker providing the price used for the exercise-settlement amount (e.g. SPX for SPXW)
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: OptionTradeDates
    logicalType: string
    logicalTypeOptions:
      format: start:end periods separated by ';', end 29991231 = still active
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Date range(s) during which this option root ASID traded
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OptionListStatus
    logicalType: string
    physicalType: string (csv text)
    description: Current list status of the root
    required: true
    enum:
    - value: D
      label: Delisted
    - value: L
      label: Listed
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UnderSecId
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek unique equity security identifier (SecId) of the underlying
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: UnderTradeDates
    logicalType: string
    logicalTypeOptions:
      format: start:end, end 29991231 = still active
    physicalType: string (yyyymmdd:yyyymmdd) (csv text)
    description: Start and end dates of the underlying SecId
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: GreeksCoverage
    logicalType: string
    physicalType: string (csv text)
    description: Whether algoseek provides analytics (Daily Analytics) for this root
    enum:
    - value: Y
      label: 'Yes'
    - value: N
      label: 'No'
    customProperties:
    - property: nullMeaning
      value: Never
    - 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: '2012-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_sec_master
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/opt_sec_master.csv
- property: assetClass
  value: reference
- property: coverage
  value: All listed and delisted OPRA options on stocks, ETFs, ETNs, indexes and currencies (UnderType
    S, I, F). Guide says 2012 to present; product page says 2015 to present; sample OptionTradeDates start
    20120103.
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: Dates yyyymmdd; MarketClose HH:MM; date ranges 'yyyymmdd:yyyymmdd' joined by ';'
- property: sessionHours
  value: 'MarketClose column per root: 16:00 for ordinary roots, 16:15 for roots such as SPXW (guide Table
    1)'
- 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 2012 to present, and sample
    OptionTradeDates begin 20120103.'
  - 'Doc discrepancy: Page says the ASID stays stable throughout the lifecycle of an option root; guide
    intro says it ''remains unchanged during specific contract expiration'' (wording copied from contract
    master) and Appendix A shows ASIDs change when the underlying ticker/SecId changes or after gaps.'
  - 'Doc discrepancy: Guide names the file eq_opt_sec_master.csv; the published sample is opt_sec_master.csv.'
  - 'Doc discrepancy: Guide text says ''Table 4 below'' before the settlement-type table, which is numbered
    Table 5.'
  - 'Doc discrepancy: Guide UnderTradeDates doc type shows a single ''yyyymmdd:yyyymmdd'' range while
    OptionTradeDates allows '';''-separated multiple ranges.'
  - 'Doc discrepancy: Sample has two rows (ABAT, ABKFQ, both delisted) with blank UnderTicker, UnderType,
    OptionType, OptionStyle, IsWeekly, MarketClose, SettlType, UnderSecId, UnderTradeDates and GreeksCoverage
    = N; all 98 other rows are stock/vanilla/American/16:00/PM. Sample SettlTicker is blank in all 100
    rows.'
  - 'Doc discrepancy: ASID doc type is string here but integer in the OPRA Contracts Security Master guide.'
  - 'Doc discrepancy: Guide columns match the 15-column sample header exactly, in the same order.'
contractCreatedTs: '2026-11-02T00:00:00Z'