Validate generated fiscal XML against versioned official XSD bundles #48

Parent epic: #47

Context

The library has a reference schema snapshot, but schema validation must become an explicit compatibility contract rather than a set of string assertions. Other NFS-e implementations validate generated XML against the official XSD in tests, which catches element order, optionality, enums and version drift.

Current production documentation publishes NFS-e XSD v1.01 and related DPS/NFS-e/event layouts.

Goal

Create a versioned schema subsystem and CI tests that validate every generated DPS/event XML against the exact official schema release the library claims to support.

Scope

• keep official XSD snapshots under a versioned path with source URL, publication date and checksum metadata
• expose an internal/schema-test helper that validates XML with libxml using local files only
• validate representative DPS scenarios: taxable, retained ISS, immunity, export, suspended enforceability, IBS/CBS, foreign taker, alphanumeric CNPJ
• validate cancellation and future event payloads
• fail with useful schema diagnostics
• add a documented update procedure for a new official schema release

Constraints

• never download schemas during tests or runtime
• preserve exact official files; do not hand-edit XSD contents
• XML parsing must disable network/external entity resolution
• supporting a new schema version must be an explicit change

Tests

• valid fixtures pass
• wrong element order fails
• invalid enum fails
• unsupported schema version fails clearly
• XXE/network resolution remains disabled

Definition of done

• all generated fiscal XML classes covered by XSD tests
• schema source/checksum/version documented
• CI executes validation on supported PHP versions
• no network dependency in test execution

Implementation status (2026-10-04)

Already present on main:

• official NFS-e/DPS 1.01 XSD bundle under references/schemas/nfse/1.01;
• local-only DpsSchemaValidator using libxml schema validation;
• representative DPS XSD contract tests, including newer fiscal groups;
• schema source/version documentation in the bundled README.

Remaining work for this issue:

• extend versioned schema coverage to generated event XML and any other generated fiscal XML classes, not only DPS;
• make checksum/source metadata mechanically verifiable rather than descriptive only;
• document/rehearse the update procedure for a new official schema release;
• add explicit unsupported-version and XXE/network-resolution regression coverage if not already equivalent.

Do not duplicate the existing DPS validator/bundle.