Lets talk about Tooling

Hi all,

I just want to bring attention to this doc OR Tooling Requirements that David and I have been working on.

This builds on the work undertaken on tooling previously such as OR tools but accounts for the current context and work undertaken since that list was put together. We will update and link back around to that spreadsheet once we’ve gotten feedback.

Workgroup - We would love to hear your thoughts on this when we meet later today (if we have time), if not, we will set up an additional, tooling-specific meeting next month.

Anyone beyond the workgroup - Feedback/comments also welcome.

Thanks,

Dan

1 Like

Hi. I received a request from the community for an improvement to our ERD diagrams showing 1-1 or 1-many relationships. Where would be the best place to post such a request?

Thanks @devin,

Here in the technical section is as good place as any request such things. I will discuss this with @mrshll and @davidraznick and post an update here.

Dan

Hi @devin,

Our preference is that we address this issue with guidance because the Schema Reference page should be treated as the SSOT for understanding the HSDS models.

The ERD diagrams are generated automatically by some code which runs over the HSDS schema (actually the datapackage serialization), so while we could theoretically add labels for 1:1, 1:n, etc. to the diagram; doing so would be likely be quite costly in terms of time for only a minor benefit at this stage.

We believe that it’s more effective to tighten up the documentation surrounding the Logical Model page, as it seems best placed to provide a sort of “birds-eye” view of the HSDS models. We’re therefore going to be working on this as part of some upcoming documentation changes to tidy everything up and bring it all in alignment with 3.0.

This is what we’re planning to do in relation to this issue:

  • Clarify (on the Logical Model page) that the 1:1 and 1:many relationships are documented as part of the Schema Reference page, wherever an “array[object]” appears.
  • Adjust the table currently on the logical model page and replace the “X” with an explicit label saying whether the foreign keys are 1:1 or 1:n, and in which direction.

We think this will balance making sure that people use the Schema Reference page appropriately, while acknowledging the need that the Logical Model page and the ERD fulfill a supporting role by presenting an overview of how the different schemas interact with each other in 3.0, especially for people coming at this from a HSDS 2.x perspective.

We encourage you and others in the community to continue to participate by letting us know your thoughts here, and reviewing the changes when they’re staged as a PR :slightly_smiling_face:

Makes sense. Sounds good. Thanks.

1 Like