Issue 115 235 formating documentation

[madanucd]

Closes #115 and #235

[madanucd]

Detailed Updates

Schema Consolidation

• Previously, the schema was split across multiple files:
  • include_schema.yaml
  • include_core.yaml
  • include_study.yaml
  • include_participant.yaml
  • include_assay.yaml
• While modularization can be beneficial, the current model is not large enough to require separate files.
• These have been consolidated into a single file: include_schema.yaml, simplifying management without modifying any structural definitions.

Schema Changes

Class-Level Updates

• Thing Removed: This high-level class was unused and has been taken out.
• Annotations Removed: All annotations have been removed from classes.

Slot-Level Changes

• To better establish relationships between classes, some slots have been explicitly defined as referential using slot_usage:
  • studyCode → Referenced in Participant, Condition, Biospecimen, DataFile, Dataset, and DatasetManifest.
  • participantGlobalId → Referenced in Condition, Biospecimen, and DataFile.
  • eventId → Usage not fully defined; consider adding specific references.
  • sampleGlobalId → Referenced in DataFile and DatasetManifest.
  • fileGlobalId → Referenced in DatasetManifest.
  • datasetGlobalId → Usage not fully defined; consider adding specific references.
• Referential slots help in generating the ER diagram, making relationships between entities more explicit and improving visualization.

Enum-Level Changes

• text Element Removed: The text element has been removed from all permissible values in enums.

No Other Changes to Schema

• No syntactic formatting adjustments have been made.
• No additional elements were removed aside from annotations in classes and text in permissible values.

Updated Documentation

• The workflow now includes generating the ER diagram as part of the process defined in deploy-docs.yaml.
• The generated file, erdiagram.md, will be placed under the src/docs/ folder.
• The mkdocs.yml file will be updated accordingly to reflect the changes.

[lopierra]

@madanucd Thanks for the super helpful update details!

Could we move the "Slot usage" comments to the start of the slots section in include_schema.yaml instead of at the end? So that comments section would start at line 267.

Otherwise, it looks good to me. @JamedFV are we still waiting for comments/questions from the FHIR team, or are you ready to merge this?

[JamedFV]

@lopierra @madanucd The team has not had a chance to review this yet (we have some project deadlines we are heads down on), but I will follow up with the team.

[RobertJCarroll]

The detailed explanation is very helpful, thanks. One outstanding question is linting- it looks like from the details that the model hasn't been changed in a way that would support the default linter config. Is that something we are targeting, or are there plans for a linter config that aligns with our conventions?

[madanucd]

Thank you for all the feedback and updates! I'm glad the explanation was helpful.

@RobertJCarroll Regarding the linting, you're right in noting that the model hasn't yet been adjusted to fully align with the default linter configuration. We are aware of the need for consistency with linting standards, including the canonical approaches recommended by LinkML. Specifically:

• Missing Descriptions: Some slots and enums are missing descriptions, which should be added for consistency and clarity.
• Naming Convention: Slot and enum names should follow the snake_case convention for consistency.
• Ontology Prefixes: Ontology prefixes should be uppercase with an underscore at the end (e.g., MONDO_). This is the recommended canonical format.

At this stage, we're not targeting a complete update to the default linter config for this iteration, as some changes may require significant updates to the schema. We are excluding these updates from the current iteration. However, we plan to incorporate them in future iterations to better align with the linter config and our conventions.

Let me know if you have any further questions or concerns!

[madanucd]

@madanucd Thanks for the super helpful update details!

Could we move the "Slot usage" comments to the start of the slots section in include_schema.yaml instead of at the end? So that comments section would start at line 267.

Otherwise, it looks good to me. @JamedFV are we still waiting for comments/questions from the FHIR team, or are you ready to merge this?

@lopierra Slot usage overview section is moved to top as requested.