Skip to content

Entry Data Model

Each library entry lives at library/<slug>/metadata.yaml. The slug is kebab-case and must be unique across the library.

Full Field Reference

# ── Required ──────────────────────────────────────────────────────────────────

title: string
# Display name of the project or tool. Title case.

description: string
# 1–3 sentences. Plain English. What does it do, and who is it for?

category: enum
# One of: data_engineering | data_analytics | data_science |
#         data_architecture | dataops_devops | ig_security

project_type: string
# Subtype within the category. See docs/reference/categories.md for valid values.
# Examples: "Data Pipelines (Automated)", "Ad Hoc Analysis", "Simulation & Modelling"

language:
  - enum
# List. One or more of: python | r | sql | terraform | typescript |
#                        javascript | yaml | julia | other

repo_url: string
# Full GitHub URL, e.g. https://github.com/org/repo

repo_visibility: enum
# One of: public | private | internal

reusability_tier: enum
# One of: baseline | bronze | silver | gold
# See docs/reference/reusability_framework.md for what each tier means.

contact: string
# Email address or GitHub username of the maintainer.


# ── Recommended ───────────────────────────────────────────────────────────────

organisation: string
# NHS organisation or team. e.g. "NHS England Data Science", "UKHSA", "NHS Wales"

platforms:
  - string
# Free-form list of platforms/tools the code targets.
# Suggested values: databricks | azure | aws | gcp | sql-server | postgresql |
#                   oracle | power-bi | tableau | jupyter | github-actions |
#                   gitlab-ci | docker | kubernetes | nhs-login | spine

tags:
  - string
# Free-form searchable tags. Lowercase, hyphenated. Use for data types, standards,
# clinical areas, etc. e.g. nhsdd | icd-10 | snomed | waiting-lists | a-and-e |
# cancer | mental-health | primary-care | secondary-care | synthetic-data | rap

sul:
  structural: bool   # Templates, folder structures, project skeletons
  utility: bool      # Generic helper functions decoupled from project logic
  logic: bool        # Bespoke project-specific code, clearly separated
# Whether the entry demonstrates each element of the SUL principle.
# All three true = strong reuse candidate. See /about/ for the SUL explanation.

date_added: date
# ISO 8601 date, e.g. 2026-06-12. Set when the entry is first added.

last_updated: date
# ISO 8601 date. Update when the metadata or underlying repo changes significantly.


# ── Optional / Display ────────────────────────────────────────────────────────

tier_rationale: string
# 1–2 sentences explaining why this entry was assigned its tier.
# Shown on the detail page. Encouraged for Silver and Gold.

featured: bool          # default: false
# If true, the entry appears in the Featured section on the home page.
# Reserve for mature, well-documented entries that represent best practice.

success_story: bool     # default: false
# If true, the entry appears in the Success Stories section on the home page.

success_story_text: string
# Required if success_story is true. 1–2 sentences describing the measurable
# outcome or impact. e.g. "Reduced monthly reporting time from 4 hours to 15 minutes."

logo_url: string
# URL to a logo or screenshot. Shown on the entry card and detail page.
# Prefer a raw GitHub URL to an image in the repo, e.g.:
# https://raw.githubusercontent.com/org/repo/main/docs/logo.png

documentation_url: string
# URL to external documentation site, if separate from the repo.

package_url: string
# PyPI / CRAN / conda-forge URL, if the code is published as a package.

atlas_listed: bool      # default: false
# If true, this entry is also listed on the HSMA Decision Intelligence Atlas.

atlas_url: string
# Required if atlas_listed is true. Full URL to the Atlas entry.

status: enum            # default: active
# One of: active | withdrawn
# Withdrawn entries keep their YAML file in the repository as an audit trail
# but are excluded from every build output (catalogue, pages, JSON).

Category + Project Type Values

category Valid project_type values
data_engineering Data Pipelines (Automated), Ad Hoc Extractions, Data Quality & Utility Tools
data_analytics Automated Reporting Pipelines, Dashboards, Ad Hoc Analysis
data_science Exploratory Research & Model Training, Production ML Pipelines, Simulation & Modelling, AI & NLP Implementations
data_architecture Standard Infrastructure Pipelines, Ad Hoc Sandboxes, Database Schemas
dataops_devops Project Templates, CI/CD Pipelines, Docker Images
ig_security Data Masking Scripts, Audit Tools

Validation Rules

The Pydantic model in src/nrcl/models.py enforces:

  • All required fields present
  • category is one of the six valid values
  • language list is non-empty
  • repo_visibility is one of the three valid values
  • reusability_tier is one of the four valid values
  • contact is either a valid email or a GitHub username (starts with @ or no spaces)
  • success_story_text is present when success_story is true
  • atlas_url is present when atlas_listed is true
  • date_added is a valid ISO 8601 date
  • slug (the directory name) matches ^[a-z0-9-]+$
  • status, when given, is active or withdrawn

Quality score

The build derives a 0-100 quality score from these fields (src/nrcl/quality.py): description length, tags, documentation link, tier rationale, SUL declaration, recency of last_updated, platforms, organisation, repository visibility, and package link. The score is not stored in the YAML; it is recomputed on every build and shown on the entry page with the criteria met and missed.