UK Cross-Government Metadata Exchange Model

A metadata model for describing data assets for exchanging between UK government organisations.

This repository uses:

• LinkML: YAML specification of the metadata model which can be translated into JSON-Schema and SHACL, as well as having documentation generated
• MkDocs Tech Docs Template: GOV.UK styling for the MkDocs Material theme for service MkDocs technical documentation

Website

The website is automatically deployed when a new commit is made to the main branch using the .github/workflows/deploy-docs.yaml action. The website is available from:

https://co-cddo.github.io/ukgov-metadata-exchange-model/

Documentation site

The documentation site is hosted as a github pages site. See repo configuration for details.

The layout of pages have been overridden from the base jinja templates provided by LinkML. This is to allow renaming of pages elements, e.g. slots are displayed as properties, and for customising where elements appear on the page. The custom jinja templates can be found in src/docs/templates.

The Usage Notes section of a property page is generated from the comments: property. The rendering relies on structure of the comments property as shown below.

comments: |
      purpose:
      distinctFrom:
      guidance:

Repository Structure

Key directories and files are highlighted here:

• project/ - project files (do not edit these)
• src/ - source files (edit these)
  • data/ - example data by class with subfolders for valid and invalid examples
  • docs/ - static documentation files and assets to be included in the generated documentation site
  • model - LinkML specification of the metadata model – edit these files
• mkdocs.yml - MkDocs configuration file

Developer Documentation

To initialise your environment run

make install

To update the dependencies in your environment run

make update

To generate the schemas in different constraint languages and run the tests run

make test

To generate and serve the documentation locally run

make serve

⚠️ Note: Documentation will not be generated correctly on macOS due to the use of entity names only differing by case, e.g. the class Distribution and the property distribution. In this case, you can use Docker to build and serve the documentation

make docker-serve

To discover what other targets are available run

make help

Dependabot updates

Do not blindly accept these pull requests!

The following process should be followed to ensure that everything is working as expected.

1. Switch to the pull request branch
2. Run make clean
3. Review the pull request details to see if the updated library is one that is listed in pyproject.toml. If it is then update the file.
4. Run make update. This will change the poetry.lock file
5. Run make test serve and inspect the generated site
6. If everything has built correctly then commit your changes and accept the pull request