Enhancement [CAT-FR-AU] Document schema-module admin toggles in the architecture chapters#41
Merged
Conversation
…pping to ServiceOffering
…pping to ServiceOffering
* [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
continued in the follow-up cleanup branch.
* introduce trust framework bundles * correct current state about incomplete schema loading * remove the framework-bundled ontology and shapes from defaultschemas * remove deleted methods
…ouple-result-types-from-roles # Conflicts: # federated-catalogue/src/docs/architecture/chapters/05_building_block_view.adoc # federated-catalogue/src/docs/architecture/chapters/08_concepts.adoc # federated-catalogue/src/docs/architecture/chapters/09_architecture_decisions.adoc # federated-catalogue/src/docs/architecture/chapters/12_glossary.adoc
* 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.
…anup-credential-verification-strategy Cleanup credential verification strategy
* [CAT-FR-AU] document schema-module admin toggles in the architecture chapters
- 09_architecture_decisions.adoc — new ADR 16 splitting the four
toggles into validators (module_disabled:<MODULE> on 400) and OWL
(gates tier-3 role resolution; custom-subclass uploads rejected with
400, registry-direct types unaffected). Related: ADR 10.
- 05_building_block_view.adoc — Admin API tables reflect the wired OWL toggle and module_disabled:<MODULE> contract; new NOTE on verifySchema vs SHACL toggle; new "Schema-module admin toggles" subsection covering the admin page, OntologyImpactService, and toggle semantics.
- 08_concepts.adoc — new "Type Dispatch and the OWL Toggle" entry
documenting the three-tier resolver and that OWL gates tier 3 only.
- 12_glossary.adoc — Schema Module, OWL Module Toggle, Subclass Walk, Composite Ontology.
- 04_solution_strategy.adoc — non-RDF schemas section notes that
on-demand validation invokes JSON Schema / XML Schema for non-RDF assets; links to ADR 16.
- 07_deployment_view.adoc — new "Runtime Admin Configuration"
subsection covering admin_config persistence and the start-up
verifySchema flag vs admin module toggles.
* [CAT-FR-AU] address PR review and document gated SHACL sweep
- 08_concepts: OWL toggle description leads with operator-facing
effect (admits runtime ontology extensions yes/no) before the
tier-3 implementation detail; admin UI labels follow suit.
- 05_building_block_view: document the parseError flag,
noActiveBundles flag, and per-root 2 s SPARQL timeout on the
ontology impact list; document the SHACL toggle gating the
background revalidation sweep with auto-resume on re-enable.
- ADR 16: replace the "sweep not yet gated" hedge with the actual
behavior — gated both at ingest and on the sweep, with
RevalidationService.startValidating() re-sweeping the backlog
on false→true; ObjectProvider so it no-ops when the Revalidation
bean is not registered. Separate bullet documents the on-demand
validation 422→400 alignment for "no module enabled or applicable".
* [CAT-FR-AU] describe SHACL revalidation gate as dormant — drop resume-sweep
The resume-sweep wiring it documented has been reverted on the code
side (RevalidationServiceImpl has no production Spring bean today,
so the ObjectProvider always resolved to null). The gate stays —
correctness when the sweep is eventually wired — but the auto-resume
hook is gone.
- 09_architecture_decisions.adoc (ADR 16): SHACL bullet now describes
only the gate; the previous "admin write path detects false→true
and calls startValidating()" paragraph replaced with a one-sentence
follow-up note tying re-queueing to future production wiring.
- 05_building_block_view.adoc: trailing SHACL-revalidation paragraph
rewritten to drop the resume-sweep mention and disclose dormancy.
|
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-AU] Document schema-module admin toggles in the architecture chapters
🚀 Summary
Documents the schema-module admin toggles shipped on
federated-cataloguePR #54. The central artefact is ADR 16, which establishes the asymmetric four-toggle semantics: SHACL / JSON Schema / XML Schema gate their validators (400 module_disabled:<MODULE>when off); OWL gates the third tier of role resolution and rejects credentials whose type is reachable only through a runtime-uploaded ontology. The other chapter edits thread that decision through the places that previously hedged or contradicted it.🧩 Chapter coverage
09_architecture_decisions.adoc— new ADR 16. Frames the two semantic classes (validators vs. OWL gating role resolution) and pins the consequences: independence from the caller'sverifySchema/verifySemantics; SHACL toggle additionally gates the periodic revalidation sweep (sweep itself dormant in the default deployment, gate pre-positioned, resume-on-enable deferred); on-demand validation returns400both formodule_disabledand for the broader "no module enabled or applicable" case, with 422 reserved for not-validatable inputs.05_building_block_view.adoc— Admin API and runtime-component tables updated for the wired OWL toggle and themodule_disabled:<MODULE>contract; new NOTE on theverifySchema× SHACL-toggle layering; new "Schema-module admin toggles" subsection introducingOntologyImpactService,GET /admin/schema-validation/ontologies, theparseError/noActiveBundlesflags and the per-root 2 s SPARQL timeout, plus a closing paragraph on the SHACL revalidation gate and the sweep's dormancy.08_concepts.adoc— new "Type Dispatch and the OWL Toggle" entry: the three-tier resolver and the framing that the OWL toggle controls whether the catalogue admits runtime extensions to its registered type vocabulary, not whether a validator runs.04_solution_strategy.adoc— corrects the prior "non-RDF schemas stored but not used for validation" claim and links to ADR 16.07_deployment_view.adoc— new "Runtime Admin Configuration" subsection covering theadmin_configlayer (schema.module.<MODULE>.enabled,trust_frameworks.enabled) and the start-upverifySchemavs. admin-toggle relationship.12_glossary.adoc— adds Schema Module, OWL Module Toggle, Subclass Walk, Composite Ontology.🔗 Related
CAT-FR-AU-01. Companion PR:
federated-cataloguePR #54 (feature/CAT-FR-AU-Schema-activations).