# 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-market-holidays
name: AlgoSeek US Equities Market Holidays
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
- calendar
description:
  purpose: A list of the weekday dates on which the US equity (and equity options) market is closed all
    day, from 1998 onward. A companion file lists early-close days with open and close times. Used to
    schedule data processing and avoid false missing-data alerts in backtests.
  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. Meaning: a TradeDate
    in holidays.csv is a weekday full-closure date; the sample contains weekdays only (Mon-Fri) and uses
    observed dates (e.g. 20051226 when Christmas fell on a Sunday, no 20000101 when New Year''s Day fell
    on a Saturday), so weekends are NOT listed and consumers must combine the list with a weekend rule.
    Sample includes ad hoc closures as well as scheduled holidays (20010911-20010914 September 11 closure,
    20040611 and 20070102 national days of mourning), so the list is the set of actual closures, not just
    statutory holidays. Early closes (earlycloses.csv, guide Tables 2 and 4): columns TradeDate (string
    yyyymmdd), MarketOpen (string HH:MM), MarketClose (string HH:MM); guide sample dates 20181224, 20190703,
    20191129, 20191224, 20201127, 20201224, 20211126, 20221125, 20230703, 20231124, each 09:30-13:00.
    A date in earlycloses.csv is a trading day with a shortened session; it should not be in holidays.csv.
    Use cases per guide: avoid alerting on missing data on holidays, avoid alerting on a shortened feed
    on scheduled early-close days, and detect unscheduled historical feed cut-offs by comparing against
    early closes.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-market-holidays/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.Market.Calendar.pdf
  - type: implementation
    url: https://algoseek.com/docs/rest-api/reference
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_MARKET_HOLIDAYS}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: 'Two public plain-text CSV files, each with a fixed header and one row per date: s3://us-equity-market-holidays/holidays.csv
      (TradeDate) and s3://us-equity-market-holidays/earlycloses.csv (TradeDate,MarketOpen,MarketClose);
      direct HTTPS links https://us-equity-market-holidays.s3.amazonaws.com/holidays.csv and .../earlycloses.csv.
      Whole history in one file each.'
  - 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-ref/market-holidays
  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_equities_market_holidays
  physicalName: eq_market_holidays
  physicalType: file
  logicalType: object
  businessName: US Equities Market Holidays
  description: A list of the weekday dates on which the US equity (and equity options) market is closed
    all day, from 1998 onward. A companion file lists early-close days with open and close times. Used
    to schedule data processing and avoid false missing-data alerts in backtests.
  dataGranularityDescription: one full-day market closure (one trading date) per row
  properties:
  - name: TradeDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Trading date on which the US equity market is closed for the full day.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: nullMeaning
      value: unstated (always populated)
    - 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
    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: '1998-01-01'
  description: First trade date of the vendor history.
- 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_market_holidays
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_market_holidays.csv
- property: assetClass
  value: reference
- property: coverage
  value: Holidays and early closes from 1998 through the end of the year following the current year (forward-looking).
    Applies to US equity and equity options markets. The guide points to the NYSE hours and calendars
    page for further reference.
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: yyyymmdd (TradeDate); HH:MM for MarketOpen/MarketClose in earlycloses.csv
- property: sessionHours
  value: early-close days 09:30-13:00 (guide sample); regular session hours not stated
- 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.
  - Update cadence and publication latency are not stated in the guide; confirm with AlgoSeek (or GET
    /v1/meta/datasets/{id}/status).
  - 'Doc discrepancy: Page description says the dataset covers ''full market holidays and early market
    closes''; the published sample (eq_market_holidays.csv, header TradeDate) contains only the holiday
    dates. Early closes are a separate file, earlycloses.csv, with columns TradeDate, MarketOpen, MarketClose
    (guide Table 4); that file is not in the catalog sample.'
  - 'Doc discrepancy: The guide matches the public files named in the task: holidays.csv has the single
    header TradeDate and earlycloses.csv has TradeDate, MarketOpen, MarketClose; the guide''s Table 2
    early-close sample is garbled in text extraction but shows 09:30 / 13:00 for every row.'
  - 'Doc discrepancy: Guide cover is version 1.1 (Aug 2026) while the guide describes data ''through the
    end of the year following the current year''; the 100-row sample ends 20080704 (sample is truncated,
    not a coverage statement).'
  - 'Doc discrepancy: Guide gives no Missing column and no refresh cadence for the files.'
contractCreatedTs: '2026-11-02T00:00:00Z'