# 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-basic-shares-outstanding
name: AlgoSeek US Equities Basic Shares Outstanding
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- reference
- us
description:
  purpose: 'History of reported shares-outstanding figures for US exchange-listed equities: one row per
    change event giving the SecId, ticker, created/changed/effective dates and the new share count. Used
    for market capitalization, EPS and ownership/float calculations.'
  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. Three dates,
    as-of semantics: EffectiveDate = effective date of the SO value change (the as-of date of the figure);
    CreatedDate = trading date on which algoseek created the SO event; ChangedDate = date (optionally
    with an _n version suffix) on which the event was last changed. In the samples CreatedDate is never
    earlier than EffectiveDate (gap 1-93 days), so CreatedDate (or ChangedDate if revised) is the date
    a figure could have been known - use it, not EffectiveDate, to avoid look-ahead (infer… Event/step
    data, not a daily series: a row is a new SO figure. SO on a date D is the SharesOutstanding of the
    latest row with EffectiveDate <= D (and CreatedDate <= D for point-in-time use); it persists until
    the next row (inferred from the ''event'' wording). SharesOutstanding is ''the new shares outstanding
    figure'' (a level, not a change) captured from stock exchanges and company websites as soon as the
    official source publishes it; official update frequency varies from daily to annual, so gaps of months
    or years between rows are normal. Values are as reported, not restated for later splits (inferred
    from samples): AAPL 861,874,894 effective 20070124 versus 16,687,631,000 effective 20210416 (guide
    Table 1), and ARCI drops from 8,472,651 (effective 20181229) to 1,694,530 (effective 20190422), about
    one fifth, consistent with a reverse split. Recent figures are often rounded to thousands (ending
    in 000). Combine with the Adjustment Factors datasets if a split-consistent share count is needed.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-basic-shares-outstanding/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-reference/algoseek.US.Equity.Shares.Outstanding.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_SHARES_OUTST_BASIC}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: 'Plain-text CSV with fixed header row, one row per shares-outstanding (SO) change event. Two
      aggregation options with identical fields: ''all'' (a single CSV for all symbols) and ''secid''
      (one CSV per SecId, e.g. 33449/AAPL holds all its data). Guide mentions files so_basic.csv, so_detailed.csv
      and a per-SecId file being refreshed; Basic and Detailed share one guide.'
  - 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/shares-outst-basic
  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_basic_shares_outstanding
  physicalName: eq_shares_outst_basic
  physicalType: file
  logicalType: object
  businessName: US Equities Basic Shares Outstanding
  description: 'History of reported shares-outstanding figures for US exchange-listed equities: one row
    per change event giving the SecId, ticker, created/changed/effective dates and the new share count.
    Used for market capitalization, EPS and ownership/float calculations.'
  dataGranularityDescription: one shares-outstanding change event for one SecId (one new SharesOutstanding
    figure effective on EffectiveDate)
  properties:
  - name: SecId
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: algoseek unique security identifier.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol name for the security.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: CreatedDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Trading date when the SO event was created (first captured by algoseek); can fall on
      a Saturday in the sample.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: ChangedDate
    logicalType: string
    logicalTypeOptions:
      format: yyyymmdd with optional _n version suffix (no suffix appears in the sample)
    physicalType: string (yyyymmdd[_n]) (csv text)
    description: Date, plus version number when suffixed, on which the SO event was last changed; equals
      CreatedDate in 98 of 109 Basic sample rows.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: EffectiveDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Effective date of the SO value change; the figure's as-of date.
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: SharesOutstanding
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: New shares outstanding figure effective from EffectiveDate (a level, not a delta).
    customProperties:
    - property: unit
      value: shares
    - 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:
      - SecId
      - EffectiveDate
    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-ref
- property: vendorDatasetTextId
  value: eq_shares_outst_basic
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_shares_outst_basic.csv
- property: assetClass
  value: equity
- property: coverage
  value: US exchange-listed equity securities from 2007 to present (product page); official shares-outstanding
    figures from exchanges and company websites. Sample has three SecIds (AAPL 82 rows to 20230721, APPB
    4, ARCI 23).
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: yyyymmdd date strings (ChangedDate may add an _n version suffix)
- 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 2 documents CreatedDate as a ''trading date'', but 17 of 109 sample
    rows have a Saturday CreatedDate (e.g. 20071117, 20171104, 20200104, 20230805); in 11 rows ChangedDate
    is the following Monday.'
  - 'Doc discrepancy: ChangedDate is documented as yyyymmdd[_n] with a version suffix, but none of the
    109 sample rows carries a suffix.'
  - 'Doc discrepancy: Update cadence: guide says ''a couple of times a day'' (starting 04:00 AM EST);
    product page says ''multiple times per day''.'
  - 'Doc discrepancy: File names: guide mentions so_basic.csv / so_detailed.csv; published samples are
    eq_shares_outst_basic.csv / eq_shares_outst_detail.csv.'
  - 'Doc discrepancy: Guide gives no Missing/null column for this dataset; the sample has no blank values.'
  - 'Doc discrepancy: No unique key is stated for the Basic file (no EventId column); (SecId, EffectiveDate)
    is unique in the 109-row sample, but the guide says events can be ''changed'', so revisions may repeat
    an effective date.'
contractCreatedTs: '2026-11-02T00:00:00Z'