Add SOP0013 for FDP submission metadata validation - #72
Conversation
|
Similar to the other PR @hcvdwerf - change the target branch to |
…eps-for-dcat-and-beacon
M-casado
left a comment
M-casado
left a comment
There was a problem hiding this comment.
Good draft again, @hcvdwerf. See comments in line and below:
- Similarly to the other PR, I would recommend format changes to ease the reading and be explicit with the "what step comes after this one".
- Even as a node-specific template, it seems a bit too generic operationally. For example, what FDP instance is covered, references to documentation, like the SHACLs (even as an example in a node), more details on how to review the outcome of the validation, where the outcomes may be logged (or why).
- The current rule is basically "if validation fails, correct and save again until it passes". There is no escalation path, no ownership for persistent failures, no distinction between content errors and validator/configuration errors, and no stopping rule for cases that cannot be resolved immediately (or if there's an error in the SHACL shapes, for example).
- Similarly, to be more explicit, there should be clear references to not just GH repositories, but tags/releases if available. For example, when referencing the general GDI metadata repository.
- I'm missing references, if any, to how this SOP may interact with the other "future" SOPs on validation against GDI HDM and Beacon. Even as placeholders.
- I would also add a comment in the original GH issue https://github.com/GenomicDataInfrastructure/GDI-Pillar-2/issues/68 regarding what is covered by this SOP.
- I would add in the introduction a clear distinction between what the FDP metadata model (the nodes' SHACL shapes) and the GDI HDM. These should not be confused, and I'm sure they are based on the original request. It should explicitly say that being FDP-compliant doesn't mean overall GDI HDM-compliant.
- Are we relying on individual FDP validation at each GDI node? When this information is harvested by the central portal, how will that validation happen? If GDI nodes have different SHACL shapes, how will they be harmonised? I think @brunopacheco1 originally was requesting catalogue-level validation as well.
- The title of the SOP must be changed to its specific scope.
|
Addressed the current review feedback in Main updates:
I also added a scope clarification comment to GDI-Pillar-2 issue 68. |
|
Added Oriol as well, as his SOP will have to do with metadata validation as well. |
costero-e
left a comment
costero-e
left a comment
There was a problem hiding this comment.
Generally, the PR makes total sense to me on the different steps to follow for a metadata validation. 👍 The only thing I see is the difference between a new submission or a submission for an update, which is slightly different for beacon and I was wondering if FDP handles it exactly the same. At least, for the logs/audit, it should be different.
| | :-------------- | :----------------------------------------------------------------------------------- | :-------------------------------------- | | ||
| | `2` | After step 1, when the metadata record is ready to be entered or updated in the FDP. | Node metadata curator or FDP maintainer | | ||
|
|
||
| Enter or update the metadata directly in the node's FDP. Follow the node's FDP operating instructions, for example `<Node FDP operational documentation>`, and ensure the record is created under the intended FDP resource type and deployed shape set. |
There was a problem hiding this comment.
I think it's important to distinguish between enter and update. And for update, is relevant to know if it's a PATCH or a PUT that will be performed. At least, for beacon, depending on the partial or complete update of information, the operation might be slightly different. I don't know how FDP works on that regard, but I guess that if the information is stored in a database, the kind of operation to perform will also be relevant.
There was a problem hiding this comment.
Good point. For the FDP side, the reference client distinguishes the two operations: create uses POST, while update uses PUT for the full entity update. I kept the SOP at the workflow level rather than documenting HTTP semantics in the step text, but for FDP specifically the update path is PUT, not PATCH. The Beacon-specific distinction is out of scope for this SOP.
| | :-------------- | :----------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- | | ||
| | `6` | After step 3, when the FDP validation output passes without unresolved local validator, schema, or configuration issues. | FDP maintainer or node metadata curator | | ||
|
|
||
| When validation succeeds, the record can be treated as harvestable by the central node. This SOP ends at that point; the downstream central harvesting workflow remains outside its scope and should be defined in a future GDI harvesting specification or SOP. |
There was a problem hiding this comment.
Linked to the previous comment about enter/update, maybe it is relevant here to know the type of operation to perform in the database.
There was a problem hiding this comment.
Yes, for FDP that is the relevant distinction here. The reference implementation persists updates through a PUT on the entity, so the SOP should be read as covering create via POST and update via PUT in the FDP workflow.
|
After my initial review and comments I'll leave it here without doing a second round. It'll be in the hands of the approvers whether the SOP is ready be merged or not. |
|
Just to confirm @hcvdwerf, would you say the SOP can be considered reviewed (i.e., feedback is addressed) and can go into the next step (approval by OC/SDPC)? |
yes please! |
|
OC & SDPC have been notified |
|
As a reviewer from the OC I need to clarify the scope and relationship to other SOPs before approving. My concern here is that this is just in effect describing the process entering data in to an FDP (ie. reference implementation), but not specifically the validation where a node chooses to generate their own file against a SHACL validator, and also the validation of the metadata itself beyond conformance with the SHACL. The SOP mentions that it does not deal with validation against the HDM - maybe this should be the scope of this SOP with the SHACL validation part of the process (this is implied by the title of FDP submission metadata validation)? If not I suggest the title of the SOP should be changed to something like 'SHACL validation of FDP metadata'. |
|
As a reviewer from the SDPC, I would also like to clarify if different nodes can have different SHACL shapes and that there is not standard SHACL shape required central for the harvesting to work? I would also reiterate @jdylan request for clarification of scope and possible title change for clarity. |
|
@jdylan @waakanni I have clarified this in On scope: this SOP should be read narrowly as the node-level FDP workflow for entering or updating dataset metadata in the FDP, reviewing the save-time SHACL validation returned there, correcting metadata content issues, and handling local escalation when the validator or configuration is at fault. It is not intended to cover full HDM validation, broader metadata quality assessment beyond SHACL conformance, or the downstream central harvesting validation logic. On SHACL harmonization: nodes do not necessarily need identical SHACL files. What matters is that their deployed node-level shapes conform to the central GDI SHACL constraints expected for interoperable harvesting. I have now made that distinction explicit in the SOP so local node variation is separated from the central interoperability requirements. I have kept the current title for now and tightened the Purpose, Scope, and Introduction text accordingly. |
waakanni
left a comment
waakanni
left a comment
There was a problem hiding this comment.
As an approval from SDPC, I am satisfied with the current version.
|
Current status: pending review from the OC |
costero-e
left a comment
costero-e
left a comment
There was a problem hiding this comment.
I'm not going to lie, I'm not a user for FDP (can't help with the specific things), but I think the SOP makes sense overall so I approve it. Only thing I didn't see, is what the SHACL source of validation is. Are the definitions needed to be extracted from this repo? For me is not that obvious, maybe just clarifying it would be good, but I'm just a newbie external reader (maybe the users that read this SOP already have this knowledge and is not needed for the purpose of the SOP).
|
@jdylan, you requested changes to this SOP back in May. Could you please check that you are now happy with the new version & approve for the OC if it's ok? |
|
Approved from my side |
# Conflicts: # sops/README.md # sops/european-level/GDI-SOP0009_dataset-withdrawal.md
6 participants
Summary
GDI-SOP0013_submission-metadata-validation.md..docxdraft into repository-compliant Markdown and align it with the SOP template, style guide, and glossary rules.Types of changes
Motivation and Context
This branch adds a node-specific SOP template for FAIR Data Point submission metadata validation. The content comes from the reviewed draft
20260305-GDI-SOP_draft-Submission Metadata Validation.docx, converted into the repository Markdown structure and normalized into a reusable template.The current SOP scope is intentionally FDP-only. It documents save-triggered SHACL validation in the FAIR Data Point as the operational validation step and keeps the required-field definition anchored in the deployed SHACL shapes and referenced specifications.
References
Changes Introduced
sops/node-specific/GDI-SOP0013_submission-metadata-validation.mdsops/README.mdwith the SOP0013 index entrydocs/GDI-SOP_charter.mdglossary withDCAT,FAIR,FDP, andSHACLCHANGELOG.mdunderUnreleasedReview
The SOP content is based on the reviewed
.docxdraft and the later FDP-only clarification for the procedure scope. Additional review from Task 4.3 / SOP maintainers is still welcome before merge.Additional Notes
scripts/sop_linter.pyis not worktree-safe because it looks specifically for a.gitdirectory; I therefore ran the linter against a temporary full-copy validation tree with the same file contents. The linter completed with no errors and only the expected warnings for emptyGDI NodeandInstance versionfields in a node-specific template.Checklist:
General Compliance:
Only applicable if the PR includes new, or changes to, GDI SOPs (i.e., documents at
sops/):