> ## Documentation Index
> Fetch the complete documentation index at: https://noxstock.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema 2 refusals and provenance

> The schema-2 refusal grammar, refusal catalog, and doc_extracted provenance class.

Schema 2 uses one refusal discriminator everywhere:

```json theme={null}
{ "unavailable": "not_reported" }
```

An object is a refusal if and only if it contains `unavailable`. Do not replace it with `0`, `null`, or an empty chart point.

For the product decisions behind deliberately absent metrics, see [why specific metrics are deliberately absent →](/why-we-refuse).

## Refusal grammar

```json theme={null}
{
  "unavailable": "valuation_operand_unavailable",
  "missing_operand": "shares_outstanding",
  "affects": ["market_cap", "price_to_book"],
  "recovery": { "action": "none", "note": "shares_outstanding is a data gap we own; no caller action serves it" }
}
```

Refusals can appear at four altitudes:

* cell: one period of one field
* field row: all requested periods for one field
* block: one cause affects multiple fields
* response: `data` itself is a refusal

## Worked block refusal

Request schema 2 explicitly:

```bash theme={null}
curl -sS "https://api.stockcontext.com/v1/tools/stock_overview" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"symbol":"RIVN","detail":"core"}'
```

Trimmed from `tests/fixtures/overview_v2/golden_overview_rivn_core.wire.json`; shown values are unchanged.

```json theme={null}
{
  "data": {
    "snapshot": {
      "period": "FY2025",
      "price": { "close": 17.18, "session": "2026-07-01" },
      "revenue": { "v": "5387000000", "d": "≈$5.387B" },
      "net_income": { "v": "-3646000000", "d": "≈-$3.646B" },
      "shares_outstanding": { "unavailable": "not_reported" }
    },
    "valuation": {
      "block_refusal": {
        "unavailable": "valuation_operand_unavailable",
        "recovery": {
          "action": "none",
          "note": "shares_outstanding is a data gap we own; no caller action serves it"
        },
        "missing_operand": "shares_outstanding",
        "affects": [
          "market_cap",
          "price_to_book",
          "price_to_sales",
          "enterprise_value",
          "ev_to_sales",
          "earnings_yield_pct",
          "book_value_per_share",
          "fcf_per_share"
        ]
      },
      "price_to_earnings": { "unavailable": "ratio_undefined_nonpositive_denominator" },
      "price_to_fcf": { "unavailable": "ratio_undefined_nonpositive_denominator" },
      "dividend_yield_pct": { "unavailable": "valuation_operand_unavailable", "missing_operand": "dividends_paid" }
    }
  }
}
```

The block refusal covers only fields that the missing share count would unlock. Other fields keep their own reasons.

## Closed vocabulary

Resolve tokens with the refusal catalog:

```bash theme={null}
curl -sS "https://api.stockcontext.com/v1/tools/stock_reference" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"catalog":"refusal_reasons"}'
```

Trimmed from `tests/fixtures/v2_golden/reference_refusal_reasons.json`.

```json theme={null}
{
  "data": {
    "catalog": "refusal_reasons",
    "items": [
      {
        "token": "ingestion_pending",
        "meaning": "This company is known but its filings are not ingested yet; retry later.",
        "recovery": [
          { "action": "retry", "requires": ["retry_after_s"] },
          { "action": "none" }
        ]
      },
      {
        "token": "interim_not_filed_with_sec",
        "meaning": "The filer files no interim (10-Q) reports with the SEC, so no quarterly fundamentals exist to serve — a fact about the filer (a 20-F/40-F foreign private issuer publishes interim results only as unstructured 6-K narrative, never as sub-annual XBRL), not a coverage gap.",
        "recovery": [{ "action": "none" }]
      },
      {
        "token": "invalid_request",
        "meaning": "The request failed parameter validation. errors[] names each offending param with what was given and what is expected; the recovery carries a literal corrected params fragment whenever one can be honestly derived (alias canonicalization or a documented default).",
        "recovery": [
          { "action": "supply_params", "requires": ["params"] },
          { "action": "none" }
        ]
      },
      {
        "token": "not_applicable_for_shape",
        "meaning": "The statement shape structurally lacks this line, distinct from a filer-specific not_reported omission; use the named shape-native analog when the recovery provides one.",
        "recovery": [
          { "action": "use_alternative_field", "requires": ["field"] },
          { "action": "none" }
        ]
      }
    ]
  },
  "meta": { "schema_version": "2" }
}
```

## `doc_extracted`

Most served fundamentals are direct tagged values or exact derivations from tagged operands. `doc_extracted` is an exceptional provenance class for a value extracted from the filed document rather than the normal direct XBRL face path, and it is stamped so an agent does not quote it as a plain direct tagged value.

Request schema 2 explicitly:

```bash theme={null}
curl -sS "https://api.stockcontext.com/v1/tools/stock_financials" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"symbol":"DEMO","statements":["income"],"periods":1}'
```

Trimmed from `tests/fixtures/render_v2/golden_doc_extracted_income_core.wire.json`; shown values are unchanged.

```json theme={null}
{
  "data": {
    "statement": "income_statement",
    "shape": "operating_company",
    "periods": [{ "id": "FY2025", "start": "2024-09-29", "end": "2025-09-27", "restated": false }],
    "source": { "form": "10-K", "accession": "0001067983-25-000123", "filed": "2025-10-31" },
    "fields": {
      "revenue": ["416161000000"],
      "net_income": ["112010000000"],
      "eps_diluted": [{ "v": "7.46", "source_class": "doc_extracted" }]
    },
    "unavailable_fields": {
      "operating_income": {
        "unavailable": "verification_pending",
        "recovery": { "action": "retry", "retry_after_s": 3600 }
      }
    }
  },
  "meta": { "schema_version": "2", "as_of": { "sec": "2025-10-31" } }
}
```

The repo has a dedicated fixture for this class, but no committed coverage catalog with a measured frequency. Treat it as rare and explicitly stamped; do not publish a rate until the coverage catalog reports one.