Guide: Creating a new OpenActive Vocabulary

An OpenActive Vocabulary consists of a specific instance of the skos-vocabulary-editor Heroku App, paired with a specific GitHub repository based on the skos-vocabulary-template.

Note that much of the configuration is driven by convention, so the identifier must be used consistently throughout.

1. Choose an identifier for this new vocabulary (e.g. "activity-list").

   • Note that the vocabulary name should follow the same "-list" naming convention - e.g. "facility-type-list", "facility-attribute-list", "place-type-list", etc.

   • (Some existing vocabularies do not follow this convention)

2. Use the skos-vocabulary-template as a template to create a new repository with a name that exactly matches the identifier.

   • Update the README.md by removing the top section, and adapting the content for the new vocabulary.

3. Enable GitHub Pages in this new repository

   1. Ensure the "Build and deployment" "Source" is "GitHub Actions", in the GitHub Pages section

   2. Do not set a Custom domain (it will default to "https://openactive.io/<repository-name>", where the repository name is also the identifier as per the previous step)

4. Edit the PUBLIC_REPO_ACCESS_TOKEN secret within "Secrets and variables -> Actions" in the Settings of the openactive GitHub Organisation to include this new repository

   
5. Add a branch protection rule to the main branch of the repository, which includes the following rule:

   
6. Ensure that "Auto-merge" is enabled on the repository

7. Ensure that "Automatically delete head branches" is enabled on the repository

8. Edit the VOCAB_WORKFLOW_GH_ACCESS_TOKEN GitHub Fine-grained Personal Access Token of the openactive-bot GitHub account to include this new repository

   
9. Deploy a new instance of the skos-vocabulary-editor (iQvoc)

   • Click this button:

   • Name the Heroku app "oa-voc-<identifier>", e.g. "oa-voc-activity-list"

   • Ensure the region chosen is "Europe"

   • Add the app to the "skos-vocabulary-editors" Heroku pipeline, in the "Production" stage

   • Use the new vocabulary identifier chosen in Step 1 for the value of VOCAB_IDENTIFIER

   • Copy the value of VOCAB_WORKFLOW_GH_ACCESS_TOKEN from the Config Var in the skos-vocabulary-editor-staging app.

   • Ensure the VOCAB_NAME, VOCAB_DESCRIPTION, VOCAB_PROPERTY, VOCAB_DRAFT, VOCAB_EXPORT_RELATED_MATCHES, VOCAB_HELP_URL and VOCAB_SUGGESTIONS_LINK values are updated to be specific to this new vocabulary.

     • VOCAB_NAME is the name of the vocabulary, and should be of the form "X List".

     • VOCAB_PROPERTY is the name of the property in the OpenActive Namespace or Beta Namespace that references this SKOS vocabulary, e.g. "activity" or "beta:placeType".

     • VOCAB_DRAFT should be set to true if the property is in the Beta Namespace,

     • VOCAB_EXPORT_RELATED_MATCHES is a list other OpenActive vocabularies that this vocabulary references, with the name of the JSON-LD property to use when exporting such references. Leave this blank if this vocabulary does not reference other vocabularies.

       • For example:

         facility-types:facilityType;activity-list:activity

10. Add a Heroku custom domain for this new instance with an OpenActive subdomain that exactly matches the identifier (i.e. <identifier>.openactive.io e.g. activity-list.openactive.io for the identifier activity-list)

    • Follow Guide: Adding a custom domain to a Heroku App

11. If this vocabulary references other vocabularies:

    • Log into iQvoc

    • Click on "Configuration" in the top right menu

    • Under Federation, Sources (iQvoc) should be a comma-separated list of base URLs of the iQvoc instances of the other OpenActive vocabularies that this vocabulary references

12. Update the JSON-LD Reverse Proxy to ensure that the JSON-LD references to the vocabulary resolve

    1. Create a new PR to add the new vocabulary to the jsonLdUrlMap in this file and the routes array in this file, copying the example of the activity-list and updating the identifier accordingly. An example PR can be found here.

    2. Merge the PR to the master branch, and the GitHub Action will automatically deploy to Cloudflare.