Represent incomplete or unavailable `Statement.validate()` checks separately from successful validation

[synfonia-llc]

Feature Category

• New API functionality
• Performance improvement
• Developer experience improvement
• Documentation enhancement
• Tool/utility addition

Problem Statement

Is your feature request related to a problem? Please describe.

Statement.validate() can return is_valid=True and render VALID when a substantive check could not be completed or when no validator exists for the statement type.

In EdgarTools 5.53.0, is_valid appears to mean “no error-severity issue was emitted by the checks that ran.” A caller can reasonably interpret it as “the requested validation completed successfully.” The result object currently requires every consumer to infer incomplete or unavailable validation from warning- or INFO-level issue codes.

This is a result-state ambiguity, not an assertion that the tested Oracle balance sheet is invalid. Exact same-context facts for Assets and Liabilities and Stockholders' Equity are equal in the filing.

Who would benefit from this feature?

• Beginner Python users working with SEC filings
• Financial analysts and researchers
• Advanced developers building financial applications
• Data scientists working with financial datasets

Proposed Solution

Describe the solution you'd like

Please represent validation outcome and validation completion separately. One backwards-compatible design would add:

result.status               # "valid", "invalid", or "inconclusive"
result.validation_complete  # bool
result.checks_attempted      # list[str]
result.checks_completed      # list[str]

is_valid could remain as the existing compatibility boolean, with documentation that it only reports whether performed checks found an error. Rendering should say INCONCLUSIVE when a requested substantive check could not run or no validator is available.

Describe alternatives you've considered

• Document is_valid as “no errors found” and require callers to inspect every issue code.
• Raise an exception when no validator exists.
• Return None from is_valid for inconclusive cases.

An additive status/completion field is easier to adopt and preserves existing boolean-based callers.

Use Case Example

How would you use this feature?

from pathlib import Path

from edgar.xbrl import XBRL

# Run from a directory containing the unpacked accession package.
xbrl = XBRL.from_directory(
    Path("0000950170-23-047713") / "xbrl"
)

balance = xbrl.statements.balance_sheet()
income = xbrl.statements.get(
    "Role_StatementCONDENSEDCONSOLIDATEDSTATEMENTSOFOPERATIONS"
)

for name, statement in (("balance", balance), ("income", income)):
    result = statement.validate(level="detailed")
    print(name, result.is_valid, result.checks_performed)
    print([str(issue) for issue in result.issues])
    print(str(result))

Observed output includes:

balance True ['fundamental_equation', 'section_totals']
[WARNING] INCOMPLETE_DATA: Could not validate equation: missing Liabilities and/or Equity totals
ValidationResult: VALID (0 errors, 1 warnings)

income True ['type_detection']
[INFO] NO_VALIDATOR: No validator available for statement type: IncomeStatement
ValidationResult: VALID (0 errors, 0 warnings)

With an explicit completion state, both results could be represented as inconclusive without describing the underlying filing as invalid.

Implementation Considerations

Complexity Level:

• Simple (minor API addition)
• Moderate (new functionality with existing patterns)
• Complex (significant architectural changes)

Backwards Compatibility:

• This feature maintains backwards compatibility
• This feature might break existing code (please explain below)
• Unsure about compatibility impact

The additive fields can be derived from existing issue codes and check bookkeeping while leaving is_valid in place. The pinned generic validation path currently returns is_valid=True with NO_VALIDATOR for unsupported statement types; see validate_statement().

Additional Context

This was reproduced with EdgarTools 5.53.0, CPython 3.14.4, and Oracle 10-Q accession 0000950170-23-047713.

At the same instant context C_028c7bb3-56aa-481b-864a-2f3dc233de1a and unit U_USD, exact FactQuery results contain:

• us-gaap:Assets = 136662000000; and
• us-gaap:LiabilitiesAndStockholdersEquity = 136662000000.

The balance-sheet warning therefore reflects the convenience validator's extraction path, not a demonstrated failure of the filing to balance. Separately, the Income Statement, Cash Flow Statement, Comprehensive Income Statement, and multiple disclosures return the NO_VALIDATOR pattern.

Statement.validate() is an EdgarTools product diagnostic. This request does not treat it as formal XBRL validation, an accounting-standard conclusion, or independent assurance.

Related Issues/Features:

A bounded search of open and closed issues for Statement.validate NO_VALIDATOR on August 31, 2026 did not identify an exact match. Please recheck before submission.

---

Feature requests are evaluated based on EdgarTools' core principles: Simple yet powerful, accurate financials, beginner-friendly, and joyful UX.