HSDS 3.0 - What is "compliance"?

Technical
1

This topic flows from recent HSDS Workgroup meetings, as well as the topic for “HSDS 3.0 - Key Decisions” HSDS 3.0 - Key Decisions - #9 by skyleryoung

I looked around for duplicates, and while this topic is alluded to in a few places, it appears we don’t have a dedicated thread to settle the issue. So here we go.

First, I’d like to vet an assumption in writing: at the last HSDS Workgroup meeting we decided that defining compliance is not a blocking issue for release of 3.0. We’ll release and then keep working to define that topic. Does anyone have a different understanding?

Next, we have discussed a couple of scenarios for “compliance” that stood out to me:

Compliance Version 1

Compliance encompasses both Data Packages and APIs. Levels of compliance might look something like this:

  1. “Compatible”/Minimum: The publisher is providing CSVs in the Data Package format.
  2. Standard: The publisher is providing Service level data via HSDA specifications.
  3. Full: The publisher is providing all core data via HSDA specifications.
    (For more info on 2 and 3, see “HSDS 3.0 - Key Decisions” referenced above.)

Compliance Version 2

This version is the same as Version 1, but without the first “Data Package” option included. The reasoning is to force conversations with enterprise organizations into the API domain without leaving wiggle room to avoid it. However, community guidelines should be vocal about allowing use of data packages for small, temporary, or poor organizations, and also provide tooling to improve interoperability between data packages and APIs.

Compliance Version 3

There are no set standards for compliance, and instead we publish use-case specific compliance standards in much the same way we anticipate publishing Application Profiles. This option is non-exclusive, and may be used to extend or refine default standards as defined above.

This list of compliance options is non-exhaustive and meant to be a starting point for discussion. What are your thoughts/ideas/assumptions for compliance?

@bloom @MikeThacker @devin @davidraznick @robredpath

2

Thanks for kicking off this discussion space, Skyler.

Here’s a quick summary of the longer post below:

  • The published HSDS3 standard doesn’t need to address these issues at this point.
  • We should work to upgrade our tools to HSDS3 and make them compatible with each other.
  • We should define data management and sharing guidelines and create a mechanism to validate whether groups who claim to comply with them actually do.

Okay, now to the longer post. :slight_smile:

What does HSDS3 say about compliance? IMO at this point it shouldn’t say anything. But it should publish the format for (1) the datapackage, (2) the minimum API and the (3) full API.

Open Referral Global, as the project/organization that publishes and maintains HSDS3, should offer official tools that, validate the datapackage, and API formats that it published. Vendors who make software that produces successful validation can claim they do so.

That, to me, is the core standard/validation solution that Open Referral Global should offer.

But there is so much more we want to do with the data!

  • ORUK has produced a set of tools that work together to generate lots of value.
  • Skyler’s group has put together a lovely front end interface and is working on other data pipeline and merging tooliong.
  • My group has put together some data display/creation/admin and API tools. We want all these to work together to make everyone’s life easier! So this, to me, is where “compatibility” fits in.

IMO these tools constitute the HSDS3 Ecosystem that operates under a logic of compatibility.

Naturally, once HSDS3 comes out, we’ll all be able to upgrade our tooling to it, and in doing so, make it possible to integrate out tools together to create a valuable ecosystem.

Here’s how I imagine my tools get connected to the ecosystem:

  • First, we create an HSDS3 datapackage export for our ORServices application.
  • Then, we create/assist/encourage/whatever a reference implementation of the full HSDS3 API.
  • Finally, we create/assist/encourage/whatever a tool that imports a datapackage into the API.

At that point we’d have all the tools we need to take ORServices data and publish it via HSDS3 API, and thus, connect it to the ecosystem of compatible HSDS tools.

I’d hope that Skyler’s lovely Connect211 front-end interface would also be compatiblen with the HSDS3 API so that someone could easily move data from ORServices into the HSDS3 API and display it via a Connect211 instance.

Similarly, I’d hope that I can register my HSDS3 API with the ORUK connector tool and then use their query, exporter, aggregator, validator tools.

As such, I’d want to describe my ORServices software application as compatible with the HSDS3 Ecosystem, and since that ecosystem offers so much value, I think other solution providers will want to say the same thing about their software.

Compliance, I think, goes beyond the technical question of compatibility and into some as-yet undefined rules/guidance around producing and sharing services data.

For example: for an API to be in compliance with (a theoretical) Open Referral Data Guidelines, the data must be:

  • available to the public at a compatible endpoint
  • must be assured/verified within the last year
  • must have a richness score over 80

Maybe there are core guidelines (public) and nation specific ones (ex. maybe ORUK requires a specific taxonomy to be used)?

Thanks for reading and all this and I hope you don’t think I got carried away with my use of bold. :slight_smile:

3

On @skyleryoung’s points I thought we agreed that compliance means having the basic set of API methods (HSDA) with correct response formats. Going beyond that with the extra documents API web methods can be encouraged.

Compatible means CSVs in the Data Package format - I think the documentation should mention that second as a fallback if compliance can’t be achieved.

@devin Yes we can get on with firming up the spec before confirming what constitutes compliance and tooling but UK people now are getting public funding and/or being encouraged to produce compliant feeds. Others have it in their product development plans. Until we have anything different we test compliance with our Dashboard and associated documented rules. Although some suppliers are keen to stay up-to-date we can’t ask them to make changes late in the day.

Yes, compliance means an open public endpoint. We test nightly not annually. Richness might be left to specific profiles as different combinations of fields are important to different implementations.

4

Do you need this “compliance” language to live at the Open Referral Global/HSDS3 level or can it continue to live at the Open Referral UK level?

5

Others can say if they need it outside the UK. I just want to make sure it’s pretty prominent in the documentation, even if it says “in the UK” rather than being a footnote or in some related documents.

6

Would it make sense to reorganize this page to put your guidelines here under an Open Referral UK section? Publication Guidance — Open Referral Data Specifications 2.0.1 documentation

If not there, where at https://docs.openreferral.org/en would you like your guidelines/compliance instructions published?

7

I could be wrong about this (at @bloom correct me?), but I think that requiring a public endpoint for compliance will create governance problems in the US. A number of “data steward” organizations gate access to their data in order to prevent bad actors from stealing it, and also to ensure they get funding to maintain it. In many cases there isn’t assigned funding to maintain a community data base. This is why Connect 211’s APIs aren’t open. We are forcing our clients to adopt HSDS in order to promote interoperability and (hopefully) compliance, but at the end of the day they own their own data, and we of course can’t just turn it loose without their permission.

8

@devin I guess that, ideally, I’d like an entry in the contents list (on the left) linking to “Compliance” or “UK compliance”.

On @skyleryoung’s point, we also get objections or reluctance in the UK to an API feed being open. I push back saying:

  • normally its a public body paying for the data to be gathered even if that’s not explicit in an agreement for funded services
  • the data is usually open anyway even if it has to be gleaned by scraping a website

If openness is too much of a hurdle outside the UK this requirement might need to be UK-specific. I wouldn’t want to lose it.

9

Great points @MikeThacker, thanks. Funding is all over the place, but scraping is particularly salient. I’ll start having that conversation with clients and see how they receive it. Should be interesting.

1 Like
10

@MikeThacker, a “UK Compliance” page under the “HSDS Implementation Guidance” heading on the left side menu seems like the best solution to me.

I think you should write up that page and propose its inclusion.

11

Right. I’ll draft something when we have the core API methods agreed. @davidraznick and @Dan-ODS please let me know if you need it sooner or if you’d recommend a different approach.

12

Sorry to over-simplify but would I be right to deduce the following from the above posts:

There are factors and dynamics unique to the US ecosystem that mean moving towards the terms ‘Compliant’ and ‘Compatible’ would be problematic at this point in time. And whilst there is agreement on this as the direction of travel, conversations with key stakeholders and perhaps the provision of toolling are required to smooth the transition?

Whereas due to factors and dynamics unique to the UK ecosystem (i.e. provision of funding based on ‘compliance’ and availability of tooling) a move towards the terms ‘Compliance’ and ‘Compatibility’ sooner rather than later would be preferable?

As such, there is a suggestion to create the documentation in way that distinguishes UK form the US in this regard?

Although this divergence would in theory be temporary in nature - are there implications we’d need to consider first?

Thoughts @bloom @davidraznick?

13

@Dan-ODS That is my understanding and Open Referral UK already have a 'Compliance` model.

My main concern about not using terms like Compliance and Compatibility is how we frame the documentation for 3.0.

It is difficult for the documentation to remain completely neutral and just specify publication options and not specify any recomendation on how to use any of them.

We could just say that we “recommend”, APIs over Datapackages, for example, but that does not feel like strong enough language. I would prefer if we just said that publishing datapackages were “deprecated” but maybe that is too strongly worded.

On top of this, I think the documation needs reframing, to move the API approach into the “Human Services Data Spec” top section, replacing the “Formats and Packaging” section. The datapackage option could then be moved to where HSDA is now and expressed as an “alternate”/“deprecated” or “non recommended” option. Ideally we would also have examples of the produced JSON througout the whole of the “HSDS Reference” section.

I feel the documentation needs to push people to the “API” approach even if we do no explicitely use the terms “complience” (with the exception of OR-UK of course).

14

Which is the latest version of the 3.0 docs? This one? About — Open Referral Data Specifications 2.0.1 documentation

What’s the best way for us to comment on the final docs? Do we want to have a Google Doc so we can use its comments/suggestions feature to get specific on language and structure?

As for the API part, I think it should be in the Human Services Data Spec section, maybe placed under the “Logical Model”.

15

Yes that’s the one @devin. Just have to ensure 3.0-dev-update is selected bottom left which judging by the link you’ve sent you’ve figured out.

I believe @davidraznick plans to update the various sections within the ‘HUMAN SERVICES DATA SPEC’ to make it API focused - including that one.

I’m not sure whether there’s a G Doc and the mechanism for making comments but will check with David and get back to you.

I do have an update/proposal drafted summarising what we agreed and next steps based on the last meeting which I’ve had to adjust based on the conversations in this thread.

That will be posted after xmas now though.

@MikeThacker that summary/proposal should cover off your query to David and I yesterday once it’s finilaised.

Have a great Xmas all!

Dan

1 Like
16

This is a wonderful conversation. Thanks, all.

I think that the most important thing that we can do to ensure that implementers use the API spec is to make sure that the documentation is entirely API-centric. This is in line with our proposal for HSDS 3.0 anyway - if we’re moving to being an API-first spec then we’ll want to change the language throughout the documentation, change the examples, and ensure that the whole experience of someone starting to use the standard is API-first. That way, we’re removing the perception of choice: this is an API specification; you don’t need to choose formats.

We’re going to need some amount of UK-specific documentation: this can be lightweight and avoid duplication wherever possible, but we can make it clear that Open Referral UK is a particular additional set of rules on top of Open Referral.

We can further have a section that describes the datapackage (CSV) format and the circumstances under which someone might want to use it. We can be clear in that section that this isn’t compliant OR-UK. Similarly, when we address licensing, we can make it clear that OR-UK imposes additional restrictions over and above OR’s in order to be compliant.

In other standards we try to avoid the word “compliant” for fear of either putting people off, or accidentally encouraging people to do the bare minimum. I don’t think those concerns apply here, so I’m more relaxed about it.

The term “compatible” has already been used to refer to software and data in this thread alone: I think that without significant discipline around how we use the term it will rapidly become confusing what it means.

1 Like
17

Hi Devin,

We’ve discussed this and think the best way to approach it would be to share Git Hub Branches with you via this forum channel as things progress. You could then feedback to us via the forum and/or within GitHub itself. How does this sound?

18

Hi Mike,

Yes we are happy to go with this approach and for you draft something. We will consider where and how present this in the documentation as we work on the upgrade. And will no doubt bring to the workgroup for discussion at some point.

Dan

19

Sounds good to me. Thank you.