# 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-otc-security-master
name: AlgoSeek US Equities OTC Security Master
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
description:
  purpose: One row per algoseek ASID holding the complete history of each OTC security attribute (symbol,
    names, class, type, status, ISIN, FIGI, share-class FIGI, LEI, OTC SecIds/CompIds) as semicolon-separated
    values paired with date-range columns. Used to track symbol/name changes and cross-reference OTC securities.
  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. Shape: this
    is a ''history in one row'' table. Each attribute X is a list column paired with XDateRange; the i-th
    element of X applies to the i-th StartDate:EndDate of XDateRange. Parse by splitting on '';'' and
    then the range on '':''; keep empty elements (they are meaningful ''no value'' periods). Attributes
    have independent period boundaries, so do not zip lists of different attributes together. Point-in-time
    lookup: for date D, take the element whose StartDate <= D <= EndDate. End dates are inclusive per
    the guide example. 29991231 is a sentinel for open-ended, not a real date; when a value changes the
    sentinel is replaced by the real end date, so the same ASID row mutates over time (no row-level version
    columns). Identifiers: ASID is algoseek''s stable key (sample values are 16-digit, prefix 121; listed-equity
    ASIDs in other datasets start 101). OTCSecId/OTCCompId are OTC Markets Group IDs and one ASID can
    hold several OTCSecIds (reverse splits, name changes; 11 of 100 sample rows). The OTC Market Compliance
    dataset''s SecId and CompId are these OTC Markets IDs; join to this table via OTCSecId/OTCCompId element
    ranges, not to ASID directly. Cross-reference identifiers: ISIN comes from algoseek internal lookups
    on the OTC ticker; FIGI (composite) and ShareClassFIGI come from the OpenFIGI API; LEI is mapped from
    ISIN using GLEIF files, so a security without an ISIN has no LEI. These identifier fields refresh
    only in the PM update.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-otc-security-master/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.OTC.Security.Master.pdf
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_OTC_SEC_MASTER}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: Single gzip-compressed CSV, file name eq_otc_sec_master.csv.gz; fixed header in the first row;
      records sorted by ASID.
  - property: compression
    value: gzip
  - property: header
    value: true
  - property: entitlement
    value: Bucket access is granted per subscription; bucket names arrive with license provisioning.
schema:
- name: us_equities_otc_security_master
  physicalName: eq_otc_sec_master
  physicalType: file
  logicalType: object
  businessName: US Equities OTC Security Master
  description: One row per algoseek ASID holding the complete history of each OTC security attribute (symbol,
    names, class, type, status, ISIN, FIGI, share-class FIGI, LEI, OTC SecIds/CompIds) as semicolon-separated
    values paired with date-range columns. Used to track symbol/name changes and cross-reference OTC securities.
  dataGranularityDescription: one security (ASID) with all historical values of every attribute in delimited
    lists
  properties:
  - name: ASID
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek unique security identifier, retained across symbol changes, name changes and
      corporate actions; one row per ASID.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OTCSecId
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (secid1;secid2;... ) (csv text)
    description: OTC Markets Group SecIds related to the security structure; several when SecId changed
      through corporate actions such as reverse splits.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OTCSecIdDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of OTCSecId; end date 29991231 means the value is still
      in use.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OTCCompId
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (compid1;compid2;... ) (csv text)
    description: OTC Markets Group company identifiers related to the issuer; may list several.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OTCCompIdDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of OTCCompId; end date 29991231 means the value is still
      in use.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (ticker1;ticker2;...) (csv text)
    description: All symbols the security has used, oldest first; repeats allowed when a symbol is reused
      (e.g. WNFT;WNFTD;WNFT).
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: TickerDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of Ticker; end date 29991231 means the value is still
      in use.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SecurityName
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (name1;name2;...) (csv text)
    description: Security names over time (OTC Markets short-form upper-case names in sample).
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SecurityNameDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of SecurityName; end date 29991231 means the value is
      still in use.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: CompanyName
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (name1;name2;...) (csv text)
    description: Company (issuer) names over time.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: CompanyNameDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of CompanyName; end date 29991231 means the value is
      still in use.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SecurityClass
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (csv text)
    description: Security class (e.g. A, B, C) over time; blank in 93 of 100 sample rows.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: SecurityClassDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of SecurityClass; end date 29991231 means the value
      is still in use.
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SecurityType
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (csv text)
    description: Security type over time (e.g. common, unit, warrant); sample values include Common Stock,
      Ordinary Shares, Warrants, Units.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: SecurityTypeDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of SecurityType; end date 29991231 means the value is
      still in use.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SecurityStatus
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (csv text)
    description: Trading-status codes over time, e.g. A;D or A;H;A.
    enum:
    - value: A
      label: Active, freely trading security
    - value: S
      label: SEC suspension
    - value: H
      label: FINRA halt
    - value: I
      label: Internal OTC Markets halt
    - value: R
      label: SEC revocation
    - value: D
      label: Delisted (security is no longer active)
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: SecurityStatusDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of SecurityStatus; end date 29991231 means the value
      is still in use.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: ISIN
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (isin1;isin2;...) (csv text)
    description: ISIN codes over time; an empty element means no ISIN during that period (e.g. ';US5147005418').
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: ISINDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of ISIN; end date 29991231 means the value is still
      in use.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: FIGI
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (figi1;figi2;...) (csv text)
    description: Composite FIGI codes over time (OpenFIGI); empty elements allowed.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: FIGIDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of FIGI; end date 29991231 means the value is still
      in use.
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: ShareClassFIGI
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (figi1;figi2;...) (csv text)
    description: Share-class (global) FIGI codes over time (OpenFIGI); empty elements allowed.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: ShareClassFIGIDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of ShareClassFIGI; end date 29991231 means the value
      is still in use.
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: LEI
    logicalType: string
    logicalTypeOptions:
      format: semicolon-separated list, one element per period
    physicalType: string (lei1;lei2;...) (csv text)
    description: Legal Entity Identifiers over time, mapped from ISIN via GLEIF; blank in 75 of 100 sample
      rows.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: LEIDateRange
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd:yyyymmdd;... (StartDate:EndDate per period, 29991231 = still active)
    physicalType: string (yyyymmdd:yyyymmdd;...) (csv text)
    description: Start:end dates for each element of LEI; end date 29991231 means the value is still in
      use.
    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: '2024-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-ref
- property: vendorDatasetTextId
  value: eq_otc_sec_master
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_otc_sec_master.csv
- property: assetClass
  value: equity
- property: venues
  value:
  - OTC (OTCBB and Other OTC)
- property: coverage
  value: All OTC securities, November 1, 2024 to present with daily updates. Built from OTC Markets Compliance
    Data, algoseek ISIN lookups, OpenFIGI, GLEIF ISIN-to-LEI mappings and FINRA Daily List links; related
    SecIds changed through corporate actions are joined under one ASID using the OTC Corporate Actions
    dataset.
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: yyyymmdd:yyyymmdd date ranges; 29991231 = open-ended
- 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: Every page of the guide carries the running title ''US Equities OTC Corporate Actions
    Guide'' although the cover and content are the OTC Security Master guide (copy-paste error); the file
    name and cover identify the Security Master.'
  - 'Doc discrepancy: Guide Table 2 types the Ticker list as ''tricker1;ticker2'' (typo) and describes
    ShareClassFIGIDateRange as ''for each FIGI''; FIGI is described as a composite FIGI and ShareClassFIGI
    as a ''global'' FIGI.'
  - 'Doc discrepancy: Guide Table 2 marks Ticker, SecurityClass, SecurityType, ISIN, FIGI, ShareClassFIGI
    and LEI as ''Blank'' (field may be empty) and every DateRange as ''Never'', while Key Concepts says
    empty values are valid data tracked with their own date ranges; the sample confirms an empty value
    field can have a populated range (LEI blank in 75 of 100 rows, LEIDateRange always set) and empty
    list…'
  - 'Doc discrepancy: In 2 of 100 sample rows (ASID 1210000000022635 and 1210000000022668) SecurityClass
    is an empty string while SecurityClassDateRange has two periods, so a fully-empty list does not repeat
    delimiters; for all other attributes list and range have the same element count.'
  - 'Doc discrepancy: Guide Table 2 describes SecurityStatus as ''e.g., active, suspended, delisted''
    but Key Concepts defines six codes (A, S, H, I, R, D); the sample only has A, D and H.'
  - 'Doc discrepancy: Guide does not enumerate SecurityType values (examples only); the sample shows eight
    values including ''Ordinary Shares'', ''Other Security Type'' and ''Exchange-Traded Fund''.'
  - 'Doc discrepancy: Guide implies a continuous timeline per attribute, but sample ranges for one attribute
    are not always contiguous: gaps of 2-4 days (weekends/holidays) and 51-116 days occur (e.g. Ticker
    20241206:20251208;20260128:29991231), and SecurityStatus can run to 29991231 as D after the Ticker/ISIN
    ranges have ended.'
contractCreatedTs: '2026-11-02T00:00:00Z'