New tool: the HSDS Profile Wizard

Technical
1

Hi everyone,

I’d like to announce the first release of the “HSDS Profile Wizard”. This is a CLI tool which aims to make it as easy as possible to create and manage new (and existing) HSDS Profiles in accordance with the HSDS Profiles Reference.

This joins the “HSDS Schema Tools” as the second implementation of a tool which implements the Profiles Reference, and was motivated by the following things:

  • Fixing bugs inherent in the HSDS Schema Tools’ treatment of compiling Profile Schemas (see #8 and #9) without breaking HSDS’ own build pipeline.
  • Automatic handling of schema $id fields for Profiles. Now, if we address #561 on HSDS, Profiles will be unaffected. As a bonus, Profiles using the HSDS Profile Wizard can benefit from shiny $id fields right now (get them while they’re hot!)
  • (Relatively) elegant handling of updating links to to Profile schemas inside your Profile’s openapi.json file. The tool will iterate through all the paths in your openapi.json file (after it is patched) and make sensible guesses as to which schema you want to link to. If there’s a case where an API endpoint in the Profile is linking to a schema which doesn’t exist in your Profile, it will warn you and prompt you to fix it.
  • Looking ahead to a possible Profiles registry, use of this tool will create a profile.json file containing metadata for your Profile. This is currently only used by the HSDS Profile Wizard to manage generating your Profile schemas, but in the future it would enable us to build a registry of profiles by maintaining links to various profile.json files and extracting data from them.

One important note: the HSDS Profile Wizard currently does not automatically generate a datapackage.json file for your Profile. This was deliberately omitted to keep the tool lean for now, but can be added in the future. In the meantime, you can combine the HSDS Profile Wizard with the HSDS Schema Tools to generate a datapackage.json for your Profile.