Expose Extensible Enumerations 2.0 metadata and structured fact values

[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.

EdgarTools recognizes an Extensible Enumerations 2.0 concept's data_type, but the schema attributes that define its allowed-value domain are not publicly accessible. Filed enumeration facts consequently remain only raw expanded-name URI strings.

Microsoft's 2026 10-K provides a concrete example. Its extension schema declares:

<xsd:element
    id="msft_DerivativeAssetStatementOfFinancialPositionExtensibleEnumerationNotDisclosedFlag"
    type="enum2:enumerationSetItemType"
    enum2:domain="us-gaap:AssetsAbstract"
    enum2:headUsable="false"
    enum2:linkrole="http://fasb.org/us-gaap/role/eedm/ExtensibleEnumerationLists"
    ... />

The filing then reports two facts whose value is:

http://fasb.org/us-gaap/2025#DerivativeAssets

On current main, the public catalog entry contains only:

{
    "name": "msft_DerivativeAssetStatementOfFinancialPositionExtensibleEnumerationNotDisclosedFlag",
    "data_type": "enum2:enumerationSetItemType",
    "period_type": "instant",
    "balance": None,
    "abstract": False,
    "labels": {...},
}

There is no enumeration domain, link role, head-usability flag, allowed-member collection, or resolved enumeration value. FactQuery reaches both facts, but their values remain the technical URI strings.

This request is not being presented as a confirmed regression or violation of an existing EdgarTools API contract. No current public ElementCatalog field promises Extensible Enumerations metadata. It is a filing-backed unsupported capability that prevents callers from interpreting a standards-defined fact type without reparsing the raw schema and definition network themselves.

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 add an additive public representation for Extensible Enumerations 2.0 concepts. A useful first increment would let callers access:

• the enum2:domain concept;
• the enum2:linkrole that identifies the relevant domain-member network;
• the effective enum2:headUsable value;
• the parsed expanded-name URI value or values of each enumeration fact as a structured set.

This could be exposed through additional ElementCatalog fields, a dedicated enumeration metadata object, or a helper such as xbrl.get_enumeration(concept). The existing lexical Fact.value can remain unchanged for backwards compatibility while an additive field or helper supplies structured values. A follow-on capability could resolve the effective usable-member network, validate filed values against it, and attach labels while honoring targetRole, usability, prohibition, priority, and cross-role traversal semantics.

Describe alternatives you've considered

Callers can inspect ElementCatalog.data_type, parse the extension XSD again for enum2:* attributes, locate the specified definition role, build the effective domain-member network, apply member usability, split and validate the expanded-name URI set, and then resolve labels. That duplicates taxonomy processing that EdgarTools already performs for adjacent schema, label, and definition structures.

Returning the raw URI string correctly preserves the standards-defined lexical value, but it does not decompose it into structured concept identity, relate it to the declared domain, validate whether it is allowed, or provide the user-facing label that enumeration-aware XBRL applications normally display.

Use Case Example

How would you use this feature?

from edgar import get_by_accession_number, set_identity

set_identity("Your Name your.email@example.com")
filing = get_by_accession_number("0001193125-26-323660")
assert filing is not None
xbrl = filing.xbrl()
assert xbrl is not None

concept = (
    "msft_DerivativeAssetStatementOfFinancialPosition"
    "ExtensibleEnumerationNotDisclosedFlag"
)

# Current public surface: the type is known, but its enumeration definition is not.
element = xbrl.element_catalog[concept]
print(element.data_type)
print(element.__dict__)

facts = xbrl.query().by_concept(concept.replace("_", ":", 1), exact=True).execute()
print([fact["value"] for fact in facts])

# Illustrative additive API; exact naming is left to the maintainer.
enumeration = xbrl.get_enumeration(concept)
print(enumeration.domain)
print(enumeration.linkrole)
print(enumeration.head_usable)
print(enumeration.allowed_members)
print(enumeration.resolve(facts[0]["value"]))

The current output begins:

enum2:enumerationSetItemType
{'name': 'msft_DerivativeAssetStatementOfFinancialPositionExtensibleEnumerationNotDisclosedFlag',
 'data_type': 'enum2:enumerationSetItemType',
 'period_type': 'instant',
 'balance': None,
 'abstract': False,
 'labels': {...}}
['http://fasb.org/us-gaap/2025#DerivativeAssets',
 'http://fasb.org/us-gaap/2025#DerivativeAssets']

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

Schema metadata preservation is localized: SchemaParser.parse_schema_content() currently retains type, period type, balance, and abstract status but does not read the three enum2:* attributes. The public ElementCatalog has no corresponding fields.

Resolving allowed values is more involved because the domain is role-specific and must honor the effective domain-member network, including usability, prohibitions, priority, and cross-role traversal. The requested first increment can preserve the raw schema metadata and parse the lexical URI set; relationship-aware allowed-member validation and label resolution can follow without changing Fact.value.

For enumerationSetItemType, the structured representation should treat the value as a set while retaining deterministic source/canonical ordering where useful. The specification requires expanded-name URIs in the lexical value to be unique and lexicographically ordered.

Additional Context

This was reproduced with EdgarTools 5.55.0, CPython 3.14.4, upstream main at a0ff18089c844ddfe81bd21a1c7c56f4ed629e55, and audit worktree 70c31469dc7e6d4b386a6f8fe4ce1276d48fca51 whose edgar/** tree is identical, using Microsoft Corporation's 10-K:

• Ticker: MSFT
• Accession: 0001193125-26-323660
• Filed: July 29, 2026
• Period ended: June 30, 2026
• Retrieval: get_by_accession_number("0001193125-26-323660").xbrl() as shown above; the SEC filing index lists the required attachments
• Raw sources: extension schema and Inline XBRL document

The same filing contains a liability counterpart with enum2:domain="us-gaap:LiabilitiesAbstract" and two values of http://fasb.org/us-gaap/2025#DerivativeLiabilities.

This is not an isolated one-off syntax. The same enum2:headUsable="false" pattern appears in 12 consecutive cached MSFT filings from accession 0000950170-23-054855 through the primary accession above. Monster Beverage Corporation's 2025 10-K (0001104659-26-020831) independently declares mnst:IncomeTaxExaminationAuthorityNameExtensibleEnumeration with enum2:domain="us-gaap:IncomeTaxAuthorityNameDomain", enum2:headUsable="false", and a filed Internal Revenue Service member value.

Extensible Enumerations 2.0 defines the domain of allowed values from the domain, linkrole, and effective headUsable attributes. It also defines non-nil enumerationSetItemType facts as space-separated sets of expanded-name URIs drawn from that allowed domain.

A source-only functional search at a0ff18089c844ddfe81bd21a1c7c56f4ed629e55 found no implementation or documentation support, and no Python test exercising enum2 metadata or value resolution, in edgar/**, docs/**, or tests/**/*.py. Raw filing cassettes and fixtures were excluded from that capability claim. A search of the local First-through-Fourth-Wave draft corpus found no duplicate. Targeted searches of the open and closed GitHub tracker for “extensible enumeration,” enumerationSetItemType, headUsable, and enum2 found no matching issue.

Related Issues/Features:

No exact match was found. This request is adjacent to dimensional-definition parsing because enumeration domains reuse domain-member networks, but it does not duplicate the existing reports about targetRole, hypercube closed, sibling order, or Domain.parent. Those reports concern fields and relationships already represented by EdgarTools; this request asks for a public representation of an additional XBRL standard feature.

A live search of the open and closed GitHub issue tracker should be repeated immediately before submission.

---

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