Enhancement [CAT-FR-CO-05] Docs: validation strategy cleanup + provenance cascade#39
Open
peleskek wants to merge 10 commits into
Conversation
…itecture guide - Added Validation Result Storage to the building block view summary. - Detailed the PostgreSQL schema (`VALIDATION_RESULT` table) and data model for persisting on-demand credential validation outcomes. - Documented the REST API endpoints for retrieval and the graph re-projection mechanism for `FAILED` records during graph rebuilts.
* docs(CAT-FR-LM-04): document validation result lifecycle in schema validation service Add result storage and lifecycle rules (OutdatedReason enum, OUTDATED marking on update/revoke, cascade delete on asset delete). * feat(CAT-FR-LM-04): cleanup * feat(CAT-FR-LM-04): resolve comment --------- Co-authored-by: saackef <fabian.saacke@msg.group>
* [CAT-FR-CO-05] on demand validation docs
- Add On-Demand Asset Validation Service section: AssetValidationService,
ValidationStrategy pattern (ShaclValidationStrategy, JsonSchemaValidationStrategy,
XmlSchemaValidationStrategy), ShaclValidationExecutor shared engine,
multi-asset cardinality rules, max-assets-per-request and timeout config
- Document asset deletion cascade: AssetDeletedEvent -> ValidationResultCleanupListener
-> ValidationResultStore.deleteByAssetId (BEFORE_COMMIT atomicity)
- validator_type column lists SHACL, JSON_SCHEMA, XML_SCHEMA, TRUST_FRAMEWORK
- On-demand validation endpoint is POST /assets/validate
- ValidationResultStore class diagram includes findAll, syncToGraph, deleteByAssetId
- SchemaValidationService is scoped to the upload/revalidation path
- Admin table reflects JSON Schema and XML Schema wiring through AssetValidationService
- Component table refers to "asset validation"
- Verify Credential procedure (chapter 6): on-demand validation routes through
AssetValidationService (SHACL/JSON/XML); SchemaValidationService remains the
upload-flow path, gated by federated-catalogue.verification.schema
- Delete Participant sequence (chapter 6): note the AssetDeletedEvent cascade that
cleans up validation results before commit
- Input Parsing Security cross-cutting concept (chapter 8): XXE hardening
(FEATURE_SECURE_PROCESSING + empty external DTD/schema access), SSRF protection
via JSON $ref scheme allowlist, and SPARQL injection prevention via requireSafeIri
* [CAT-FR-CO-05] remove requirement ids
* introduce trust framework bundles * correct current state about incomplete schema loading * remove the framework-bundled ontology and shapes from defaultschemas * remove deleted methods
* docs: asset metadata enrichment Document the metadata enrichment path: routing on POST /assets when the uploaded RDF's primary subject IRI matches an existing non-RDF asset, the resulting graph and content updates, and the new content_kind column. Adds ADR 10 covering the subject-IRI routing decision and overwrite semantics, plus glossary entries for ContentKind and Metadata Enrichment. * feat(CAT-FR-AM-03): resolving comments * feat(CAT-FR-AM-03): resolving comments --------- Co-authored-by: saackef <fabian.saacke@msg.group>
* introduce trust framework bundles * correct current state about incomplete schema loading * remove the framework-bundled ontology and shapes from defaultschemas * add role to result mapping from bundle metadata * describe the no-adapter decision in ADR-10 * explain role declaration and the additional_roots mechanic for DSO mapping to ServiceOffering * explain role declaration and the additional_roots mechanic for DSO mapping to ServiceOffering * replace method name * update documentation with partial refactoring changes continued in the follow-up cleanup branch. --------- Signed-off-by: Eric Nowak <eric.nowak@msg.group>
…e cascade listener (#28) Aligns arc42 building block and runtime views with the cleanup PR: SHACL evaluation now runs directly inside ShaclValidationStrategy and SchemaValidationServiceImpl (no shared executor), and ProvenanceCleanupListener joins ValidationResultCleanupListener as a second AssetDeletedEvent consumer.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📦 [CAT-FR-CO-05] Docs: validation strategy cleanup + provenance cascade
🚀 Summary
Architecture docs catch up with the federated-catalogue cleanup PR:
ShaclValidationStrategyandSchemaValidationServiceImplnow evaluate SHACL directly via the TopBraid engine — no sharedShaclValidationExecutorindirection, no separate timeout/pool configuration paragraph.ValidationResultCleanupListenerandProvenanceCleanupListeneras@TransactionalEventListener(BEFORE_COMMIT)consumers ofAssetDeletedEvent.Requirement: CAT-FR-CO-05 — On-demand Validation of Assets against Schemas
This change is part of the Enhancement of XFSC Federated Catalogue. Details can be found here (permalink): https://github.com/eclipse-xfsc/docs/blob/f3c6e6b6fbcc87732a1dfe83f060fa58a9a97873/federated-catalogue/src/docs/CAT%20Enhancement/CAT_Enhancement_Specifications%20v1.0.pdf
✅ What's in this PR
Modified files:
05_building_block_view.adocShaclValidationExecutor" line and the "TopBraid SHACL in an isolated fixed-size thread pool + hard timeout" paragraph with a single line stating that both the upload-verification and on-demand paths invoke the TopBraid SHACL engine directly, on the request thread.deleteAssetdescription to mention that the cascade cleans up associated provenance credentials in addition to validation results.@TransactionalEventListener(BEFORE_COMMIT)consumers —ValidationResultCleanupListener(rows + best-effort graph triples) andProvenanceCleanupListener(provenance credential rows) — and clarify that all three deletions share the asset's transaction.06_runtime_view.adocNote over AssetStorenow lists both listeners.ShaclValidationExecutorfor SHACL evaluation" clause and replaces it with "both flows evaluate SHACL via the same TopBraid SHACL engine".No ADR is needed — both changes adopt patterns already established by existing ADRs and by
ValidationResultCleanupListener.🔍 Related Issues
Related to PR federated-catalogue — CAT-FR-CO-05 cleanup work (
feature/CAT-FR-CO-05-cleanup-work)Documents the corresponding behaviour for CAT-FR-CO-05 (On-demand Validation of Assets against Schemas).
📋 Checklist