feat(validation): improve user-facing schema validation errors

[saquibsaifee]

Description

Implements the structured validation error improvement planned in #836 (which remains a WIP draft by the maintainer). PR #840 (already merged) laid the groundwork by introducing JsonValidationError and XmlValidationError subclasses — this PR completes that work.

Changes:

• ValidationError gains three structured fields: message (human-readable str), path (tuple of path segments to the offending value), and data (raw backend error object). __str__ and __repr__ now use message.
• JsonValidationError._make_from_jsve recurses into nested jsonschema context errors to surface the most specific leaf failure for oneOf/anyOf checks, instead of emitting the generic parent message.
• XmlValidationError._make_from_xle extracts e.message and e.path from lxml's _LogEntry, normalising XML errors to the same message/path shape.

Closes #827

---

Note: This PR was originally based on #836 to build on top of its stub. Since #836 is a WIP draft and #840 (which merged the stubs into main) has already landed, this PR is now retargeted directly to main.

AI Tool Disclosure

• My contribution includes AI-generated content, as disclosed below:
  • AI Tools: GTP Codex
  • LLMs and versions: GPT-5.3-Codex
  • Prompts: [Summarize the key prompts or instructions given to the AI tools]

Affirmation

• My code follows the CONTRIBUTING.md guidelines

[read-the-docs-community]

Documentation build overview

📚 CycloneDX Python Library | 🛠️ Build #33589345 | 📁 Comparing ac93dbc against latest (0daf3f9)

  🔍 Preview build  

11 files changed · + 2 added · ± 9 modified

+ Added

• autoapi/cyclonedx/contrib/bom/index.html
• autoapi/cyclonedx/contrib/bom/utils/index.html

± Modified

• changelog.html
• genindex.html
• py-modindex.html
• autoapi/index.html
• autoapi/cyclonedx/contrib/index.html
• autoapi/cyclonedx/output/index.html
• autoapi/cyclonedx/validation/index.html
• autoapi/cyclonedx/model/crypto/index.html
• autoapi/cyclonedx/model/license/index.html

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 5 complexity · 0 duplication

Metric	Results
Complexity	5
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[saquibsaifee]

@jkowalleck is this along the lines of what you had in mind for #827?

PR #940 builds directly on the work from #834 and #840 already in main. Here's what it adds:

• ValidationError now has .message (bounded str) and .path (tuple) alongside the existing .data
• JSON: recurses into oneOf/anyOf context errors to surface the deepest failure, then caps the message at 256 chars — so the full SPDX licence list no longer leaks through
• XML: same 256 char cap on lxml's _LogEntry.message

Before/after on the exact test files from the issue (attaching screenshots):

• JSON str(error): 111,672 → 257 chars
• XML str(error): 13,430 → 257 chars
• .message and .path: were AttributeError, now work as expected

Raw data is still there for anyone depending on it. Happy to adjust the message cap value, the path shape, or anything else — just let me know!

Test code and output:

"""AFTER — our branch"""
from cyclonedx.schema import SchemaVersion
from cyclonedx.validation.json import JsonStrictValidator
from cyclonedx.validation.xml import XmlValidator

SEP = '=' * 72

# --------------- JSON ---------------
json_file = 'tests/_data/schemaTestData/1.2/invalid-license-id-1.2.json'
with open(json_file) as fh:
    json_data = fh.read()

json_validator = JsonStrictValidator(SchemaVersion.V1_2)
error = json_validator.validate_str(json_data)

print(SEP)
print('JSON')
print(SEP)
print(f'type(error)       : {type(error).__qualname__}')
print(f'type(error.data)  : {type(error.data).__qualname__}')
print(f'len(str(error))   : {len(str(error)):,} chars')
print(f'error.message     : {error.message!r}')
print(f'error.path        : {error.path!r}')

# --------------- XML ---------------
xml_file = 'tests/_data/schemaTestData/1.1/invalid-license-id-1.1.xml'
with open(xml_file) as fh:
    xml_data = fh.read()

xml_validator = XmlValidator(SchemaVersion.V1_1)
error = xml_validator.validate_str(xml_data)

print()
print(SEP)
print('XML')
print(SEP)
print(f'type(error)       : {type(error).__qualname__}')
print(f'type(error.data)  : {type(error.data).__qualname__}')
print(f'len(str(error))   : {len(str(error)):,} chars')
print(f'error.message     : {error.message!r}')
print(f'error.path        : {error.path!r}')