HSDS Go Types and Constructors

Technical
1

I’ve developed a type system and constructors in Go for working with HSDS (Human Services Data Specification) data. This implementation makes it easy for organizations to transform their existing data into HSDS-compliant formats using Go’s high-performance capabilities.

Key Features

The system provides a standardized way to map various data sources to the HSDS API schema using Go. It includes:

  • Type definitions aligned with HSDS specifications
  • Constructor functions for creating valid HSDS objects
  • GORM compatibility for simplified SQL interactions

Usage Example

Here’s a practical example showing how to map legacy hospital service data to HSDS:

func mapLegacyHospitalService(legacyService LegacyHospitalService) (*Service, *Schedule, error) {
   // Create service
   svcOpts := &ServiceOptions{
       Description: &legacyService.Description,
   }
   svc, err := NewService(hospitalOrgID, legacyService.Title, ServiceStatusActive, svcOpts)
   if err != nil {
       return nil, nil, err
   }
   // Create schedule
   schedOpts := &ScheduleOptions{
       ServiceID: &svc.ID,
       DTStart: &legacyService.StartTime,
       ValidTo: &legacyService.EndTime,
       Freq: (*ScheduleFreqEnum)(&legacyService.Frequency),
   }
   sched, err := NewSchedule(schedOpts)
   if err != nil {
       return nil, nil, err
   }
   return svc, sched, nil
}

This code demonstrates how organizations can easily map their existing data structures to the HSDS schema using the provided constructors.

Use this Code

You can add this to your Go project with:

go get github.com/david-botos/hsds-types/

I am not certain I did this the right way, I have never made a go package, but the code is in that repo.

I’ve opened a GitHub issue to propose adding this to the HSDS repository: https://github.com/openreferral/specification/issues/536

This would allow other developers to leverage these tools when their organizations need to share or consume HSDS data.

2

Hello Cheeto

This is potentially very useful. Please forgive me if I ask dumb questions because I am no longer a programmer but want to see if your code might help other users. I’m not currently aware of people using Go.

Here in the UK some databases modelled around the standard closely match the database structure given in the entity relation diagram. Older databases and ones that serve many purposes have different structures so mapping to the HSDS structure is important in achieving API endpoints that match the specification given in our Swagger page.

Does your approach help achieve this and would you recommend it even to people new to Go?

3

Mike,

Wow sweet, that swagger page has taxonomies which have confused me. I’ll hit that endpoint and will be looking more into that. Interesting and thank you a ton for sharing… helps a lot as I pick up on this stuff :smiley:

Yes, I am using it actively as I am transforming data from my inference format to the HSDS format. Let me explain:

TLDR: Yes, a robust type system would significantly help any effort to break down silos and bring data from different formats to the HSDS format. It improves the data health, development speed, and the developer experience. Types make coding fun and easier for new developers to pick up ESPECIALLY in Go because GoPls is SUCH a good VSCode extension that with robust types, it should provide you incredible autocompletion on many methods ʕ•ᴥ•ʔ

For BearHug, the intention is to use LLM inference to turn unstructured strings (like call transcripts) into structured data. The format the LLM prefers when extracting structured data is not often the same structure as HSDS as foreign key relationships linking multiple tables is complicated and random, there is no logic to the naming of the uuid, but the key must be precise — you can see how this would be a situation ripe for LLM hallucination, and broken data.

So, to aid in this mapping experience from inference type to HSDS, this package seriously helps. Since mapping legacy data structures to HSDS is a roadblock to the overall advancement of HSDS and better data in social services, I thought the community might benefit from this package or at least the pattern, which can be copied and translated to whatever language your heart desires.

While I understand not many people may be writing their APIs in Go right now, I just wanted to share this type system that I am maintaining, updating, and improving for BearHug. BearHug is written primarily in Go, with some C# that I might want to replace later with Go. I really like the language, especially its performance, syntax, and concurrency pattern.

I could write similar type systems for TypeScript or Python, if it would seriously help a lot of people, but since I won’t be actively utilizing and dog fooding it, I don’t expect I could support them single handedly nearly as well, even if the pattern is useful.

For example, just today I took improvements I made to the HSDS Go type system for my own project and published them to the public package.

Cheeto

1 Like