├── standards-catalogue ├── .ruby-version ├── .rspec ├── .dockerignore ├── source │ ├── javascripts │ │ ├── application.js │ │ ├── table_sort.js │ │ ├── govuk_tech_docs.js │ │ ├── _start-modules.js │ │ ├── _modules │ │ │ ├── anchored-headings.js │ │ │ ├── navigation.js │ │ │ ├── collapsible-navigation.js │ │ │ └── in-page-navigation.js │ │ ├── modules.js │ │ ├── _govuk │ │ │ └── modules.js │ │ └── _vendor │ │ │ └── fixedsticky.js │ ├── stylesheets │ │ ├── print.css.scss │ │ ├── modules │ │ │ ├── _navbar.scss │ │ │ ├── _standards-table.scss │ │ │ ├── _status.scss │ │ │ ├── _footer.scss │ │ │ ├── _contribution-banner.scss │ │ │ ├── _header.scss │ │ │ ├── _collapsible.scss │ │ │ ├── _app-pane.scss │ │ │ ├── _anchored-heading.scss │ │ │ ├── _search.scss │ │ │ └── _technical-documentation.scss │ │ ├── screen.css.scss │ │ ├── manifest.css │ │ ├── screen-old-ie.css.scss │ │ ├── _core.scss │ │ ├── vendor │ │ │ └── _fixedsticky.scss │ │ └── _govuk_tech_docs.scss │ ├── layouts │ │ ├── layout.erb │ │ ├── taxonomy_table.erb │ │ ├── _search.erb │ │ ├── standards_table.erb │ │ ├── _footer.erb │ │ ├── core.erb │ │ └── _header.erb │ ├── favicon.ico │ ├── images │ │ ├── govuk-icn-close.png │ │ ├── govuk-icn-close@2x.png │ │ ├── anchored-heading-icon.png │ │ ├── anchored-heading-icon-2x.png │ │ ├── govuk-icn-numbered-list.png │ │ └── govuk-icn-numbered-list@2x.png │ ├── index.html.md │ └── accessibility.html.md.erb ├── .rubocop.yml ├── .git-blame-ignore-revs ├── Dockerfile ├── helpers │ ├── format_helpers.rb │ └── navigation_helpers.rb ├── bin │ └── docker_serve ├── lib │ ├── govuk_tech_docs │ │ ├── unique_identifier_extension.rb │ │ ├── tech_docs_html_renderer.rb │ │ ├── unique_identifier_generator.rb │ │ ├── meta_tags.rb │ │ └── contribution_banner.rb │ └── schemaorg.rb ├── data │ ├── statuses.yml │ ├── tags.yml │ ├── organisations.yml │ └── licences.yml ├── spec │ ├── spec_helper.rb │ └── helpers │ │ └── format_helpers_spec.rb ├── .schema │ ├── tag.json │ ├── organisation.json │ ├── licence.json │ └── standards.json ├── .gitignore ├── README.md ├── docs │ ├── deployment.md │ ├── adding_a_standard.md │ └── getting_started.md ├── package.json ├── Gemfile ├── config │ └── tech-docs.yml ├── LICENSE ├── CODE_OF_CONDUCT.md ├── config.rb ├── Rakefile └── Gemfile.lock ├── CODEOWNERS ├── content ├── taxonomies │ ├── esco │ │ ├── Taxonomy_Evaluation_Document_ESCO_FINAL.odt │ │ ├── Taxonomy_Evaluation_Document_ESCO_FINAL.pdf │ │ └── index.html.md │ ├── onet │ │ ├── Taxonomy_Evaluation_Document_ONET_FINAL.odt │ │ ├── Taxonomy_Evaluation_Document_ONET_FINAL.pdf │ │ └── index.html.md │ ├── soc │ │ ├── Taxonomy_Evaluation_Document_SOC_FINAL.odt │ │ ├── Taxonomy_Evaluation_Document_SOC_FINAL.pdf │ │ └── index.html.md │ └── index.html.md.erb ├── guidance │ ├── spreadsheets │ │ └── index.html.md │ ├── apimanagement │ │ ├── index.html.md │ │ ├── APIM-Retirement.html.md │ │ ├── APIM-Management.html.md │ │ ├── APIM-Design.html.md │ │ ├── APIM-Discovery.html.md │ │ ├── APIM-Deployment.html.md │ │ └── APIM-Introduction.html.md │ ├── index.html.md.erb │ ├── addressbase │ │ └── index.html.md │ └── apidomain │ │ └── index.html.md └── standards │ ├── external-standards.html.md │ ├── bods │ └── index.html.md │ ├── iso20022 │ └── index.html.md │ ├── digital-object-identifier │ └── index.html.md │ ├── 360giving │ └── index.html.md │ ├── algorithmic-transparency-reporting-standard │ └── index.html.md │ ├── securitytxt │ └── index.html.md │ ├── rfc4180 │ └── index.html.md │ ├── odf12 │ └── index.html.md │ ├── openreferraluk │ └── index.html.md │ ├── index.html.md.erb │ ├── UKGemini │ └── index.html.md │ └── UPRN │ └── index.html.md ├── adr ├── template.md ├── 0002-standards-static-site-configuration.md ├── 0003-make-contraction-optional.md └── 0001-standards-catalogue-data-structure.md ├── .github ├── dependabot.yml └── workflows │ ├── scorecards-analysis.yml │ └── ci.yml ├── README.md ├── SDO └── membership.md ├── projects └── data-service-standard │ └── improving-data-guidance-in-service-manual.md ├── CODE_OF_CONDUCT.md └── LICENCE.md /standards-catalogue/.ruby-version: -------------------------------------------------------------------------------- 1 | 3.2.2 2 | -------------------------------------------------------------------------------- /CODEOWNERS: -------------------------------------------------------------------------------- 1 | .github/workflows/ @co-cddo/dsa-tech 2 | -------------------------------------------------------------------------------- /standards-catalogue/.rspec: -------------------------------------------------------------------------------- 1 | --require spec_helper 2 | -------------------------------------------------------------------------------- /standards-catalogue/.dockerignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | build 3 | tmp 4 | -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/application.js: -------------------------------------------------------------------------------- 1 | //= require govuk_tech_docs 2 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/print.css.scss: -------------------------------------------------------------------------------- 1 | $is-print: true; 2 | 3 | @import "govuk_tech_docs"; 4 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_navbar.scss: -------------------------------------------------------------------------------- 1 | .navbar li { 2 | margin: 2px 15px 2px 0; 3 | } 4 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_standards-table.scss: -------------------------------------------------------------------------------- 1 | .list-of-tags { 2 | padding-left: 20px; 3 | } 4 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/screen.css.scss: -------------------------------------------------------------------------------- 1 | @import "govuk_tech_docs"; 2 | @import "tablesort/tablesort"; 3 | -------------------------------------------------------------------------------- /standards-catalogue/source/layouts/layout.erb: -------------------------------------------------------------------------------- 1 | <% 2 | wrap_layout :core do 3 | html = yield 4 | 5 | html 6 | end 7 | %> 8 | -------------------------------------------------------------------------------- /standards-catalogue/source/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/standards-catalogue/source/favicon.ico -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/table_sort.js: -------------------------------------------------------------------------------- 1 | //= require tablesort 2 | 3 | new Tablesort(document.querySelector('.js-table-sort')); 4 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/manifest.css: -------------------------------------------------------------------------------- 1 | //= link_tree ../../node_modules/govuk-frontend/govuk/assets 2 | 3 | //= require screen 4 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/screen-old-ie.css.scss: -------------------------------------------------------------------------------- 1 | $is-ie: true; 2 | $ie-version: 8; 3 | 4 | @import "govuk_tech_docs"; 5 | @import "tablesort/tablesort"; 6 | -------------------------------------------------------------------------------- /standards-catalogue/source/images/govuk-icn-close.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/standards-catalogue/source/images/govuk-icn-close.png -------------------------------------------------------------------------------- /standards-catalogue/.rubocop.yml: -------------------------------------------------------------------------------- 1 | inherit_gem: 2 | rubocop-govuk: 3 | - config/default.yml 4 | - config/rspec.yml 5 | 6 | inherit_mode: 7 | merge: 8 | - Exclude 9 | -------------------------------------------------------------------------------- /standards-catalogue/source/images/govuk-icn-close@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/standards-catalogue/source/images/govuk-icn-close@2x.png -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_status.scss: -------------------------------------------------------------------------------- 1 | .status-active { 2 | background-color: #8D5; 3 | } 4 | 5 | .status-draft { 6 | background-color: #ffdd00; 7 | } 8 | -------------------------------------------------------------------------------- /standards-catalogue/source/images/anchored-heading-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/standards-catalogue/source/images/anchored-heading-icon.png -------------------------------------------------------------------------------- /standards-catalogue/source/images/anchored-heading-icon-2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/standards-catalogue/source/images/anchored-heading-icon-2x.png -------------------------------------------------------------------------------- /standards-catalogue/source/images/govuk-icn-numbered-list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/standards-catalogue/source/images/govuk-icn-numbered-list.png -------------------------------------------------------------------------------- /standards-catalogue/.git-blame-ignore-revs: -------------------------------------------------------------------------------- 1 | # Usage: git blame --ignore-revs-file .git-blame-ignore-revs 2 | 3 | # Initial Rubocop autocorrect 4 | c2f7f38dcde3e9d1ef6a70f6847293ba4baff390 5 | -------------------------------------------------------------------------------- /standards-catalogue/source/images/govuk-icn-numbered-list@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/standards-catalogue/source/images/govuk-icn-numbered-list@2x.png -------------------------------------------------------------------------------- /content/taxonomies/esco/Taxonomy_Evaluation_Document_ESCO_FINAL.odt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/content/taxonomies/esco/Taxonomy_Evaluation_Document_ESCO_FINAL.odt -------------------------------------------------------------------------------- /content/taxonomies/esco/Taxonomy_Evaluation_Document_ESCO_FINAL.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/content/taxonomies/esco/Taxonomy_Evaluation_Document_ESCO_FINAL.pdf -------------------------------------------------------------------------------- /content/taxonomies/onet/Taxonomy_Evaluation_Document_ONET_FINAL.odt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/content/taxonomies/onet/Taxonomy_Evaluation_Document_ONET_FINAL.odt -------------------------------------------------------------------------------- /content/taxonomies/onet/Taxonomy_Evaluation_Document_ONET_FINAL.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/content/taxonomies/onet/Taxonomy_Evaluation_Document_ONET_FINAL.pdf -------------------------------------------------------------------------------- /content/taxonomies/soc/Taxonomy_Evaluation_Document_SOC_FINAL.odt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/content/taxonomies/soc/Taxonomy_Evaluation_Document_SOC_FINAL.odt -------------------------------------------------------------------------------- /content/taxonomies/soc/Taxonomy_Evaluation_Document_SOC_FINAL.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alphagov/data-standards-authority/HEAD/content/taxonomies/soc/Taxonomy_Evaluation_Document_SOC_FINAL.pdf -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/govuk_tech_docs.js: -------------------------------------------------------------------------------- 1 | //= require jquery 2 | //= require _vendor/modernizr 3 | //= require _vendor/fixedsticky 4 | //= require lodash 5 | //= require _start-modules 6 | //= require govuk-frontend/govuk/all.js 7 | 8 | $(function () { 9 | $('.fixedsticky').fixedsticky() 10 | GOVUKFrontend.initAll() 11 | }) 12 | -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/_start-modules.js: -------------------------------------------------------------------------------- 1 | //= require _govuk/modules 2 | //= require _modules/anchored-headings 3 | //= require _modules/in-page-navigation 4 | //= require _modules/navigation 5 | //= require _modules/search 6 | //= require _modules/collapsible-navigation 7 | 8 | $(document).ready(function () { 9 | GOVUK.modules.start() 10 | }) 11 | -------------------------------------------------------------------------------- /standards-catalogue/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM ruby:2.7-alpine 2 | WORKDIR /app 3 | 4 | RUN apk add --no-cache build-base nodejs sqlite-dev npm 5 | 6 | COPY package.json package-lock.json /app/ 7 | RUN npm install 8 | 9 | COPY Gemfile* /app/ 10 | RUN gem install bundler:1.17.2 && bundle install --jobs=4 --retry=3 11 | 12 | COPY . /app 13 | 14 | CMD ["bundle", "exec", "middleman", "serve"] 15 | -------------------------------------------------------------------------------- /standards-catalogue/helpers/format_helpers.rb: -------------------------------------------------------------------------------- 1 | require "redcarpet" 2 | 3 | module FormatHelpers 4 | def render_markdown(content) 5 | Redcarpet::Markdown.new(Redcarpet::Render::HTML, autolink: true) 6 | .render(content) 7 | end 8 | 9 | # Converts escaped newlines into literal newlines ("\\n" => "\n") 10 | def unescape_newlines(content) 11 | content.gsub('\n', "\n") 12 | end 13 | end 14 | -------------------------------------------------------------------------------- /standards-catalogue/bin/docker_serve: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # Builds the Docker image, and serves the site on localhost:4567 4 | 5 | # Usage: 6 | # bin/docker_serve 7 | # PORT=8080 bin/docker_serve 8 | 9 | set -euo pipefail 10 | 11 | host_port=${PORT:-0.0.0.0:4567} 12 | 13 | docker build -t alphagov/standards-catalogue:latest . 14 | docker run --rm -p "$host_port:4567" alphagov/standards-catalogue:latest 15 | -------------------------------------------------------------------------------- /standards-catalogue/lib/govuk_tech_docs/unique_identifier_extension.rb: -------------------------------------------------------------------------------- 1 | module GovukTechDocs 2 | class UniqueIdentifierExtension < Middleman::Extension 3 | def initialize(app, options_hash = {}, &block) 4 | super 5 | 6 | app.before do 7 | UniqueIdentifierGenerator.instance.reset 8 | end 9 | end 10 | end 11 | end 12 | 13 | ::Middleman::Extensions.register(:unique_identifier, GovukTechDocs::UniqueIdentifierExtension) 14 | -------------------------------------------------------------------------------- /adr/template.md: -------------------------------------------------------------------------------- 1 | --- 2 | creation_date: 1970-01-01 3 | decision_date: null 4 | status: proposed|accepted|rejected|deprecated|superseded 5 | --- 6 | 7 | # Title 8 | 9 | ## Context 10 | 11 | What is the issue that we're seeing that is motivating this decision or change? 12 | 13 | ## Decision 14 | 15 | What is the change that we're proposing and/or doing? 16 | 17 | ## Consequences 18 | 19 | What becomes easier or more difficult to do because of this change? 20 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/_core.scss: -------------------------------------------------------------------------------- 1 | @charset "utf-8"; 2 | 3 | @import "modules/anchored-heading"; 4 | @import "modules/app-pane"; 5 | @import "modules/footer"; 6 | @import "modules/header"; 7 | @import "modules/search"; 8 | @import "modules/contribution-banner"; 9 | @import "modules/technical-documentation"; 10 | @import "modules/collapsible"; 11 | @import "modules/navbar"; 12 | @import "modules/status"; 13 | @import "modules/standards-table"; 14 | -------------------------------------------------------------------------------- /content/guidance/spreadsheets/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Spreadsheets guidance 3 | weight: 860 4 | keywords: 'spreadsheets' 5 | identifier: DSA-006 6 | name: Spreadsheets 7 | organisation: Data Standards Authority 8 | status: published 9 | startDate: 2021-06-28 10 | dateAdded: 2021-06-28 11 | dateUpdated: 2021-06-28 12 | --- 13 | 14 | ## Read the guidance on [creating and sharing spreadsheets](https://www.gov.uk/guidance/creating-and-sharing-spreadsheets) on GOV.UK. 15 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_footer.scss: -------------------------------------------------------------------------------- 1 | .app-footer { 2 | padding-left: govuk-spacing(3); 3 | padding-right: govuk-spacing(3); 4 | 5 | @include govuk-media-query($from: tablet) { 6 | padding-left: govuk-spacing(6); 7 | padding-right: govuk-spacing(6); 8 | } 9 | @include govuk-media-query($from: desktop) { 10 | .govuk-footer__meta-item { 11 | max-width: 790px; 12 | max-width: 49.375rem; 13 | margin: auto; 14 | } 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /standards-catalogue/data/statuses.yml: -------------------------------------------------------------------------------- 1 | standard: 2 | endorsed: 3 | name: Endorsed 4 | styling: status-active 5 | review: 6 | name: In review 7 | styling: status-draft 8 | guidance: 9 | draft: 10 | name: Draft 11 | styling: status-draft 12 | published: 13 | name: Published 14 | styling: status-active 15 | taxonomies: 16 | endorsed: 17 | name: Endorsed 18 | styling: status-active 19 | review: 20 | name: In review 21 | styling: status-draft 22 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "npm" 4 | directory: "/standards-catalogue" 5 | schedule: 6 | interval: "daily" 7 | 8 | - package-ecosystem: "github-actions" 9 | directory: "/" 10 | schedule: 11 | interval: "daily" 12 | 13 | - package-ecosystem: "bundler" 14 | directory: "/standards-catalogue" 15 | schedule: 16 | interval: "daily" 17 | 18 | - package-ecosystem: "docker" 19 | directory: "/standards-catalogue" 20 | schedule: 21 | interval: "daily" 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Data Standards Authority 2 | 3 | # Who we are 4 | We're the Data Standards Authority team, working to improve how the public sector manages data. We're establishing standards, writing guidance and building things to make it easier and more effective to share and use data across government. 5 | 6 | You can find our web page on GOV.UK at https://www.gov.uk/government/groups/data-standards-authority, on UK Goverment Digital Slack in #data-standards-authority, or email us at data-standards-authority@digital.cabinet-office.gov.uk 7 | 8 | -------------------------------------------------------------------------------- /standards-catalogue/spec/spec_helper.rb: -------------------------------------------------------------------------------- 1 | require "factory_bot" 2 | 3 | RSpec.configure do |config| 4 | config.mock_with :rspec do |mocks| 5 | mocks.verify_partial_doubles = true 6 | end 7 | 8 | config.example_status_persistence_file_path = "spec/examples.txt" 9 | config.disable_monkey_patching! 10 | config.warnings = true 11 | 12 | config.order = :random 13 | Kernel.srand config.seed 14 | 15 | config.include FactoryBot::Syntax::Methods 16 | 17 | config.before(:suite) do 18 | FactoryBot.find_definitions 19 | end 20 | end 21 | -------------------------------------------------------------------------------- /content/standards/external-standards.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: External Standards Catalogues 3 | exclude_from_list: true 4 | --- 5 | # External Standards Catalogues 6 | 7 | - [Criminal Justice System Exchange Data Standards Catalogue](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/360582/cjs-data-standards-catalogue-5.0.pdf) 8 | - [NHS information standards](https://digital.nhs.uk/data-and-information/information-standards) 9 | - [ONS data standards](https://www.ons.gov.uk/aboutus/transparencyandgovernance/datastrategy/datastandards) 10 | - [LGA data standards](https://standards.esd.org.uk/) 11 | -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/_modules/anchored-headings.js: -------------------------------------------------------------------------------- 1 | (function ($, Modules) { 2 | 'use strict' 3 | 4 | Modules.AnchoredHeadings = function () { 5 | this.start = function ($element) { 6 | var headings = $element.find('h1, h2, h3, h4, h5, h6') 7 | headings.each(injectAnchor) 8 | } 9 | 10 | function injectAnchor () { 11 | var $this = $(this) 12 | $this.addClass('anchored-heading') 13 | $this.prepend( 14 | '' 15 | ) 16 | } 17 | } 18 | })(jQuery, window.GOVUK.Modules) 19 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/vendor/_fixedsticky.scss: -------------------------------------------------------------------------------- 1 | .fixedsticky { 2 | position: -webkit-sticky; 3 | position: -moz-sticky; 4 | position: -ms-sticky; 5 | position: -o-sticky; 6 | position: sticky; 7 | } 8 | /* When position: sticky is supported but native behavior is ignored */ 9 | .fixedsticky-withoutfixedfixed .fixedsticky-off, 10 | .fixed-supported .fixedsticky-off { 11 | position: relative; 12 | } 13 | .fixedsticky-withoutfixedfixed .fixedsticky-on, 14 | .fixed-supported .fixedsticky-on { 15 | position: fixed; 16 | } 17 | .fixedsticky-dummy { 18 | display: none; 19 | } 20 | .fixedsticky-on + .fixedsticky-dummy { 21 | display: block; 22 | } 23 | -------------------------------------------------------------------------------- /standards-catalogue/.schema/tag.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-04/schema#", 3 | "id": "https://github.com/alphagov/data-standards-authority/blob/main/standards-catalogue/.schema/tag.json", 4 | "title": "Data Standards Authority Tag objects", 5 | "description": "A JSON Schema to manage the format of tag objects", 6 | "type": "object", 7 | "required": [ 8 | "name" 9 | ], 10 | "properties": { 11 | "name": { 12 | "$comment": "The name of the tag", 13 | "type": "string", 14 | "minLength": 2 15 | }, 16 | "description": { 17 | "$comment": "A description of the tag", 18 | "type": "string" 19 | } 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_contribution-banner.scss: -------------------------------------------------------------------------------- 1 | .contribution-banner { 2 | @include govuk-font($size: 19); 3 | padding: 0; 4 | max-width: 40em; 5 | margin-top: govuk-spacing(9); 6 | margin-left: govuk-spacing(3); 7 | margin-right: govuk-spacing(3); 8 | 9 | @include govuk-media-query(tablet) { 10 | margin-left: govuk-spacing(6) + 2px; 11 | margin-right: govuk-spacing(6) + 2px; 12 | } 13 | 14 | a { 15 | margin-right: govuk-spacing(3); 16 | @include govuk-link-common; 17 | @include govuk-link-style-default; 18 | } 19 | 20 | li { 21 | display: inline-block; 22 | list-style: none; 23 | margin: 2px 0; 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /standards-catalogue/source/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: DSA 3 | weight: 1 4 | --- 5 | 6 | # Data Standards Authority 7 | 8 | This site holds a catalogue of data standards and taxonomies endorsed or under consideration by the [Data Standards Authority](https://www.gov.uk/government/groups/data-standards-authority), as well as draft guidance that the DSA is working on. 9 | 10 | If you have any questions, [please contact us](mailto:standards-catalogue@digital.cabinet-office.gov.uk). 11 | 12 | If you'd like to comment on or contribute to any of these documents, please use the link at the bottom of the page to submit a github issue. You can view the original documents in our github repo, linked below 13 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_header.scss: -------------------------------------------------------------------------------- 1 | .app-header { 2 | // Adjust the padding on the header container so that it matches the custom sidebar. 3 | .govuk-header__container--full-width { 4 | @include govuk-responsive-padding(6, "left"); 5 | @include govuk-responsive-padding(6, "right"); 6 | } 7 | // Give the product name in the header more space so it does not wrap early on smaller screens. 8 | @include govuk-media-query($from: desktop) { 9 | .govuk-header__logo { 10 | width: 65%; 11 | } 12 | .govuk-header__content { 13 | width: 55%; 14 | } 15 | } 16 | .header-content { 17 | max-width: 750px; 18 | max-width: 46.875rem; 19 | margin: auto; 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /standards-catalogue/.gitignore: -------------------------------------------------------------------------------- 1 | # See http://help.github.com/ignore-files/ for more about ignoring files. 2 | # 3 | # If you find yourself ignoring temporary files generated by your text editor 4 | # or operating system, you probably want to add a global ignore instead: 5 | # git config --global core.excludesfile ~/.gitignore_global 6 | 7 | # Ignore bundler config 8 | /.bundle 9 | 10 | # Ignore the build directory 11 | /build 12 | 13 | # Ignore the source directory as content is defined source and is synced with source during build 14 | /source 15 | 16 | # Ignore cache 17 | /.sass-cache 18 | /.cache 19 | 20 | # Ignore .DS_store file 21 | .DS_Store 22 | 23 | Staticfile.auth 24 | 25 | spec/examples.txt 26 | 27 | /tmp 28 | 29 | node_modules 30 | yarn.lock 31 | -------------------------------------------------------------------------------- /standards-catalogue/README.md: -------------------------------------------------------------------------------- 1 | # Data Standards Authority 2 | 3 | This is the home of the DSA Standards Catalogue, as well as various DSA artefacts 4 | 5 | 6 | - [Getting started](./docs/getting_started.md) 7 | - [Deployment workflow](./docs/deployment.md) 8 | - [Adding a new standard](./docs/adding_a_standard.md) 9 | 10 | ## Licence 11 | 12 | Unless stated otherwise, the codebase is released under [the MIT licence](./LICENSE). 13 | 14 | The data is [© Crown 15 | copyright](http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/copyright-and-re-use/crown-copyright/) 16 | and available under the terms of the [Open Government 17 | 3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/) 18 | licence. 19 | -------------------------------------------------------------------------------- /standards-catalogue/.schema/organisation.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-04/schema#", 3 | "id": "https://github.com/alphagov/data-standards-authority/blob/main/standards-catalogue/.schema/organisation.json", 4 | "title": "Data Standards Authority Organisations objects", 5 | "description": "A JSON Schema to manage the format of organisation objects", 6 | "type": "object", 7 | "required": [ 8 | "name", 9 | "url" 10 | ], 11 | "properties": { 12 | "name": { 13 | "$comment": "The name of the organisation", 14 | "type": "string", 15 | "minLength": 2 16 | }, 17 | "url": { 18 | "$comment": "A link to the organisation", 19 | "type": "string", 20 | "pattern": "^https?://.*" 21 | } 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /standards-catalogue/docs/deployment.md: -------------------------------------------------------------------------------- 1 | # Deployment 2 | 3 | The site is hosted on [GitHub pages][github-pages]. When a pull request is 4 | merged into `main` a new version of the site is deployed automatically using 5 | [GitHub actions][github-actions]. 6 | 7 | ## Publishing from your computer 8 | 9 | In the event you need to publish a local version of the site from your computer 10 | (not recommended) the following Rake tasks can be run: 11 | 12 | ```sh 13 | # Not recommended - pull requests are preferred 14 | bundle exec rake build publish 15 | ``` 16 | 17 | These tasks will build the site, checkout the `gh-pages` branch, commit any 18 | changes, and push them to GitHub. 19 | 20 | [github-pages]: https://pages.github.com/ 21 | [github-actions]: https://docs.github.com/en/free-pro-team@latest/actions 22 | -------------------------------------------------------------------------------- /standards-catalogue/helpers/navigation_helpers.rb: -------------------------------------------------------------------------------- 1 | module NavigationHelpers 2 | def populate_navbar(resources) 3 | root_page = resources.detect { |r| r.path == "index.html" } 4 | top_level_pages = navigable_pages(root_page.children).sort_by { |page| page.data.weight || 99_999 } 5 | navigation = [] 6 | navigation += top_level_pages.map { |page| navigation_html(page) } 7 | navigation.join 8 | end 9 | 10 | private 11 | 12 | def navigable_pages(resources) 13 | resources 14 | .filter { |resource| resource.ext.match?("html") } 15 | .reject { |resource| resource.data.hide_in_navigation } 16 | end 17 | 18 | def navigation_html(page) 19 | <<~HTML 20 |
  • 21 | #{page.data.title} 22 | #{yield if block_given?} 23 |
    • 24 | HTML 25 | end 26 | end 27 | -------------------------------------------------------------------------------- /standards-catalogue/data/tags.yml: -------------------------------------------------------------------------------- 1 | algorithms: 2 | name: Algorithms 3 | common-reference-data: 4 | name: Common Reference Data 5 | data-info-and-records-management: 6 | name: Data, Information and Records Management Lifecycle 7 | domain-specific: 8 | name: Domain Specific 9 | geospatial: 10 | name: Geospatial 11 | identification: 12 | name: Identification 13 | metadata: 14 | name: Metadata 15 | open-documents: 16 | name: Open Documents 17 | payments: 18 | name: Payments Clearing and Settlement 19 | reporting: 20 | name: Reporting 21 | security: 22 | name: Security 23 | semantics: 24 | name: Semantics 25 | service-design: 26 | name: Service, Product, Application, System or Platform Design 27 | service-referrals: 28 | name: Service Referrals 29 | tabular-data: 30 | name: Tabular Data 31 | transparency: 32 | name: Transparency 33 | vulnerability: 34 | name: Vulnerability 35 | -------------------------------------------------------------------------------- /standards-catalogue/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "name": "data-standards-authority", 4 | "license": "MIT", 5 | "scripts": { 6 | "lint": "standard" 7 | }, 8 | "dependencies": { 9 | "govuk-frontend": "^3.11.0", 10 | "jquery": "^3.6.0", 11 | "lodash": "^4.17.21", 12 | "mark.js": "^8.11.1", 13 | "tablesort": "^5.2.1" 14 | }, 15 | "devDependencies": { 16 | "standard": "^14.3.4" 17 | }, 18 | "standard": { 19 | "globals": [ 20 | "describe", 21 | "before", 22 | "after", 23 | "beforeEach", 24 | "afterEach", 25 | "it", 26 | "assert", 27 | "expect", 28 | "GOVUK", 29 | "lunr", 30 | "$", 31 | "jQuery", 32 | "_", 33 | "Modernizr", 34 | "history", 35 | "ga", 36 | "GOVUKFrontend" 37 | ], 38 | "ignore": [ 39 | "lib/assets/javascripts/_vendor/**" 40 | ] 41 | } 42 | } 43 | -------------------------------------------------------------------------------- /standards-catalogue/source/layouts/taxonomy_table.erb: -------------------------------------------------------------------------------- 1 | <% wrap_layout :layout do %> 2 | 3 |
    4 |

    <%= current_page.data.name %>

    5 | 6 | 7 | 8 | 11 | 12 | 13 | <% if current_page.data.contraction %> 14 | 15 | 16 | 19 | 20 | <% end %> 21 | 22 | 23 | 24 | 28 | 29 |
    Name 9 | <%=current_page.data.name %> 10 |
    Also Known As 17 | <%= current_page.data.contraction %> 18 |
    Status 25 | <% status = current_page.data.status %> 26 | <%= display_status(:taxonomies, status) %> 27 |
    30 |
    31 | 32 | <%= yield %> 33 | 34 | <% end %> 35 | -------------------------------------------------------------------------------- /standards-catalogue/lib/govuk_tech_docs/tech_docs_html_renderer.rb: -------------------------------------------------------------------------------- 1 | require "middleman-core/renderers/redcarpet" 2 | 3 | module GovukTechDocs 4 | class TechDocsHTMLRenderer < Middleman::Renderers::MiddlemanRedcarpetHTML 5 | include Redcarpet::Render::SmartyPants 6 | 7 | def initialize(options = {}) 8 | @local_options = options.dup 9 | @app = @local_options[:context].app 10 | super 11 | end 12 | 13 | def header(text, level) 14 | anchor = UniqueIdentifierGenerator.instance.create(text, level) 15 | %(#{text}) 16 | end 17 | 18 | def image(link, *args) 19 | %(#{super}) 20 | end 21 | 22 | def table(header, body) 23 | %(
    24 | 25 | #{header}#{body} 26 |
    27 |
    ) 28 | end 29 | end 30 | end 31 | -------------------------------------------------------------------------------- /standards-catalogue/.schema/licence.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-04/schema#", 3 | "id": "https://github.com/alphagov/data-standards-authority/blob/main/standards-catalogue/.schema/licence.json", 4 | "title": "Data Standards Authority Licences objects", 5 | "description": "A JSON Schema to manage the format of licence objects", 6 | "type": "object", 7 | "required": [ 8 | "name", 9 | "type" 10 | ], 11 | "properties": { 12 | "name": { 13 | "$comment": "The name of the licence", 14 | "type": "string", 15 | "minLength": 2 16 | }, 17 | "url": { 18 | "$comment": "A link to the licence", 19 | "type": "string", 20 | "pattern": "^https?://.*" 21 | }, 22 | "type": { 23 | "$comment": "The type of licence", 24 | "type": "string", 25 | "enum": [ 26 | "Proprietary", 27 | "Unknown", 28 | "Open standard" 29 | ] 30 | } 31 | } 32 | } 33 | -------------------------------------------------------------------------------- /standards-catalogue/Gemfile: -------------------------------------------------------------------------------- 1 | # If you do not have OpenSSL installed, change 2 | # the following line to use 'http://' 3 | source "https://rubygems.org" 4 | 5 | gem "rake" 6 | 7 | # For faster file watcher updates on Windows: 8 | gem "wdm", "~> 0.1.0", platforms: %i[mswin mingw] 9 | 10 | # Windows does not come with time zone data 11 | gem "tzinfo-data", platforms: %i[mswin mingw jruby] 12 | 13 | gem "sqlite3" 14 | 15 | group :test do 16 | gem "factory_bot" 17 | gem "rspec" 18 | end 19 | 20 | group :development do 21 | gem "rubocop-govuk" 22 | end 23 | 24 | group :development, :test do 25 | gem "pry" 26 | end 27 | 28 | # From tech-docs-gem - to be revised 29 | gem "activesupport" 30 | gem "middleman", ">= 4.4.0", "<5.0" 31 | gem "middleman-autoprefixer" 32 | gem "middleman-compass" 33 | gem "middleman-livereload" 34 | gem "middleman-search-gds" 35 | gem "middleman-sprockets" 36 | gem "redcarpet" 37 | gem "sass" 38 | gem "sprockets" 39 | 40 | gem "json-schema" 41 | -------------------------------------------------------------------------------- /content/guidance/apimanagement/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: API Management Guidance 3 | weight: 830 4 | keywords: 'API Management' 5 | identifier: DSA-003 6 | name: APIManagement 7 | organisation: Data Standards Authority 8 | author_email: api-programme@digital.cabinet-office.gov.uk 9 | status: draft 10 | startDate: 2021-03-22 11 | dateAdded: 2021-03-22 12 | dateUpdated: 2021-05-26 13 | --- 14 | 15 | 16 | ## *DRAFT* | API Management Guidance | *DRAFT* 17 | 18 | 19 | _This is a DRAFT document for discussion. This is not finalised. All aspects of this document are subject to change. Please leave comments on any aspect of it._ 20 | 21 | 22 | #### Contents: 23 | - [00 - Cover Page](index.html) 24 | - [01 - Introduction](APIM-Introduction.html) 25 | - [02 - Design](APIM-Design.html) 26 | - [03 - Deployment](APIM-Deployment.html) 27 | - [04 - Management](APIM-Management.html) 28 | - [05 - Discovery](APIM-Discovery.html) 29 | - [06 - Retirement](APIM-Retirement.html) 30 | 31 | 32 | [Next](APIM-Introduction.html) 33 | -------------------------------------------------------------------------------- /standards-catalogue/data/organisations.yml: -------------------------------------------------------------------------------- 1 | agi: 2 | name: Association for Geographic Information 3 | url: https://www.agi.org.uk/ 4 | doi-foundation: 5 | name: DOI Foundation and DataCite 6 | url: https://www.doi.org/ 7 | geospatial-commission: 8 | name: Geospatial Commission 9 | url: 'https://www.agi.org.uk/' 10 | ietf: 11 | name: Internet Engineering Task Force 12 | url: 'https://www.ietf.org/' 13 | iso: 14 | name: ISO 15 | url: 'https://www.iso.org/' 16 | odf: 17 | name: OASIS ODF Technical Committee 18 | url: 'https://www.oasis-open.org/' 19 | open-ownership: 20 | name: Open Ownership 21 | url: https://www.openownership.org/ 22 | open-referral-uk: 23 | name: Open Referral UK 24 | url: 'https://openreferraluk.org/' 25 | ordnance-survey: 26 | name: Ordnance Survey 27 | url: 'https://www.ordnancesurvey.co.uk/' 28 | three-sixty-giving: 29 | name: 360Giving 30 | url: 'https://www.threesixtygiving.org/' 31 | uk-gov: 32 | name: UK Government (CDDO and CDEI) 33 | url: 'https://www.gov.uk' 34 | -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/_modules/navigation.js: -------------------------------------------------------------------------------- 1 | (function ($, Modules) { 2 | 'use strict' 3 | 4 | Modules.Navigation = function () { 5 | var $html = $('html') 6 | 7 | var $navToggle 8 | var $nav 9 | 10 | this.start = function ($element) { 11 | $navToggle = $('.js-nav-toggle', $element) 12 | $nav = $('.js-nav', $element) 13 | 14 | updateAriaAttributes() 15 | 16 | $navToggle.on('click', toggleNavigation) 17 | $(window).on('resize', updateAriaAttributes) 18 | } 19 | 20 | function updateAriaAttributes () { 21 | var navIsVisible = $nav.is(':visible') 22 | 23 | $navToggle.attr('aria-expanded', navIsVisible ? 'true' : 'false') 24 | $nav.attr('aria-hidden', navIsVisible ? 'false' : 'true') 25 | } 26 | 27 | function toggleNavigation () { 28 | var navIsVisible = !$html.hasClass('nav-open') 29 | 30 | $html.toggleClass('nav-open', navIsVisible) 31 | updateAriaAttributes() 32 | } 33 | } 34 | })(jQuery, window.GOVUK.Modules) 35 | -------------------------------------------------------------------------------- /standards-catalogue/source/layouts/_search.erb: -------------------------------------------------------------------------------- 1 |
    2 |
    3 | 4 | 7 | 8 |
    9 | 16 |
    17 | -------------------------------------------------------------------------------- /standards-catalogue/config/tech-docs.yml: -------------------------------------------------------------------------------- 1 | # Host to use for canonical URL generation (without trailing slash) 2 | host: https://alphagov.github.io/data-standards-authority 3 | 4 | # Header-related options 5 | show_govuk_logo: false 6 | service_name: Data Standards Authority 7 | service_link: https://alphagov.github.io/data-standards-authority 8 | phase: Discovery 9 | 10 | # Links to show in the footer 11 | footer_links: 12 | Accessibility Statement: /accessibility.html 13 | 14 | # Links to show on right-hand-side of header 15 | header_links: 16 | 17 | # Prevent robots from indexing (e.g. whilst in development) 18 | prevent_indexing: false 19 | 20 | show_contribution_banner: true 21 | github_repo: alphagov/data-standards-authority/ 22 | 23 | #to add feedback email address on pages: 24 | contact_email: standards-catalogue@digital.cabinet-office.gov.uk 25 | 26 | # Table of contents depth – how many levels to include in the table of contents. 27 | # If your ToC is too long, reduce this number and we'll only show higher-level 28 | # headings. 29 | max_toc_heading_level: 5 30 | -------------------------------------------------------------------------------- /content/standards/bods/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Beneficial Ownership Data Standard (BODS) v0.3 3 | specification_url: https://standard.openownership.org/en/0.3.0/about/index.html 4 | tags: 5 | - service-referrals 6 | - service-design 7 | maintainer_id: open-ownership 8 | licence_id: Apache-2.0 9 | endorsement_status_events: 10 | - status: endorsed 11 | date: "2022-03-16" 12 | short_description: Defines a common data format that provides a consistent way to collect, use, exchange and publish beneficial ownership information. 13 | --- 14 | 15 | 16 | 17 | Use the Beneficial Ownership Data Standard v0.2 to collect, use, exchange and publish beneficial ownership information. 18 | 19 | [Read GOV.UK guidance](https://www.gov.uk/government/publications/open-standards-for-government/collect-use-and-exchange-beneficial-ownership-information) about this standard to help you: 20 | 21 | * learn how to use it for government work 22 | * find out how it meets user needs 23 | * access links to data schemas, technical guidance and example data 24 | * publish BODS data properly and following government policy 25 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/_govuk_tech_docs.scss: -------------------------------------------------------------------------------- 1 | $govuk-assets-path: "/assets/govuk-frontend/govuk/assets/" !default; 2 | 3 | // Include only the bits of GOV.UK Frontend we need 4 | @import "govuk-frontend/govuk/settings/all"; 5 | @import "govuk-frontend/govuk/tools/all"; 6 | @import "govuk-frontend/govuk/helpers/all"; 7 | 8 | @import "govuk-frontend/govuk/core/all"; 9 | @import "govuk-frontend/govuk/objects/all"; 10 | 11 | @import "govuk-frontend/govuk/components/footer/footer"; 12 | @import "govuk-frontend/govuk/components/header/header"; 13 | @import "govuk-frontend/govuk/components/inset-text/inset-text"; 14 | @import "govuk-frontend/govuk/components/input/input"; 15 | @import "govuk-frontend/govuk/components/tag/tag"; 16 | @import "govuk-frontend/govuk/components/skip-link/skip-link"; 17 | @import "govuk-frontend/govuk/components/warning-text/warning-text"; 18 | @import "govuk-frontend/govuk/components/table/table"; 19 | 20 | @import "govuk-frontend/govuk/utilities/all"; 21 | @import "govuk-frontend/govuk/overrides/all"; 22 | 23 | @import "core"; 24 | @import "vendor/fixedsticky"; 25 | -------------------------------------------------------------------------------- /standards-catalogue/spec/helpers/format_helpers_spec.rb: -------------------------------------------------------------------------------- 1 | require_relative "../../helpers/format_helpers" 2 | 3 | RSpec.describe FormatHelpers do 4 | subject(:helpers) do 5 | Class.new { include FormatHelpers }.new 6 | end 7 | 8 | describe "#render_markdown" do 9 | it "renders HTML from the markdown content" do 10 | markdown = "Some content" 11 | 12 | expect(helpers.render_markdown(markdown)).to match "

    Some content

    " 13 | end 14 | 15 | it "autolinks any URLs which aren't normal markdown links" do 16 | markdown = "Checkout https://example.com" 17 | 18 | expect(helpers.render_markdown(markdown)) 19 | .to match '

    Checkout https://example.com

    ' 20 | end 21 | end 22 | 23 | describe "#unescape_newlines" do 24 | it "converts escaped newlines into unescaped, literal newlines" do 25 | original = 'foo\nbar\n\nbaz\n' 26 | 27 | expect(helpers.unescape_newlines(original)).to eq <<~TXT 28 | foo 29 | bar 30 | 31 | baz 32 | TXT 33 | end 34 | end 35 | end 36 | -------------------------------------------------------------------------------- /standards-catalogue/data/licences.yml: -------------------------------------------------------------------------------- 1 | Apache-2.0: 2 | name: Apache License 2.0 3 | type: Open standard 4 | url: 'https://spdx.org/licenses/Apache-2.0.html' 5 | CC0: 6 | name: The creative commons public domain dedication 7 | type: Open standard 8 | url: 'https://creativecommons.org/about/cclicenses/#:~:text=CC0%20(aka%20CC%20Zero)%20is,or%20format%2C%20with%20no%20conditions' 9 | CC-BY-4.0: 10 | name: Creative Commons Attribution 4.0 International 11 | type: Open standard 12 | url: 'https://spdx.org/licenses/CC-BY-4.0.html' 13 | CC-BY-SA-4.0: 14 | name: Creative Commons Attribution Share Alike 4.0 International 15 | type: Open standard 16 | url: 'https://spdx.org/licenses/CC-BY-SA-4.0.html' 17 | IETF: 18 | name: Internet Engineering Task Force Trust 19 | type: Open standard 20 | url: 'https://www.rfc-editor.org' 21 | OGL-UK-3.0: 22 | name: Open Government Licence v3.0 23 | type: Open standard 24 | url: 'https://spdx.org/licenses/OGL-UK-3.0.html' 25 | proprietary: 26 | name: Proprietary 27 | type: Proprietary 28 | unknown: 29 | name: Unknown 30 | type: Unknown 31 | -------------------------------------------------------------------------------- /content/standards/iso20022/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Universal financial industry message scheme 3 | contraction: ISO20022 4 | specification_url: https://www.iso20022.org/iso-20022-message-definitions 5 | tags: 6 | - domain-specific 7 | - payments 8 | maintainer_id: iso 9 | licence_id: proprietary 10 | endorsement_status_events: 11 | - status: review 12 | date: "2021-02-02" 13 | short_description: 14 | --- 15 | 16 | 17 | 18 | ISO 20022 is a multi part International Standard prepared by ISO Technical Committee TC68 Financial Services. It describes a common platform for the development of messages using: 19 | - a modelling methodology to capture in a syntax-independent way financial business areas, business transactions and associated message flows 20 | - a central dictionary of business items used in financial communications 21 | - a set of XML and ASN.1 design rules to convert the message models into XML or ASN.1 schemas, whenever the use of the ISO 20022 XML or ASN.1-based syntax is preferred. 22 | 23 | 24 | ## How To: 25 | - [https://www.iso20022.org/iso-20022-message-definitions?search=payments](https://www.iso20022.org/iso-20022-message-definitions?search=payments) 26 | -------------------------------------------------------------------------------- /standards-catalogue/LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 Government Digital Service 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /content/standards/digital-object-identifier/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Digital Object identifier System 3 | contraction: DOI 4 | specification_url: https://ieeexplore.ieee.org/document/771073 5 | tags: 6 | - identification 7 | maintainer_id: doi-foundation 8 | licence_id: CC0 9 | endorsement_status_events: 10 | - status: endorsed 11 | short_description: DOI introduces persistent identifiers for research and information assets 12 | --- 13 | 14 | The DOI system enables persistent identifiers with permanent web addresses 15 | to be assigned to key information assets published by government, using an 16 | external registration agency. DOIs help to make key resources, such as data, insights, bulletins and policy documents findable, citable and better connected. 17 | 18 | ### Government Guidance on persistent resolvable identifiers: 19 | - [https://www.gov.uk/government/publications/open-standards-for-government/persistent-resolvable-identifiers](https://www.gov.uk/government/publications/open-standards-for-government/persistent-resolvable-identifiers) 20 | 21 | ### Government service manual: 22 | - [https://www.gov.uk/service-manual/technology/using-https](https://www.gov.uk/service-manual/technology/using-https) 23 | -------------------------------------------------------------------------------- /content/guidance/index.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Guidance 3 | weight: 800 4 | --- 5 | # DSA Guidance 6 | 7 | ## Description: 8 | These pieces of guidance are in development by the Data Standards Authority. We welcome your feedback on them, please open an issue from the link on the relevant page to add your comments. The following documents are currently open: 9 | 10 |
    11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | <% current_resource.children.sort_by{ |page| get_link_text(page).downcase }.each do |f| %> 20 | <% if f.content_type.include? "html" %> 21 | 22 | 23 | 24 | 25 | <% end %> 26 | <% end %> 27 | 28 |
    NameStatus
    <%= link_to get_link_text(f), f.path.delete_prefix("guidance/") %> <%= display_status(:guidance, f.data.status) %>
    29 |
    30 | -------------------------------------------------------------------------------- /SDO/membership.md: -------------------------------------------------------------------------------- 1 | # List of Standards Development Organisations of which GDS is a member 2 | 3 | | Organisation | Membership Level | Benefits | Cost | Renewal Date | 4 | |:---------------------------------------------------------:|:----------------:|:----------------------------------------:|:----------:|:------------:| 5 | | [W3C](https://www.w3.org/Consortium/) | Advisory Council | Voting rights | EU €7,800 | 2021-09-30 | 6 | | [BSi](https://www.bsigroup.com/en-GB/) | TBD | TBD | TBD | TBD | 7 | | [Unicode](https://unicode.org/consortium/consort.html) | Associate | Full participation at technical meetings | US $2,900 | 2021-01-31 | 8 | | [Linux Foundation](https://www.linuxfoundation.org/) | Associate | Full participation at technical meetings | Free | TBD | 9 | | [OpenAPI](https://www.openapis.org/membership/members) | Member | Full participation at technical meetings | Free | TBD | 10 | | [The Document Foundation](https://documentfoundation.org) | Advisory Board | Full participation at technical meetings | US $10,000 | 2020-12-31 | 11 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_collapsible.scss: -------------------------------------------------------------------------------- 1 | // Collapsible JS component styling, made for the navigation tree. 2 | // These classes are added in table-of-contents.js. 3 | // They should not be applied without the JS. 4 | 5 | .collapsible { 6 | position: relative; 7 | } 8 | .collapsible__body { 9 | display: none; 10 | .collapsible.is-open & { 11 | display: block 12 | } 13 | } 14 | 15 | .collapsible__heading, 16 | .toc__list > ul > li > a:link.collapsible__heading { 17 | margin-right: 30px; 18 | } 19 | 20 | .collapsible__toggle { 21 | position: absolute; 22 | top: 0; 23 | right: -25px; 24 | width: 50px; 25 | height: 40px; 26 | overflow: hidden; 27 | text-indent: -999em; 28 | border: 0; 29 | background: 0; 30 | color: inherit; 31 | padding: 0; 32 | 33 | &:focus { 34 | @include govuk-focused-text; 35 | } 36 | } 37 | 38 | .collapsible__toggle-icon { 39 | position: absolute; 40 | top: 0; 41 | right: 20px; 42 | &::after { 43 | content: ''; 44 | display: block; 45 | border: 2px solid govuk-colour("black"); 46 | border-width: 2px 2px 0 0; 47 | transform: rotate(135deg); 48 | width: 10px; 49 | height: 10px; 50 | margin-top: 10px; 51 | } 52 | .collapsible.is-open &::after { 53 | transform: rotate(315deg); 54 | margin-top: 18px; 55 | } 56 | } 57 | -------------------------------------------------------------------------------- /content/standards/360giving/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 360Giving Schema 3 | specification_url: https://standard.threesixtygiving.org/en/latest/reference/#spreadsheet-format 4 | tags: 5 | - domain-specific 6 | - payments 7 | maintainer_id: three-sixty-giving 8 | licence_id: CC-BY-4.0 9 | endorsement_status_events: 10 | - status: review 11 | date: "2021-02-02" 12 | short_description: 13 | --- 14 | 15 | 16 | 17 | Grant-makers in government need to be able to track their investments. The 360Giving data standard allows you to publish open and structured grant data and provide grant-makers with a way of identifying and understanding what is happening to their money. This makes the data easier to understand and use for decision-making and learning across the charity sector and government. 18 | 19 | 20 | ## Guidance: 21 | Resources for the 360Giving data standard: 22 | - view the 360Giving schema to [help you structure and lay out grant data](https://standard.threesixtygiving.org/en/latest/_static/docson/index.html#../360-giving-schema.json$$expand) 23 | - use the 360Giving data standard to [disclose and publish grant data from government organisations](https://www.gov.uk/government/publications/open-standards-for-government/data-standard-for-grant-making) 24 | - produce 360Giving data [in a spreadsheet format](https://standard.threesixtygiving.org/en/latest/reference/#spreadsheet-format) 25 | -------------------------------------------------------------------------------- /.github/workflows/scorecards-analysis.yml: -------------------------------------------------------------------------------- 1 | name: Scorecards supply-chain security 2 | on: 3 | branch_protection_rule: {} 4 | schedule: 5 | - cron: '23 7 * * 3' 6 | push: 7 | branches: [ main ] 8 | 9 | permissions: read-all 10 | 11 | jobs: 12 | analysis: 13 | name: Scorecards analysis 14 | runs-on: ubuntu-latest 15 | permissions: 16 | security-events: write 17 | actions: read 18 | contents: read 19 | 20 | steps: 21 | - name: "Checkout code" 22 | uses: actions/checkout@ec3a7ce113134d7a93b817d10a8272cb61118579 23 | with: 24 | persist-credentials: false 25 | 26 | - name: "Run analysis" 27 | uses: ossf/scorecard-action@b614d455ee90608b5e36e3299cd50d457eb37d5f 28 | with: 29 | results_file: results.sarif 30 | results_format: sarif 31 | repo_token: ${{ secrets.SCORECARD_READ_TOKEN }} 32 | publish_results: true 33 | 34 | - name: "Upload artifact" 35 | uses: actions/upload-artifact@82c141cc518b40d92cc801eee768e7aafc9c2fa2 36 | with: 37 | name: SARIF file 38 | path: results.sarif 39 | retention-days: 5 40 | 41 | - name: "Upload to code-scanning" 42 | uses: github/codeql-action/upload-sarif@474bbf07f9247ffe1856c6a0f94aeeb10e7afee6 43 | with: 44 | sarif_file: results.sarif 45 | -------------------------------------------------------------------------------- /content/standards/algorithmic-transparency-reporting-standard/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Algorithmic Transparency Reporting Standard 3 | contraction: ATRS 4 | specification_url: https://www.gov.uk/government/publications/algorithmic-transparency-template 5 | tags: 6 | - algorithms 7 | - transparency 8 | maintainer_id: uk-gov 9 | licence_id: OGL-UK-3.0 10 | endorsement_status_events: 11 | - status: endorsed 12 | short_description: A standardised way of recording and sharing information about how the public sector uses algorithmic tools. 13 | --- 14 | 15 | The Algorithmic Transparency Recording Standard helps public sector organisations provide clear information about the algorithmic tools they use, and why they’re using them. 16 | Algorithmic transparency means being open about how algorithmic tools support decisions. This includes providing information on algorithmic tools and algorithm-assisted decisions in a complete, open, understandable, easily-accessible, and free format. 17 | 18 | ### Algorithmic transparency reporting standard hub: 19 | - [https://www.gov.uk/government/collections/algorithmic-transparency-recording-standard-hub](https://www.gov.uk/government/collections/algorithmic-transparency-recording-standard-hub) 20 | 21 | ### CDEI report on algorithmic transparency in the public sector: 22 | - [https://www.gov.uk/service-manual/technology/using-https](https://www.gov.uk/service-manual/technology/using-https) 23 | 24 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_app-pane.scss: -------------------------------------------------------------------------------- 1 | @include govuk-media-query(tablet, $media-type: screen) { 2 | $toc-width: 330px; 3 | 4 | .flexbox, .flexboxtweener { 5 | 6 | body { 7 | overflow: hidden; 8 | } 9 | 10 | .app-pane { 11 | display: flex; 12 | flex-direction: column; 13 | overflow-x: hidden; 14 | height: 100vh; 15 | } 16 | 17 | .app-pane__header { 18 | display: flex; 19 | flex-direction: column; 20 | flex: 1 0 auto; 21 | 22 | > * { 23 | flex: 1 0 auto; 24 | } 25 | } 26 | 27 | .app-pane__body { 28 | display: flex; 29 | flex: 1 1 100%; 30 | position: relative; 31 | max-width: 800px; 32 | max-width: 50rem; 33 | margin: auto; 34 | 35 | > * { 36 | overflow-x: scroll; 37 | -webkit-overflow-scrolling: touch; 38 | -ms-overflow-style: none; 39 | } 40 | } 41 | 42 | .app-pane__toc { 43 | flex: 0 0 auto; 44 | width: $toc-width; 45 | border-right: 1px solid $govuk-border-colour; 46 | } 47 | 48 | .app-pane__content { 49 | flex: 1 1 auto; 50 | } 51 | } 52 | 53 | .no-flexbox.no-flexboxtweener, 54 | .no-js { 55 | .app-pane__toc { 56 | float: left; 57 | width: $toc-width; 58 | } 59 | 60 | .app-pane__content { 61 | margin-left: $toc-width; 62 | } 63 | } 64 | } 65 | 66 | -------------------------------------------------------------------------------- /content/standards/securitytxt/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Security.txt 3 | contraction: SECURITY 4 | specification_url: https://securitytxt.org 5 | tags: 6 | - vulnerability 7 | - reporting 8 | - security 9 | maintainer_id: ietf 10 | licence_id: IETF 11 | endorsement_status_events: 12 | - status: endorsed 13 | short_description: Security.txt provides with a simple way to report a vulnerability 14 | --- 15 | 16 | 17 | 18 | The security.txt data standard was developed to make it easier to publish important 19 | information regarding how to report a vulnerability. One of the most important elements of 20 | vulnerability disclosure, and a challenge for the finder, is understanding who to contact. 21 | Security.txt is an IETF Internet informational specification (RFC 9116) and it describes a text 22 | file that webmasters can host in the “/.well-known” directory of the domain root. This file 23 | advertises the department’s vulnerability disclosure process so that someone can quickly 24 | find all of the information needed to report a vulnerability. 25 | 26 | 27 | ### Guidance: 28 | 29 | - A piece of guidance will be published to help people use the security.txt standard. New data 30 | standards require guidance in ‘profile’ form to give users information about how it works, 31 | and how to find resources about it. A piece of guidance in the form of a basic ‘profile’ to 32 | help people use the security/txt standard will be added. 33 | 34 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_anchored-heading.scss: -------------------------------------------------------------------------------- 1 | .anchored-heading { 2 | $icon-width: 23px; 3 | $icon-height: 14px; 4 | $icon-spacing: 3px; 5 | 6 | position: relative; 7 | 8 | &__icon { 9 | position: absolute; 10 | width: $icon-width; 11 | left: -($icon-width + ($icon-spacing * 2)); 12 | padding: 0 $icon-spacing; 13 | margin-top: -1px; 14 | 15 | opacity: 0; 16 | display: none; 17 | 18 | text-decoration: none; 19 | text-indent: -9999em; 20 | 21 | background-image: image-url('/images/anchored-heading-icon.png'); 22 | background-repeat: no-repeat; 23 | background-position: center center; 24 | 25 | @include govuk-device-pixel-ratio { 26 | background-image: image-url('/images/anchored-heading-icon-2x.png'); 27 | background-size: $icon-width $icon-height; 28 | } 29 | 30 | @include govuk-media-query(tablet) { 31 | display: block; 32 | } 33 | 34 | &:before { 35 | // zero width space character so that the link behaves like it has text, 36 | // has height, sits on the baseline, etc. 37 | content: "\200b"; 38 | } 39 | } 40 | 41 | &:hover &__icon { 42 | @include govuk-media-query(tablet) { 43 | opacity: 1; 44 | } 45 | } 46 | 47 | &__icon:focus { 48 | @include govuk-media-query(tablet) { 49 | opacity: 1; 50 | outline-width: 1px; 51 | padding: 0 ($icon-spacing - 1); 52 | } 53 | } 54 | } 55 | -------------------------------------------------------------------------------- /content/standards/rfc4180/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Common Format and MIME Type for Comma-Separated Values (CSV) Files 3 | contraction: RFC4180 4 | specification_url: https://tools.ietf.org/html/rfc4180 5 | tags: 6 | - tabular-data 7 | - data-info-and-records-management 8 | - open-documents 9 | maintainer_id: ietf 10 | licence_id: unknown 11 | endorsement_status_events: 12 | - status: endorsed 13 | date: "2021-02-02" 14 | short_description: 15 | --- 16 | 17 | 18 | 19 | You can use this standard for publishing data, where your data has a variety of uses and is for many users. This standard does not cover non-tabular models of data. For example: 20 | 21 | - multiple tables with relations, such as SQL 22 | - hierarchical/flexible records, such as XML or JSON 23 | - geographic, such as GeoJSON 24 | - graph/triples, such as RDF 25 | This standard does not cover extra information about the tabular data, such as the column types, or table contents validation. You should keep this type of information separate from a CSV file to avoid it conflicting with the data structure as described in RFC 4180.. 26 | 27 | 28 | 29 | ## Guidance: 30 | - [https://tools.ietf.org/html/rfc4180](https://tools.ietf.org/html/rfc4180) 31 | 32 | ## How To: 33 | - [https://www.gov.uk/government/publications/recommended-open-standards-for-government/tabular-data-standard#how-to-use-this-standard](https://www.gov.uk/government/publications/recommended-open-standards-for-government/tabular-data-standard#how-to-use-this-standard) 34 | -------------------------------------------------------------------------------- /content/standards/odf12/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: ODF 1.2 3 | specification_url: https://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html 4 | tags: 5 | - data-info-and-records-management 6 | - open-documents 7 | maintainer_id: odf 8 | licence_id: unknown 9 | endorsement_status_events: 10 | - status: endorsed 11 | date: "2021-02-02" 12 | short_description: 13 | --- 14 | 15 | 16 | 17 | The ODF standard works on most operating systems for desktops, laptops, mobile phones and tablets. ODF 1.2 is an open standard that allows suppliers to create interoperable office productivity solutions; allows stricter security checks to help prevent common cyber-attack scenarios; can lower IT costs as ODF is either low cost or free to use; allows the government and citizens, businesses and other organisations to share documents; allows government staff to share and edit documents; is compatible with a wide range of software including assistive technology; can add digital signatures to a document; has a powerful generic metadata system. 18 | 19 | 20 | 21 | ## Guidance: 22 | - [https://www.gov.uk/guidance/using-open-document-formats-odf-in-your-organisation](https://www.gov.uk/guidance/using-open-document-formats-odf-in-your-organisation) 23 | 24 | ## How To: 25 | - [https://www.gov.uk/government/publications/open-standards-for-government/sharing-or-collaborating-with-government-documents](https://www.gov.uk/government/publications/open-standards-for-government/sharing-or-collaborating-with-government-documents) 26 | -------------------------------------------------------------------------------- /standards-catalogue/docs/adding_a_standard.md: -------------------------------------------------------------------------------- 1 | # Adding a new standard 2 | 3 | To add a new standard in GitHub: 4 | 5 | - Go to the [standards directory](../../content/standards) 6 | - Create a new file called `index.html.md` inside a directory named after the standard. For example to create a standard for `360 Giving` you'd create a file called `360giving/index.html.md` 7 | - For an example to copy, see [the existing standards](../../content/standards/). Open one of them and click on 'raw' to see the markdown content 8 | - Copy and paste this to the top of your new file and replace the values with the relevant ones for the new standard 9 | 10 | The information in the frontmatter will be displayed in a table. Any other content can be added below it. 11 | 12 | ## Filling out the frontmatter 13 | 14 | Some further information, for example about organisations, licences, tags and statuses, is kept in separate [data files](../data). Check to see if there is already an entry for the maintainer, licence or tag you're using. If there is you can reuse it, or if there's not you can add a new one to the data file. 15 | 16 | - maintainer_id relates to an entry in the [organisations](../data/organisations.yml) file 17 | - `licence_id` relates to an entry in the [licences](../data/licences.yml) file 18 | - `tags` relates to entries in the [tags](../data/tags.yml) file 19 | - `status` is in the [statuses](../data/statuses.yml) file and can either be endorsed or review (all lower case) 20 | 21 | If you have any questions, get in touch with a member of the [DSA team](https://github.com/orgs/alphagov/teams/dsa-reviewers). 22 | -------------------------------------------------------------------------------- /adr/0002-standards-static-site-configuration.md: -------------------------------------------------------------------------------- 1 | --- 2 | creation_date: 2021-11-11 3 | decision_date: 2021-11-11 4 | status: accepted 5 | --- 6 | # Alignment with the schema, while using a static website 7 | 8 | ## Context 9 | 10 | This is a byproduct from ADR-0001, please review it for further context. 11 | 12 | As the DSA Workbench is a static site, with the Standards information being contributed through Markdown files with YAML frontmatter, we have a decision around how aligned we want to be with the planned schema. 13 | 14 | Because we have a mix of technical skills that are contributing to the repository, we need to balance schema adoption with ease of contribution. 15 | 16 | Schema adoption could mean that we use different data files for each data store, and treat the Standards themselves as purely machine-readable data. 17 | 18 | ## Decision 19 | 20 | We have decided to prioritise the alignment with the schema, instead of reducing the number of files that need to be modified. 21 | 22 | This gives us the ability to start to align with the long-term data model before we migrate to using a full data store. 23 | 24 | ## Consequences 25 | 26 | This will require a little more curation overhead, and as there will be a split across multiple files, there will be a little more work required by contributors to add/update standards. 27 | 28 | Some data, such as the `Events` data will for now be stored in the frontmatter, instead of separately. 29 | 30 | We will prioritise making sure contributing documentation is provided, and that support is provided to contributors to support them over time. 31 | 32 | We will continue to use Markdown with YAML frontmatter, as that is a fairly well understood format for contributors. 33 | -------------------------------------------------------------------------------- /content/standards/openreferraluk/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: OpenReferralUK 3 | specification_url: https://openreferraluk.org/about-standard 4 | tags: 5 | - service-referrals 6 | - service-design 7 | maintainer_id: open-referral-uk 8 | licence_id: CC-BY-SA-4.0 9 | endorsement_status_events: 10 | - status: endorsed 11 | date: "2021-03-16" 12 | short_description: Making it easy to publish, find and use community services data 13 | --- 14 | 15 | 16 | 17 | The standard provides for recording sufficient data to be able to identify a small target set of services that closely meet the needs of a prospective service user, as given by the user's location and circumstances. The OpenReferral schema defines a structure for human services data - that is, a directory of services that meet human needs. Open Referral UK extends Open Referral to support richer data where needed. It then constrains the resultant schema by means of an application profile which says what fields are recommended for English use and what external vocabularies to reference. 18 | 19 | 20 | ## Use Cases: 21 | - [https://openreferraluk.org/about-standard](https://openreferraluk.org/about-standard) 22 | 23 | ## Case Studies: 24 | - [https://openreferraluk.org/community/case-studies](https://openreferraluk.org/community/case-studies) 25 | - [https://blog.wearefuturegov.com/how-to-build-a-service-directory-with-data-standards-70f926f2ed00](https://blog.wearefuturegov.com/how-to-build-a-service-directory-with-data-standards-70f926f2ed00) 26 | 27 | ## Guidance: 28 | - [https://developers.openreferraluk.org/Guidance/](https://developers.openreferraluk.org/Guidance/) 29 | 30 | ## How To: 31 | - [Steps to adopting the standard](https://openreferraluk.org/how-it-works/standard-adoption-steps) 32 | -------------------------------------------------------------------------------- /standards-catalogue/source/layouts/standards_table.erb: -------------------------------------------------------------------------------- 1 | <% wrap_layout :layout do %> 2 | 3 |
    4 |

    <%= current_page.data.name %>

    5 | 6 | 7 | 8 | 11 | 12 | 13 | <% if current_page.data.contraction %> 14 | 15 | 16 | 19 | 20 | <% end %> 21 | 22 | 23 | 24 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 43 | 44 | 45 | 46 | 47 | 51 | 52 |
    Name 9 | <%=link_to current_page.data.name, current_page.data.specification_url %> 10 |
    Also Known As 17 | <%= current_page.data.contraction %> 18 |
    Tags 25 |
      26 | <% current_page.data.tags.each do |tag| %> 27 |
    • <%= data.tags[tag].name %>
      • 28 | <% end %> 29 |
    30 |
    Maintained By<%= display_organisation(current_page.data.maintainer_id) %>
    Licence 41 | <%= display_licence(current_page.data.licence_id) %> 42 |
    Status 48 | <% status = current_page.data.endorsement_status_events.last.status %> 49 | <%= display_status(:standard, status) %> 50 |
    53 |
    54 | 55 | <%= yield %> 56 | 57 | 60 | 61 | <% end %> 62 | -------------------------------------------------------------------------------- /standards-catalogue/lib/govuk_tech_docs/unique_identifier_generator.rb: -------------------------------------------------------------------------------- 1 | require "singleton" 2 | 3 | module GovukTechDocs 4 | class UniqueIdentifierGenerator 5 | include Singleton 6 | 7 | Anchor = Struct.new(:id, :level) 8 | 9 | attr_reader :anchors 10 | 11 | def initialize 12 | reset 13 | end 14 | 15 | def create(id, level) 16 | anchor = heading_slug(id) 17 | 18 | unless unique?(anchor) 19 | anchor = prefixed_by_parent(anchor, level) 20 | end 21 | 22 | unless unique?(anchor) 23 | anchor = suffixed_with_number(anchor) 24 | end 25 | 26 | @anchors << Anchor.new(anchor, level) 27 | 28 | anchor 29 | end 30 | 31 | def reset 32 | @anchors = [] 33 | end 34 | 35 | private 36 | 37 | def prefixed_by_parent(anchor, level) 38 | closest_parent = @anchors.reverse.find { |a| a.level < level } 39 | if closest_parent.nil? 40 | anchor 41 | else 42 | [closest_parent.id, anchor].join("-") 43 | end 44 | end 45 | 46 | def suffixed_with_number(text) 47 | number = 2 48 | anchor = "#{text}-#{number}" 49 | 50 | until unique?(anchor) 51 | anchor = "#{text}-#{number}" 52 | number += 1 53 | end 54 | 55 | anchor 56 | end 57 | 58 | def unique?(value) 59 | @anchors.none? { |a| a.id == value } 60 | end 61 | 62 | # https://github.com/vmg/redcarpet/blob/820dadb98b3720811cc20c5570a5d43c796c85fc/ext/redcarpet/html.c#L274-L305 63 | def heading_slug(text) 64 | text 65 | .downcase 66 | .strip 67 | .gsub(%r{]+?>}, "") # Remove HTML tags 68 | .gsub(/[^0-9a-z]+/, "-") # Replace non-alphanumeric characters with dashes 69 | .gsub(/\A-+|-+\z/, "") # Remove trailing dashes 70 | end 71 | end 72 | end 73 | -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/modules.js: -------------------------------------------------------------------------------- 1 | (function ($, root) { 2 | 'use strict' 3 | root.GOVUK = root.GOVUK || {} 4 | GOVUK.Modules = GOVUK.Modules || {} 5 | 6 | GOVUK.modules = { 7 | find: function (container) { 8 | var modules 9 | var moduleSelector = '[data-module]' 10 | var component = container || $('body') 11 | 12 | modules = component.find(moduleSelector) 13 | 14 | // Container could be a module too 15 | if (component.is(moduleSelector)) { 16 | modules = modules.add(component) 17 | } 18 | 19 | return modules 20 | }, 21 | 22 | start: function (container) { 23 | var modules = this.find(container) 24 | 25 | for (var i = 0, l = modules.length; i < l; i++) { 26 | var module 27 | var element = $(modules[i]) 28 | var type = camelCaseAndCapitalise(element.data('module')) 29 | var started = element.data('module-started') 30 | 31 | if (typeof GOVUK.Modules[type] === 'function' && !started) { 32 | module = new GOVUK.Modules[type]() 33 | module.start(element) 34 | element.data('module-started', true) 35 | } 36 | } 37 | 38 | // eg selectable-table to SelectableTable 39 | function camelCaseAndCapitalise (string) { 40 | return capitaliseFirstLetter(camelCase(string)) 41 | } 42 | 43 | // http://stackoverflow.com/questions/6660977/convert-hyphens-to-camel-case-camelcase 44 | function camelCase (string) { 45 | return string.replace(/-([a-z])/g, function (g) { 46 | return g[1].toUpperCase() 47 | }) 48 | } 49 | 50 | // http://stackoverflow.com/questions/1026069/capitalize-the-first-letter-of-string-in-javascript 51 | function capitaliseFirstLetter (string) { 52 | return string.charAt(0).toUpperCase() + string.slice(1) 53 | } 54 | } 55 | } 56 | })(jQuery, window) 57 | -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/_govuk/modules.js: -------------------------------------------------------------------------------- 1 | (function ($, root) { 2 | 'use strict' 3 | root.GOVUK = root.GOVUK || {} 4 | GOVUK.Modules = GOVUK.Modules || {} 5 | 6 | GOVUK.modules = { 7 | find: function (container) { 8 | var modules 9 | var moduleSelector = '[data-module]' 10 | var component = container || $('body') 11 | 12 | modules = component.find(moduleSelector) 13 | 14 | // Container could be a module too 15 | if (component.is(moduleSelector)) { 16 | modules = modules.add(component) 17 | } 18 | 19 | return modules 20 | }, 21 | 22 | start: function (container) { 23 | var modules = this.find(container) 24 | 25 | for (var i = 0, l = modules.length; i < l; i++) { 26 | var module 27 | var element = $(modules[i]) 28 | var type = camelCaseAndCapitalise(element.data('module')) 29 | var started = element.data('module-started') 30 | 31 | if (typeof GOVUK.Modules[type] === 'function' && !started) { 32 | module = new GOVUK.Modules[type]() 33 | module.start(element) 34 | element.data('module-started', true) 35 | } 36 | } 37 | 38 | // eg selectable-table to SelectableTable 39 | function camelCaseAndCapitalise (string) { 40 | return capitaliseFirstLetter(camelCase(string)) 41 | } 42 | 43 | // http://stackoverflow.com/questions/6660977/convert-hyphens-to-camel-case-camelcase 44 | function camelCase (string) { 45 | return string.replace(/-([a-z])/g, function (g) { 46 | return g[1].toUpperCase() 47 | }) 48 | } 49 | 50 | // http://stackoverflow.com/questions/1026069/capitalize-the-first-letter-of-string-in-javascript 51 | function capitaliseFirstLetter (string) { 52 | return string.charAt(0).toUpperCase() + string.slice(1) 53 | } 54 | } 55 | } 56 | })(jQuery, window) 57 | -------------------------------------------------------------------------------- /content/taxonomies/index.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Taxonomies 3 | weight: 700 4 | dateAdded: 2022-03-17 5 | dateUpdated: 2022-03-18 6 | --- 7 | 8 | # Taxonomies 9 | 10 | ## Description: 11 | 12 | A taxonomy is a way of naming and classifying terms to make them fit into category groups, according to the similarities and differences between the terms. 13 | 14 | The groups they fit into form part of a larger system of groups, which altogether make a structure of terms that all relate to each other. 15 | 16 | Taxonomies are useful for discussing and deciding how terms are related, which can help us more easily retrieve and analyse datasets. Common adoption of the taxonomies in this repository will support data sharing across government. 17 | 18 | The data taxonomies listed here are either currently being assessed (In review) or have been endorsed (Endorsed) by the Data Standards Authority as suitable to be used across government. 19 | 20 | The Taxonomy Catalogue currently contains the following taxonomies: 21 | 22 |
    23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | <% current_resource.children.reject{|page| page.data.exclude_from_list}.sort_by{ |page| get_link_text(page).downcase }.each do |f| %> 32 | <% if f.content_type.include? "html" %> 33 | 34 | 35 | 36 | 37 | <% end %> 38 | <% end %> 39 | 40 |
    NameStatus
    <%= link_to get_link_text(f), f.path.delete_prefix("taxonomies/") %> <%= display_status(:taxonomies, f.data.status) %>
    41 |
    42 | -------------------------------------------------------------------------------- /content/standards/index.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Standards 3 | weight: 90 4 | dateAdded: 2020-12-16 5 | dateUpdated: 2021-04-26 6 | --- 7 | 8 | # Data Standards 9 | 10 | ## Description: 11 | The Data Standards Catalogue currently contains the standards listed below. We also have a list of [external standards catalogues](/standards/external-standards.html). 12 | 13 |
    14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | <% current_resource.children.reject{|page| page.data.exclude_from_list}.sort_by{ |page| get_link_text(page).downcase }.each do |f| %> 25 | <% if f.content_type.include? "html" %> 26 | 27 | 32 | 39 | 40 | 41 | 42 | <% end %> 43 | <% end %> 44 | 45 |
    NameTagsStatusDate updated
    28 | <%= link_to get_link_text(f), f.path.delete_prefix("standards/") %> 29 |

    30 | <%= f.data.short_description %> 31 |     		33 |
      34 | <% f.data.tags.each do |g| %> 35 |
    • <%= display_tags(g) %>
      • 36 | <% end %> 37 |
    38 |     		<%= display_status(:standard, f.data.endorsement_status_events.last.status) %><%= display_status(:standard, f.data.endorsement_status_events.last.date) %>
    46 |
    47 | -------------------------------------------------------------------------------- /content/standards/UKGemini/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: UK Gemini 3 | contraction: GEMINI 4 | specification_url: https://www.agi.org.uk/gemini/40-gemini/1037-uk-gemini-standard-and-inspire-implementing-rules/ 5 | tags: 6 | - semantics 7 | - metadata 8 | maintainer_id: agi 9 | licence_id: CC-BY-4.0 10 | endorsement_status_events: 11 | - status: endorsed 12 | date: "2020-12-01" 13 | short_description: UK GEMINI is the UK geographic metadata standard 14 | --- 15 | 16 | 17 | 18 | "GEMINI" is the UK geographic metadata standard. It provides guidance on how to publish geographic metadata in a way that conforms to relevant ISO standards and the UK's implementation of the European INSPIRE regulations. UK GEMINI (GEo-spatial Metadata INteroperability Initiative) is a specification for a set of metadata elements for describing geospatial data resources. It has been produced and is maintained by the Standards Committee. 19 | 20 | 21 | ### Use Case: 22 | - [https://www.agi.org.uk/agi-groups/standards-committee/why-uk-gemini-why-not-just-have-the-inspire-technical-guidance](https://www.agi.org.uk/agi-groups/standards-committee/why-uk-gemini-why-not-just-have-the-inspire-technical-guidance) 23 | 24 | ### Case Studies: 25 | - [https://www.agi.org.uk/about/resources/category/81-gemini?download=436:medin-a-case-study-on-how-gemini-has-been-implemented-for-marine-data](https://www.agi.org.uk/about/resources/category/81-gemini?download=436:medin-a-case-study-on-how-gemini-has-been-implemented-for-marine-data) 26 | - [https://www.agi.org.uk/about/resources/category/81-gemini?download=440:agi-gemini-2-3-case-study-astun-technology](https://www.agi.org.uk/about/resources/category/81-gemini?download=440:agi-gemini-2-3-case-study-astun-technology) 27 | 28 | ### Guidance: 29 | - [https://www.agi.org.uk/agi-groups/standards-committee/uk-gemini](https://www.agi.org.uk/agi-groups/standards-committee/uk-gemini) 30 | 31 | ### How To: 32 | - [https://www.agi.org.uk/agi-groups/standards-committee/uk-gemini/40-gemini/1037-uk-gemini-standard-and-inspire-implementing-rules](https://www.agi.org.uk/agi-groups/standards-committee/uk-gemini/40-gemini/1037-uk-gemini-standard-and-inspire-implementing-rules) 33 | -------------------------------------------------------------------------------- /standards-catalogue/source/layouts/_footer.erb: -------------------------------------------------------------------------------- 1 | 43 | -------------------------------------------------------------------------------- /projects/data-service-standard/improving-data-guidance-in-service-manual.md: -------------------------------------------------------------------------------- 1 | # Improving data guidance in the Service Manual 2 | 3 | In March and April of 2021, the Data Standards Authority (DSA) undertook five workshops with a total of around 100 data experts from across government, as part of work to improve standards and assurance of government services’ data-related work. 4 | 5 | The data experts provided extensive points and ideas on how to improve data in government. Themes included data quality, architecture, interoperability and information sources used amongst many others. 6 | 7 | The DSA is now collaborating with the Community-led [Service Standard](https://www.gov.uk/service-manual/service-standard) and [Service Manual](https://www.gov.uk/service-manual) team, with a focus on the Service Manual’s end users, researching the needs of data-related standards and guidance. These users include people with expert data capabilities, but also data newcomers. 8 | 9 | We aim to discover what data-related guidance is needed to improve the Service Manual, help service teams meet the requirements of the Service Standard, and support the priorities identified by data experts. 10 | 11 | The kinds of things we’re looking to understand about our end users include: 12 | * who the audience is for data guidance 13 | * current data practices 14 | * gaps in existing data guidance 15 | * barriers to implementing current data guidance 16 | 17 | We’ll look at more specific questions, like: 18 | * What drives users to data-related guidance? What are they trying to find out? 19 | * What are users’ responsibilities relating to data architecture, life cycle, management and * quality control? 20 | * What works well and less well about how teams collect, store, process, share, and publish data? 21 | * Are teams aware of the technical, legal, and ethical standards that they need to meet? 22 | 23 | The findings will help us ensure guidance is realistic and reflects the needs of people working with data and makes sense to people with all levels of data capability. 24 | 25 | A DSA team member will attend all research sessions as an observer, because user research is a team sport. 26 | 27 | We will keep communities and stakeholders up to date by working in the open and sharing developing timelines, information, content and artefacts. 28 | -------------------------------------------------------------------------------- /standards-catalogue/docs/getting_started.md: -------------------------------------------------------------------------------- 1 | # Getting started 2 | 3 | ## About this project 4 | 5 | The DSA site is built with [Middleman][middleman], a static-site generator. 6 | 7 | Content for pages is based on Markdown files located in the `source` directory. 8 | 9 | ## Before you start 10 | 11 | - [Setup rbenv][setup-rbenv] and install the Ruby version specified in [`.ruby-version`][ruby-version] 12 | - [Setup Node][setup-node] 13 | 14 | ## Local setup 15 | 16 | 1. Clone the git repostory: `git clone git@github.com:alphagov/data-standards-authority.git` 17 | 1. Navigate to the project directory: `cd standards-catalogue` 18 | 1. Install gems: `bundle install` 19 | 1. Install JavaScript dependencies: `npm install` 20 | 1. Run the test suite to verify your setup: `bundle exec rspec` 21 | 22 | ## Docker setup 23 | 24 | If you have Docker available on your machine, and would prefer not to setup the 25 | project dependencies locally, you can run: 26 | 27 | ``` 28 | bin/docker_serve 29 | ``` 30 | 31 | By default this will build and serve the site on host port 4567. You can 32 | navigate to `http://localhost:4567` to view the site. 33 | 34 | ## Preview your changes locally 35 | 36 | To preview the DSA site locally run: 37 | 38 | ```sh 39 | bundle exec middleman server 40 | ``` 41 | 42 | See the generated website on `http://localhost:4567` in your browser. Any 43 | content changes you make to the website will be updated in real time. 44 | 45 | To shut down the Middleman instance running on your machine, use `ctrl+C`. 46 | 47 | ## Build 48 | 49 | To build the static website run: 50 | 51 | ```sh 52 | bundle exec middleman build 53 | ``` 54 | 55 | If the build fails, run it again with the `--verbose` flag to get detailed error 56 | messages to help with finding the problem. 57 | 58 | ## Publishing 59 | 60 | [Create a pull request][pull-request] to make changes to the site. When the pull 61 | request is merged it'll be published automatically. See the 62 | [deployment documentation][deployment] for further details. 63 | 64 | [middleman]: https://middlemanapp.com/ 65 | [setup-rbenv]: https://github.com/rbenv/rbenv#installation 66 | [setup-node]: https://nodejs.org/en/download/ 67 | [ruby-version]: ../.ruby-version 68 | [pull-request]: https://gds-way.cloudapps.digital/standards/pull-requests.html 69 | [deployment]: ./deployment.md 70 | -------------------------------------------------------------------------------- /standards-catalogue/lib/govuk_tech_docs/meta_tags.rb: -------------------------------------------------------------------------------- 1 | module GovukTechDocs 2 | class MetaTags 3 | def initialize(config, current_page) 4 | @config = config 5 | @current_page = current_page 6 | end 7 | 8 | def tags 9 | all_tags = { 10 | "description" => page_description, 11 | "google-site-verification" => google_site_verification, 12 | "robots" => robots, 13 | "twitter:card" => "summary", 14 | "twitter:domain" => URI.parse(host).host, 15 | "twitter:image" => page_image, 16 | "twitter:title" => browser_title, 17 | "twitter:url" => canonical_url, 18 | } 19 | 20 | Hash[all_tags.select { |_k, v| v }] 21 | end 22 | 23 | # OpenGraph uses the non-standard property attribute instead of name, so we 24 | # return these separately so we can output them correctly. 25 | def opengraph_tags 26 | all_opengraph_tags = { 27 | "og:description" => page_description, 28 | "og:image" => page_image, 29 | "og:site_name" => site_name, 30 | "og:title" => page_title, 31 | "og:type" => "object", 32 | "og:url" => canonical_url, 33 | } 34 | 35 | Hash[all_opengraph_tags.select { |_k, v| v }] 36 | end 37 | 38 | def browser_title 39 | [page_title, site_name].select(&:present?).uniq.join(" - ") 40 | end 41 | 42 | def canonical_url 43 | "#{host}#{current_page.url}" 44 | end 45 | 46 | private 47 | 48 | attr_reader :config, :current_page 49 | 50 | def page_image 51 | "#{host}/images/govuk-large.png" 52 | end 53 | 54 | def site_name 55 | config[:tech_docs][:full_service_name] || config[:tech_docs][:service_name] 56 | end 57 | 58 | def page_description 59 | locals[:description] || frontmatter[:description] 60 | end 61 | 62 | def page_title 63 | locals[:title] || frontmatter[:title] 64 | end 65 | 66 | def robots 67 | "noindex" if config[:tech_docs][:prevent_indexing] || frontmatter[:prevent_indexing] 68 | end 69 | 70 | def google_site_verification 71 | config[:tech_docs][:google_site_verification] 72 | end 73 | 74 | def host 75 | config[:tech_docs][:host].to_s 76 | end 77 | 78 | def locals 79 | current_page.metadata[:locals] 80 | end 81 | 82 | def frontmatter 83 | current_page.data 84 | end 85 | end 86 | end 87 | -------------------------------------------------------------------------------- /content/guidance/apimanagement/APIM-Retirement.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: APIM - 06 - Retirement 3 | weight: 833 4 | keywords: 'API Management' 5 | identifier: DSA-003 6 | name: APIManagement 7 | organisation: Data Standards Authority 8 | author_email: api-programme@digital.cabinet-office.gov.uk 9 | status: Draft 10 | startDate: 2021-03-23 11 | dateAdded: 2021-03-23 12 | dateUpdated: 2021-04-28 13 | --- 14 | 15 | ## Retirement 16 | 17 | 18 | _This is a DRAFT document for discussion. This is not finalised. All aspects of this document are subject to change. Please leave comments on any aspect of it._ 19 | 20 | #### Contents: 21 | - [01 - Introduction](APIM-Introduction.html) 22 | - [02 - Design](APIM-Design.html) 23 | - [03 - Deployment](APIM-Deployment.html) 24 | - [04 - Management](APIM-Management.html) 25 | - [05 - Discovery](APIM-Discovery.html) 26 | - [06 - Retirement](APIM-Retirement.html) 27 | 28 | 29 | 30 | Something that is often overlooked when developing and managing APIs is planning how to take them out of service when they are no longer needed. People often use the terms retirement, deprecation, sunsetting, or decommissioning interchangeably. 31 | 32 | It may be useful to put together an API retirement workflow or checklist for your organisation to help teams follow a consistent process. Below is an example of what this might look like. 33 | 34 | 1. Use analytics to support your case for deprecation 35 | 2. Publish a blog post to explain the reasons, and offer alternatives where possible 36 | 3. Add a deprecation notice to documentation, with the date it will happen 37 | 4. Disable sign ups in self-service to stop new users accessing the service 38 | 5. Email subscribed users with the date of deprecation - as the date approaches, emails should get more frequent 39 | 6. Use Sunset or Deprecated HTTP headers, with a link to the documentation and blog post 40 | 7. Wait and see how usage changes - make sure it’s dropping, and reach out to any remaining active users 41 | 8. Agree an acceptable number of active users at retirement 42 | 9. Keep the API in retired status for a while - this could be months or years 43 | 44 | 45 | 46 | #### Contents: 47 | - [01 - Introduction](APIM-Introduction.html) 48 | - [02 - Design](APIM-Design.html) 49 | - [03 - Deployment](APIM-Deployment.html) 50 | - [04 - Management](APIM-Management.html) 51 | - [05 - Discovery](APIM-Discovery.html) 52 | - [06 - Retirement](APIM-Retirement.html) 53 | 54 | 55 | [Next](APIM-Introduction.html) 56 | -------------------------------------------------------------------------------- /standards-catalogue/source/layouts/core.erb: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | <%= meta_tags.browser_title %> 9 | 10 | <%= stylesheet_link_tag :manifest %> 11 | 12 | 13 | 14 | <% meta_tags.tags.each do |name, content| %> 15 | <%= tag :meta, name: name, content: content %> 16 | <% end %> 17 | 18 | <% meta_tags.opengraph_tags.each do |property, content| %> 19 | <%= tag :meta, property: property, content: content %> 20 | <% end %> 21 | 22 | <%= yield_content :head %> 23 | 24 | 25 | 26 | 27 | 28 |
    29 |
    30 | Skip to main content 31 | 32 | <%= partial 'layouts/header' %> 33 |
    34 | 35 |
    > 36 |
    37 | 43 |
    44 | <%= yield %> 45 |
    46 | 47 | 57 | 58 |
    59 |
    60 | <%= partial "layouts/footer" %> 61 |
    62 | 63 | <%= javascript_include_tag :application %> 64 | 65 | 66 | -------------------------------------------------------------------------------- /content/standards/UPRN/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Unique Property Reference Number 3 | contraction: UPRN 4 | specification_url: https://www.gov.uk/government/publications/open-standards-for-government/identifying-property-and-street-information 5 | tags: 6 | - identification 7 | - geospatial 8 | - common-reference-data 9 | maintainer_id: ordnance-survey 10 | licence_id: OGL-UK-3.0 11 | endorsement_status_events: 12 | - status: endorsed 13 | date: "2020-12-16" 14 | short_description: 15 | --- 16 | 17 | 18 | 19 | UPRN stands for Unique Property Reference Number and was created by the Ordnance Survey (OS). It consists of numbers of up to 12 digits in length. Local governments in the UK have allocated a unique number for each land or property. 20 | 21 | 22 | ## Use Cases: 23 | - [https://www.geoplace.co.uk/addresses-streets/addresses/the-uprn](https://www.geoplace.co.uk/addresses-streets/addresses/the-uprn) 24 | - [https://www.geoplace.co.uk/downloads/Linking-People-to-Places-with-Unique-Identifiers.pdf](https://www.geoplace.co.uk/downloads/Linking-People-to-Places-with-Unique-Identifiers.pdf) 25 | 26 | ## Case Studies: 27 | - [https://blog.geo.place/2020/03/26/what-can-food-hygiene-tell-us-about-fire-safety/](https://blog.geo.place/2020/03/26/what-can-food-hygiene-tell-us-about-fire-safety/) 28 | - [https://www.ukauthority.com/articles/connecting-fire-and-flood-risk-with-place-through-uprns/](https://www.ukauthority.com/articles/connecting-fire-and-flood-risk-with-place-through-uprns/) 29 | - [https://www.geoplace.co.uk/addresses-streets/addresses/addressing-in-the-uk](https://www.geoplace.co.uk/addresses-streets/addresses/addressing-in-the-uk) 30 | - [https://www.geoplace.co.uk/downloads/Address-and-street-data-a-common-standard-for-digital-transformation.pdf](https://www.geoplace.co.uk/downloads/Address-and-street-data-a-common-standard-for-digital-transformation.pdf) 31 | - [https://www.ordnancesurvey.co.uk/business-government/products/addressbase-premium](https://www.ordnancesurvey.co.uk/business-government/products/addressbase-premium) 32 | 33 | ## Guidance: 34 | - [https://www.ordnancesurvey.co.uk/business-government/tools-support/open-mastermap-programme/open-id-policy](https://www.ordnancesurvey.co.uk/business-government/tools-support/open-mastermap-programme/open-id-policy) 35 | 36 | ## How To: 37 | - [https://uprn.uk/](https://uprn.uk/) 38 | - [https://s3.eu-west-1.amazonaws.com/static.geoplace.co.uk/downloads/British-Standard-7666-2006.pdf?version=1.1](https://s3.eu-west-1.amazonaws.com/static.geoplace.co.uk/downloads/British-Standard-7666-2006.pdf?version=1.1) 39 | -------------------------------------------------------------------------------- /standards-catalogue/lib/schemaorg.rb: -------------------------------------------------------------------------------- 1 | module SchemaOrg 2 | class Base 3 | attr_accessor :obj 4 | 5 | # Middleman uses ActiveSupport's JSON encoder, which requires `as_json` to produce the hash representation of the object 6 | def as_json(_options = {}) 7 | @obj 8 | end 9 | end 10 | 11 | class Standard < SchemaOrg::Base 12 | def initialize(data, page_data) 13 | super() 14 | 15 | categories = categories(data, page_data) 16 | licence_info = SchemaOrg::Licence.new(data, page_data.licence_id) 17 | maintainer_info = SchemaOrg::Organisation.new(data, page_data.maintainer_id) 18 | endorsement_status = page_data.endorsement_status_events.last.status 19 | specification = SchemaOrg::Specification.new(page_data.name, page_data.specification_url) 20 | 21 | @obj = { 22 | "@context": "https://schema.org/", 23 | "@type": "Thing", 24 | "name": page_data.name, 25 | "isBasedOn": specification, 26 | "license": licence_info, # this needs to be US spelling 27 | "category": categories, 28 | "maintainer": maintainer_info, 29 | "endorsementStatus": endorsement_status, 30 | } 31 | 32 | if page_data.contraction 33 | @obj["contraction"] = page_data.contraction 34 | end 35 | end 36 | 37 | private 38 | 39 | def categories(data, page_data) 40 | page_data.tags.map do |tag| 41 | data.tags[tag].name 42 | end 43 | end 44 | end 45 | 46 | class Organisation < SchemaOrg::Base 47 | def initialize(data, organisation_id) 48 | super() 49 | 50 | organisation = data.organisations[organisation_id] 51 | 52 | @obj = { 53 | "@context": "https://schema.org", 54 | "@type": "Organization", 55 | "name": organisation.name, 56 | "url": organisation.url, 57 | } 58 | end 59 | end 60 | 61 | class Licence < SchemaOrg::Base 62 | def initialize(data, licence_id) 63 | super() 64 | 65 | licence = data.licences[licence_id] 66 | @obj = { 67 | "@context": "https://schema.org", 68 | "@type": "CreativeWork", 69 | "name": licence.name, 70 | } 71 | @obj["url"] = licence.url if licence.url 72 | end 73 | end 74 | 75 | class Specification < SchemaOrg::Base 76 | def initialize(name, specification_url) 77 | super() 78 | 79 | @obj = { 80 | "@context": "https://schema.org", 81 | "@type": "CreativeWork", 82 | "name": name, 83 | "url": specification_url, 84 | } 85 | end 86 | end 87 | end 88 | -------------------------------------------------------------------------------- /adr/0003-make-contraction-optional.md: -------------------------------------------------------------------------------- 1 | --- 2 | creation_date: 2021-11-19 3 | decision_date: 2021-11-19 4 | status: accepted 5 | --- 6 | # Make the `contraction` field optional in standards 7 | 8 | ## Context 9 | 10 | While doing an initial handover with members of the DSA team after adopting the schema as defined in _ADR-0001_, a question was raised about whether the contraction was required. 11 | 12 | Despite us previously deciding that this would be required, we didn't fully consider the case where a common contraction is not in use. 13 | 14 | ## Decision 15 | 16 | We have decided to make it optional, as it does not always provide value by having one there, especially if it is not a commonly used contraction, but was instead added by us just to make it pass validation. 17 | 18 | The Entity Relationship Diagram can be seen below: 19 | 20 | ![Entity Relationship Diagram for Standards](https://kroki.io/erd/svg/eNqlkk1rhDAQhu_5FWGPq3vYa289eCgtKu6WUkSWaTIroRptEltK8b83iUrVLQulh4TM5Mk7X8kPBiQHxQuyFRylEWeBikiokX7RCl6wuqEbbZSQZUgVvnVCId_QnrBGGgXMiEZekO5et8isGANHnDpVzShrLcU4aqZEuxKrQb3y5kM6IjBQngQnQSUYSob-XIOQxi5UziR59G4rKEigx6I8ZA3TaXfkYGxVk_oUP6TOv-nt-4NH_9yKWfZW5AjlPxUehhIXKj95X7zvxwhXAPPZzgCUXZ0naRSHaZak2V10vM2ew8f4Pk6e4sLiflqzYfnmJKoEKbSf528FXgm_1ltckukL0v1ut6WTtXAH1HZ14dnTsUsr7zzLlYT_HcTvAzuMm3wDKigIXA==) 21 | 22 |
    23 | 24 | Entity Relationship Diagram (raw) 25 | 26 | ```erd 27 | [Standard] 28 | *identifier 29 | name { label: "string, required" } 30 | contraction { label: "string" } 31 | specification_url { label: "url, required" } 32 | description { label: "markdown" } 33 | +tag_id 34 | +licence_id 35 | +maintainer_id 36 | 37 | [Event] 38 | +standard_id 39 | +status_id 40 | date {label: "required, date"} 41 | 42 | [Status] 43 | *identifier 44 | name { label: "string, required" } 45 | description 46 | 47 | [Tag] 48 | *identifier 49 | name { label: "string, required" } 50 | description 51 | 52 | [Licence] 53 | *identifier {label: "string, required"} 54 | name {label: "string, required"} 55 | type {label: "enum[OPEN,PROPRIETARY,UNKNOWN]"} 56 | url {label: "url"} 57 | 58 | [Organisation] 59 | *identifier 60 | name {label: "string, required"} 61 | url {label: "url, required"} 62 | 63 | Standard 1--* Standard 64 | Standard 1--+ Tag 65 | Standard 1--1 Licence 66 | Standard 1--1 Organisation 67 | Standard 1--+ Event 68 | Event 1--1 Status 69 | ``` 70 | 71 |
    72 | 73 | ## Consequences 74 | 75 | The author will need to determine whether there is a contraction currently in use that makes sense. 76 | 77 | Existing contractions that were defined by us for the purpose of schema validation will be removed. 78 | -------------------------------------------------------------------------------- /content/taxonomies/soc/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: UK Standard Occupation Classification 3 | contraction: SOC 4 | status: endorsed 5 | --- 6 | The evaluation document is available [in PDF format](/taxonomies/soc/Taxonomy_Evaluation_Document_SOC_FINAL.pdf) and [in ODT format](/taxonomies/soc/Taxonomy_Evaluation_Document_SOC_FINAL.odt). 7 | 8 | SOC is hierarchical in structure and is used to classify occupations (jobs) by skill level and specialisation. Skill levels are approximated by the length of time necessary for a person to become fully competent in the performance of the tasks associated with a job, including training and qualifications. SOC 2020 is categorised into four skill levels. 9 | 10 | SOC is used to classify occupations to most sources of occupational statistics in the UK. SOC 2020 is also used by other organisations for their own purposes. 11 | 12 | Methodology on the current SOC 2020 is available from SOC 2020 Volume 1 - structure and descriptions of unit groups. ONS publish tables showing the relationship between the previous and new classification. The current relationship tables for SOC2010 and SOC2020 and the user guide are available from here. 13 | 14 | ### Documentation: 15 | - [https://www.ons.gov.uk/methodology/classificationsandstandards/standardoccupationalclassificationsoc ](https://www.ons.gov.uk/methodology/classificationsandstandards/standardoccupationalclassificationsoc) 16 | 17 | ### Metadata: 18 | - The [SOC index](https://www.ons.gov.uk/file?uri=/methodology/classificationsandstandards/standardoccupationalclassificationsoc/soc2020/soc2020volume2codingrulesandconventions/soc2020volume2thecodingindexexcel011021.xlsx) includes a ‘FILE SPEC’ tab that includes information on the excel workbook. 19 | 20 | ### Crosswalks and limitations: 21 | The major group structure is a set of broad occupational categories which are designed to bring together groups which are similar in terms of qualifications, training, skills and experience. These categories aim to align SOC as far as possible with the International Standard Classification of Occupations (ISCO). 22 | SOC Volume 2 – the coding index maps directly to ISCO08 by job title 23 | 24 | Some existing users of SOC have expressed that the existing structure, with the lowest level being 4 digits, is not sufficiently granular to meet their needs. More information on the SOC-extension project is available here. 25 | 26 | ### Contact: 27 | 28 | Owned by the Office for National Statistics (ONS). The Classifications Branch within ONS is responsible for its revision every 10 years. 29 | 30 | General enquiries: occupation.information@ons.gov.uk 31 | 32 | Enquiries about revisions: socrevision@ons.gov.uk 33 | 34 | 35 | -------------------------------------------------------------------------------- /content/taxonomies/onet/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: The Occupational Information Network Taxonomy 3 | contraction: O*NET 4 | documentation: https://www.onetcenter.org/taxonomy.html 5 | status: endorsed 6 | --- 7 | 8 | The evaluation document is available [in PDF format](/taxonomies/onet/Taxonomy_Evaluation_Document_ONET_FINAL.pdf) and [in ODT format](/taxonomies/onet/Taxonomy_Evaluation_Document_ONET_FINAL.odt). 9 | 10 | The O\*NET (The Occupational Information Network) programme is the US's primary source of occupational information. The skill taxonomy within it categorises skill areas at the top most level as Basic Skills & Cross Functional Skills and further into 7 mid-level and finally comprehensively defines 46 lower level skill areas (e.g. Reading, decision making etc.). 11 | 12 | The system measures job requirements covering around 1,000 occupations. O\*Net aligns to the Standard Occupational Classification (SOC) system, a US federal statistical standard used to classify workers into occupational categories for the purpose of collecting, calculating, or disseminating data. 13 | 14 | The taxonomy is used by organisations outside of the US, for example Organisation for Economic Co-Cooperation Development (OECD). 15 | O\*net is provided open source and is available to download free of charge. [Methodology information is available here](https://www.onetcenter.org/search?s=methodology). 16 | O\*net has a strong and continuous revision and maintenance process in place. https://www.onetcenter.org/dl_files/TaxonomyDev2019.pdf 17 | 18 | There is also a [machine readable file](https://www.onetcenter.org/linkToOnet.html#machine). 19 | 20 | ### Documentation: 21 | - [https://www.onetcenter.org/taxonomy.html](https://www.onetcenter.org/taxonomy.html) 22 | 23 | ### Metadata: 24 | - [https://www.onetcenter.org/dictionary/26.1/excel/occupation_level_metadata.html](https://www.onetcenter.org/dictionary/26.1/excel/occupation_level_metadata.html) 25 | 26 | ### Crosswalks and limitations: 27 | The taxonomy has an occupational classification that aligns to ISCO. There is a cross walk to UK SOC 2010 and one in development for UK SOC 2020. https://www.onetcenter.org/crosswalks.html 28 | 29 | O\*Net was not developed for the UK market. UK and US job roles may differ, reflecting technology usage, commercial patterns, industrial profile, legislation, regulation and the economy. 30 | 31 | The O\*NET-SOC occupational hierarchy does not map directly to UK SOC 2010, and some granularity is lost, with some occupations lacking a match or relying heavily on averaging. O\*NET does not provide any link between skills and UK qualifications. 32 | 33 | ### Contact: 34 | 35 | US point of contact: National Center for O\*NET Development onet@onetcenter.org 36 | 37 | UK point of contact: Classifications Unit, Office for National Statistics occupation.information@ons.gov.uk 38 | 39 | -------------------------------------------------------------------------------- /content/guidance/apimanagement/APIM-Management.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: APIM - 04 - Management 3 | weight: 833 4 | keywords: 'API Management' 5 | identifier: DSA-003 6 | name: APIManagement 7 | organisation: Data Standards Authority 8 | author_email: api-programme@digital.cabinet-office.gov.uk 9 | status: Draft 10 | startDate: 2021-03-23 11 | dateAdded: 2021-03-23 12 | dateUpdated: 2021-04-28 13 | --- 14 | 15 | ## Management tools (API Gateway) 16 | 17 | 18 | _This is a DRAFT document for discussion. This is not finalised. All aspects of this document are subject to change. Please leave comments on any aspect of it._ 19 | 20 | #### Contents: 21 | - [01 - Introduction](APIM-Introduction.html) 22 | - [02 - Design](APIM-Design.html) 23 | - [03 - Deployment](APIM-Deployment.html) 24 | - [04 - Management](APIM-Management.html) 25 | - [05 - Discovery](APIM-Discovery.html) 26 | - [06 - Retirement](APIM-Retirement.html) 27 | 28 | 29 | The day to day operations of API service management are usually handled by an API gateway. Generally, an API gateway service acts as a proxy for APIs, and allows commodity services (for example, network access, security and authentication, throttling and rate limiting, logging and monitoring) to be provisioned centrally, for all the APIs using the service. 30 | 31 | 32 | Many organisations don’t put an API gateway into production until they have several APIs in use. However, you should consider implementing one at the very beginning of an API programme. 33 | 34 | 35 | Doing this will allow you to: 36 | 37 | - standardise how APIs use central services such as network access, security and authentication, throttling and rate limiting, logging and monitoring 38 | 39 | - lower developer costs and reduce time to value, since you won’t need to rebuild these services for each new API 40 | 41 | - mandate minimum standards of security, access control and monitoring, while providing an easy way for developers to meet them 42 | 43 | 44 | While adding an API gateway does mean you will need to deploy and manage another service, it reduces complexity of the API estate and introduces a consistent front end for services. 45 | 46 | 47 | There are many different API gateway products available, both open source and proprietary. They will often include elements for a dev portal and/or a catalogue. You can read more about these further in this guidance. 48 | 49 | 50 | At a minimum, an API gateway should provide: 51 | 52 | - user and application authentication 53 | 54 | - rate limiting and throttling inbound requests 55 | 56 | - logging and reporting 57 | 58 | 59 | #### Contents: 60 | - [01 - Introduction](APIM-Introduction.html) 61 | - [02 - Design](APIM-Design.html) 62 | - [03 - Deployment](APIM-Deployment.html) 63 | - [04 - Management](APIM-Management.html) 64 | - [05 - Discovery](APIM-Discovery.html) 65 | - [06 - Retirement](APIM-Retirement.html) 66 | 67 | 68 | [Next](APIM-Discovery.html) 69 | -------------------------------------------------------------------------------- /standards-catalogue/lib/govuk_tech_docs/contribution_banner.rb: -------------------------------------------------------------------------------- 1 | module GovukTechDocs 2 | # Helper included 3 | module ContributionBanner 4 | def source_urls 5 | SourceUrls.new(current_page, config) 6 | end 7 | end 8 | 9 | class SourceUrls 10 | attr_reader :current_page, :config 11 | 12 | def initialize(current_page, config) 13 | @current_page = current_page 14 | @config = config 15 | end 16 | 17 | def view_source_url 18 | override_from_page || source_from_yaml_file || source_from_file 19 | end 20 | 21 | def report_issue_url 22 | url = config[:source_urls]&.[](:report_issue_url) 23 | 24 | params = { 25 | body: "Feedback on '#{current_page.data.title}' (#{config[:tech_docs][:host]}#{current_page_url})", 26 | } 27 | 28 | if url.nil? 29 | url = "#{repo_url}/issues/new" 30 | params["labels"] = "bug" 31 | params["title"] = "Re: '#{current_page.data.title}'" 32 | else 33 | params["subject"] = "Re: '#{current_page.data.title}'" 34 | end 35 | "#{url}?#{URI.encode_www_form(params)}" 36 | end 37 | 38 | def repo_url 39 | "https://github.com/#{config[:tech_docs][:github_repo]}" 40 | end 41 | 42 | def repo_branch 43 | config[:tech_docs][:github_branch] || "main" 44 | end 45 | 46 | def project_name 47 | config[:tech_docs][:project_name] || "standards-catalogue" 48 | end 49 | 50 | # If an author_email is specified in the frontmatter, use that; 51 | # otherwise use the default from tech-docs.yml 52 | def contact_email 53 | email = current_page.data.author_email || config[:tech_docs][:contact_email] 54 | 55 | params = { 56 | subject: "Feedback on '#{current_page.data.title}' (#{config[:tech_docs][:host]}#{current_page_url})", 57 | } 58 | 59 | "mailto:#{email}?#{URI.encode_www_form(params)}" 60 | end 61 | 62 | private 63 | 64 | # If a `page` local exists, see if it has a `source_url`. This is used by the 65 | # pages that are created by the proxy system because they can't use frontmatter 66 | def override_from_page 67 | locals.key?(:page) ? locals[:page].try(:source_url) : false 68 | end 69 | 70 | # In the frontmatter we can specify a `source_url`. Use this if the actual 71 | # source of the page is in another GitHub repo. 72 | def source_from_yaml_file 73 | current_page.data.source_url 74 | end 75 | 76 | # As the last fallback link to the source file in this repository. 77 | def source_from_file 78 | "#{repo_url}/blob/#{repo_branch}/content/#{current_page.file_descriptor[:relative_path]}" 79 | end 80 | 81 | def locals 82 | current_page.metadata[:locals] 83 | end 84 | 85 | def current_page_url 86 | # remove the prefix that appears on the published site, breaking contribution links 87 | current_page.url 88 | .sub(/\/data-standards-authority/, "") 89 | end 90 | end 91 | end 92 | -------------------------------------------------------------------------------- /content/taxonomies/esco/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: European Skills, Competences, Qualifications and Occupations 3 | contraction: ESCO 4 | status: endorsed 5 | --- 6 | 7 | The evaluation document is available [in PDF format](/taxonomies/esco/Taxonomy_Evaluation_Document_ESCO_FINAL.pdf) and [in ODT format](/taxonomies/esco/Taxonomy_Evaluation_Document_ESCO_FINAL.odt). 8 | 9 | ESCO (European Skills, Competences, Qualifications and Occupations) is the European multilingual classification of Skills, Competences and Occupations. 10 | 11 | ESCO works as a dictionary, describing, identifying and classifying professional occupations and skills relevant for the EU labour market and education and training. ESCO provides descriptions of 2942 occupations and 13,485 skills linked to these occupations, translated into 27 languages (all official EU languages plus Icelandic, Norwegian and Arabic). 12 | 13 | The most recent version ESCO 1.1.0 was published 27/01/2022. ESCO is a European Commission project, run by Directorate General Employment, Social Affairs and Inclusion (DG EMPL). 14 | 15 | ESCO is published as Linked Open Data (LOD) so it can be easily reused and linked to other data sources. Extensive information covering the development of ESCO, use cases and how it can be implemented are available via [the website](https://ec.europa.eu/esco/portal/documents). 16 | 17 | There is also an [ESCO Web Services API](https://ec.europa.eu/esco/portal/api). 18 | 19 | 20 | ### Documentation: 21 | - [https://ec.europa.eu/esco/portal](https://ec.europa.eu/esco/portal) 22 | 23 | ### Metadata: 24 | The ESCO classification is published in SKOS-RDF and CSV formats, in order to enable users to integrate it into their applications and services. 25 | 26 | [SKOS is a W3C recommendation](https://www.w3.org/2004/02/skos/intro) within the Semantic Web vision of the Web of linked data. 27 | 28 | ### Crosswalks and limitations: 29 | In ESCO, each occupation is mapped to exactly one ISCO-08 code. ISCO-08 can therefore be used as a hierarchical structure for the occupations pillar. ISCO-08 provides the top four levels for the occupations pillar. ESCO occupations are located at level 5 and lower. 30 | 31 | The occupations pillar of ESCO is currently significantly more complex than SOC 2020 which contains 412 occupational groupings. The development of a crosswalk would be necessary to align the two taxonomies. 32 | 33 | Whilst the purpose of ESCO is clear, it was not primarily developed for UK use. Some of the skills listed in ESCO are considered not distinct enough. This makes defining and comparing jobs and an individual's transferable skills much harder. For UK use as a skills taxonomy we need it to be non-overlapping. Whilst this may be overcome in future this is a current weakness of the ESCO taxonomy. 34 | 35 | ### Contact: 36 | European Commission point of contact: Directorate General Employment, Social Affairs and Inclusion (DG EMPL). https://ec.europa.eu/esco/portal/escopedia/ESCO_governance 37 | 38 | UK point of contact: Office for National Statistics occupation.information@ons.gov.uk 39 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code Of Conduct 2 | 3 | ## Our pledge 4 | 5 | In order to create an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of: 6 | 7 | * age 8 | * body size 9 | * disability 10 | * ethnicity 11 | * gender identity and expression 12 | * level of experience 13 | * nationality 14 | * personal appearance 15 | * race 16 | * religion 17 | * sexual identity and orientation 18 | 19 | ## Our standards 20 | 21 | You can contribute to creating a positive environment in many ways. For example you can: 22 | 23 | * use welcoming and inclusive language 24 | * be respectful of differing viewpoints and experiences 25 | * accept constructive criticism gracefully 26 | * focus on what is best for the community 27 | * show empathy towards other community members 28 | 29 | You should not: 30 | 31 | * use sexualised language or imagery 32 | * make unwelcome sexual advances 33 | * troll, and make insulting or derogatory comments 34 | * make personal or political attacks 35 | * harass others, in public or private 36 | * publish others' private information, such as a physical or electronic address, without explicit permission 37 | * engage in any other conduct which could reasonably be considered inappropriate in a professional setting 38 | 39 | ## Our responsibilities 40 | 41 | As project maintainers, we are responsible for clarifying the standards of acceptable behaviour and we are expected to take appropriate and fair corrective action in response to any instances of unacceptable behaviour. 42 | 43 | We have the right and responsibility to remove, edit, or reject: 44 | 45 | * comments 46 | * commits 47 | * code 48 | * wiki edits 49 | * issues 50 | * other contributions that are not aligned to this code of conduct 51 | 52 | We also reserve the right to temporarily or permanently ban any contributor for other behaviours we deem inappropriate, threatening, offensive, or harmful. 53 | 54 | ## Scope 55 | 56 | This code of conduct applies whenever you are representing the project or community. For example you may be: 57 | 58 | * working in a project space online or in the public 59 | * using an official project email address 60 | * posting via an official social media account 61 | * participating in an online or offline event 62 | 63 | Project maintainers may further define and clarify representation of a project. 64 | 65 | ## Enforcement 66 | 67 | You should report any instances of abusive, harassing, or otherwise unacceptable behaviour to the project team at data-standards-authority@digital.cabinet-office.gov.uk 68 | The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain the anonymity of the reporter of an incident. We may post further details of specific enforcement policies separately. 69 | 70 | Project maintainers who do not follow or enforce this code of conduct in good faith may face temporary or permanent consequences. These will be determined by members of the project's leadership. 71 | 72 | ## Attribution 73 | 74 | This code of conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at [http://contributor-covenant.org/version/1/4](http://contributor-covenant.org/version/1/4/) 75 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | --- 2 | on: 3 | push: 4 | branches: 5 | - main 6 | pull_request: 7 | branches-ignore: 8 | - gh-pages 9 | 10 | permissions: 11 | contents: read 12 | 13 | jobs: 14 | build: 15 | runs-on: ubuntu-latest 16 | defaults: 17 | run: 18 | working-directory: standards-catalogue 19 | steps: 20 | - uses: actions/checkout@ec3a7ce113134d7a93b817d10a8272cb61118579 21 | 22 | - uses: ruby/setup-ruby@8a45918450651f5e4784b6031db26f4b9f76b251 23 | with: 24 | bundler-cache: true 25 | ruby-version: 3.2 26 | working-directory: standards-catalogue 27 | 28 | - uses: actions/setup-node@1f8c6b94b26d0feae1e387ca63ccbdc44d27b561 29 | with: 30 | node-version: '14' 31 | 32 | - name: Cache node modules 33 | uses: actions/cache@937d24475381cd9c75ae6db12cb4e79714b926ed 34 | env: 35 | cache-name: cache-node-modules 36 | with: 37 | # npm cache files are stored in `~/.npm` on Linux/macOS 38 | path: ~/.npm 39 | key: npm-${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }} 40 | restore-keys: | 41 | npm-${{ runner.os }}-build-${{ env.cache-name }}- 42 | npm-${{ runner.os }}-build- 43 | npm- 44 | 45 | - name: Install NPM dependencies 46 | run: npm install 47 | 48 | #- name: Prepare 49 | # run: bundle update --bundler 50 | 51 | - name: Test 52 | run: bundle exec rspec 53 | 54 | - name: Lint 55 | run: bundle exec rubocop --parallel 56 | 57 | - name: Validate files are schema compliant 58 | run: bundle exec rake schema 59 | 60 | - name: Build 61 | run: bundle exec rake build 62 | 63 | - name: Upload built site 64 | uses: actions/upload-artifact@82c141cc518b40d92cc801eee768e7aafc9c2fa2 65 | with: 66 | name: site 67 | path: standards-catalogue/build 68 | retention-days: 1 69 | 70 | publish: 71 | runs-on: ubuntu-latest 72 | if: ${{ github.ref == 'refs/heads/main' }} 73 | needs: build 74 | permissions: 75 | contents: write 76 | defaults: 77 | run: 78 | working-directory: standards-catalogue 79 | steps: 80 | - uses: actions/checkout@ec3a7ce113134d7a93b817d10a8272cb61118579 81 | 82 | - uses: ruby/setup-ruby@8a45918450651f5e4784b6031db26f4b9f76b251 83 | with: 84 | bundler-cache: true 85 | ruby-version: 3.2 86 | working-directory: standards-catalogue 87 | 88 | - name: Download built site 89 | uses: actions/download-artifact@f023be2c48cc18debc3bacd34cb396e0295e2869 90 | with: 91 | name: site 92 | path: standards-catalogue/build 93 | 94 | # Checkout stripped-down gh-pages branch to a subdirectory, for publishing 95 | - name: Checkout gh-pages branch 96 | uses: actions/checkout@ec3a7ce113134d7a93b817d10a8272cb61118579 97 | with: 98 | ref: gh-pages 99 | path: tmp/publish 100 | 101 | - name: Publish 102 | run: | 103 | git config --global user.email "github-actions@github.com" 104 | git config --global user.name "github-actions" 105 | bundle exec rake publish CLONED_GH_PAGES_DIR="../tmp/publish" 106 | -------------------------------------------------------------------------------- /standards-catalogue/.schema/standards.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-04/schema#", 3 | "id": "https://github.com/alphagov/data-standards-authority/blob/main/standards-catalogue/.schema/standards.json", 4 | "title": "Data Standards Authority Standards objects", 5 | "description": "A JSON Schema to manage the format of Standards objects", 6 | "type": "object", 7 | "required": [ 8 | "name", 9 | "specification_url", 10 | "maintainer_id", 11 | "endorsement_status_events", 12 | "tags", 13 | "licence_id", 14 | "short_description" 15 | ], 16 | "properties": { 17 | "identifier": { 18 | "$comment": "The unique identifier assigned to this standard", 19 | "type": "string" 20 | }, 21 | "name": { 22 | "$comment": "The title or name of the standard", 23 | "type": "string", 24 | "maxLength": 70 25 | }, 26 | "contraction": { 27 | "$comment": "A shorter way of referring to the standard, for instance via an acronym", 28 | "type": "string", 29 | "minLength": 1, 30 | "maxLength": 10 31 | }, 32 | "specification_url": { 33 | "$comment": "A link to a publicly accessible specification for the standard", 34 | "type": "string", 35 | "pattern": "^https?://.*" 36 | }, 37 | "maintainer_id": { 38 | "$comment": "The identifier of the organisation that maintains the standard", 39 | "type": "string" 40 | }, 41 | "endorsement_status_events": { 42 | "$comment": "The events that this standard's status has been through", 43 | "type": "array", 44 | "items": { 45 | "$ref": "#/definitions/endorsement_status_event" 46 | } 47 | }, 48 | "tags": { 49 | "$comment": "The overarching tags that this fits under", 50 | "type": "array", 51 | "minItems": 1, 52 | "items": { 53 | "$ref": "#/definitions/tag_id" 54 | } 55 | }, 56 | "description": { 57 | "$comment": "The long-form description of the standard, for instance written using Markdown", 58 | "type": "string" 59 | }, 60 | "licence_id": { 61 | "$comment": "A Software Package Data Exchange (SPDX) license identifier, if applicable, or `Proprietary` / `Unknown`", 62 | "type": "string", 63 | "pattern": "(Proprietary|Unknown|.+)", 64 | "minLength": 1 65 | }, 66 | "short_description": { 67 | "$comment": "A short description one or two sentences long, giving an overview of the standard", 68 | "type": ["string", "null"], 69 | "minLength": 1 70 | } 71 | }, 72 | "additionalProperties": false, 73 | "definitions": { 74 | "tag_id": { 75 | "$comment": "The tag identifier that this standard relates to", 76 | "type": "string" 77 | }, 78 | "endorsement_status_event": { 79 | "$comment": "A change in endorsement for a standard, for the purpose of the standards workflow", 80 | "type": "object", 81 | "properties": { 82 | "status": { 83 | "$ref": "#/definitions/status" 84 | }, 85 | "date": { 86 | "$comment": "Date that the change in status occurred", 87 | "type": "string", 88 | "format": "date" 89 | } 90 | } 91 | }, 92 | "status": { 93 | "type": "string", 94 | "enum": [ 95 | "endorsed", 96 | "review" 97 | ] 98 | } 99 | } 100 | } 101 | -------------------------------------------------------------------------------- /adr/0001-standards-catalogue-data-structure.md: -------------------------------------------------------------------------------- 1 | --- 2 | creation_date: 2021-11-11 3 | decision_date: 2021-11-11 4 | status: accepted 5 | --- 6 | # Define the schema for the standards portion of the Data Standards Authority Workbench 7 | 8 | ## Context 9 | 10 | The standards section of the Data Standards Authority Workbench (DSA Workbench), is used to capture standards that the DSA are reviewing, before they become official guidance on Gov.UK. It is also an attempt to map other standards in use across government, both for the DSA's internal prioritisation activities and to enable external users to find relevant data standards. To begin with, this second focus is served by curating a list of standards catalogues. 11 | 12 | As part of plans to enhance the Workbench by introducing schema.org metadata, we discovered that the underlying data wasn't quite standardised. 13 | 14 | Although this is currently a static website, at some point it may progress into a fully fledged application with a data store, and we want to take this opportunity to invest in a forward-thinking data model, which would work with a backing data store. 15 | 16 | ## Decision 17 | 18 | The Entity Relationship Diagram can be seen below: 19 | 20 | ![Entity Relationship Diagram for Standards](https://kroki.io/erd/svg/eNqlkk1PhDAQhu_9FQ3HhT3s1ZsHDkYDhN2NMYRsxnaWNEJh26Ixhv9uKRABzRrjoU1n-vSdr2Z7A5KD4jnZCI7SiLNARSRUSD9oCc9Y3lBPGyVkEVCFl1Yo5B7tCKulUcCMqOUvpG6QWVkGPXtqVTnjrbWEOWqmRLOSrUC98PpN9oRvoDgJTvxSMJQM3bkCIY1dqHqTZOGrrSUnvh7Lc5A1TKv7Iwdj65vUp_gB7f1eZ9_vHfrnpsyytyIHKP6p8DCUuFD5yvvb-26McAUw780MQNlWWZyEUZCkcZLehYfb9Ck4RvdR_BjlFnfTmg3LNSdWBUih3Tx_KvBK-LXe4pJMn5HuttsNnayF26e2qwvPjo5dWnnnWa4k3O8gbh_YYdzkE0j5DAk=) 21 | 22 | This allows a set of specific information to be available in each Standard, and: 23 | 24 | - Gives us the opportunity to track the catalogue status events that an entry goes through, such as _In Review_ to _Endorsed_, without it being tracked as a set of fields in the `Standard` itself 25 | - We decided that `specification_*` information would sit within the `Standard`, as it was very unlikely that we would produce multiple `Standard`s that had the same `specification` 26 | - License categorisation was added to make it clearer to the consumers of the site whether the licensing of the standard is Open/Proprietary, with the option to also add Unknown for cases where it is difficult to tell 27 | 28 |
    29 | 30 | Entity Relationship Diagram (raw) 31 | 32 | ```erd 33 | [Standard] 34 | *identifier 35 | name { label: "string, required" } 36 | contraction { label: "string, required" } 37 | specification_url { label: "url, required" } 38 | description { label: "markdown" } 39 | +tag_id 40 | +licence_id 41 | +maintainer_id 42 | 43 | [Event] 44 | +standard_id 45 | +status_id 46 | date {label: "required, date"} 47 | 48 | [Status] 49 | *identifier 50 | name { label: "string, required" } 51 | description 52 | 53 | [Tag] 54 | *identifier 55 | name { label: "string, required" } 56 | description 57 | 58 | [Licence] 59 | *identifier {label: "string, required"} 60 | name {label: "string, required"} 61 | type {label: "enum[OPEN,PROPRIETARY,UNKNOWN]"} 62 | url {label: "url"} 63 | 64 | [Organisation] 65 | *identifier 66 | name {label: "string, required"} 67 | url {label: "url, required"} 68 | 69 | Standard 1--* Standard 70 | Standard 1--+ Tag 71 | Standard 1--1 Licence 72 | Standard 1--1 Organisation 73 | Standard 1--+ Event 74 | Event 1--1 Status 75 | ``` 76 | 77 |
    78 | 79 | ## Consequences 80 | 81 | No consequences at this time. 82 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_search.scss: -------------------------------------------------------------------------------- 1 | @include govuk-media-query($media-type: screen) { 2 | .page-title + .search { 3 | margin-top: govuk-spacing(6); 4 | } 5 | 6 | .js .search__label { 7 | position: absolute; 8 | left: -9999em; 9 | top: auto; 10 | width: 1px; 11 | height: 1px; 12 | overflow: hidden; 13 | } 14 | } 15 | 16 | @include govuk-media-query($media-type: print) { 17 | .search { 18 | display: none; 19 | } 20 | } 21 | 22 | html.has-search-results-open { 23 | overflow: hidden; 24 | .app-pane__content { 25 | overflow: hidden; 26 | } 27 | } 28 | .search-results { 29 | display: none; 30 | &.is-open { 31 | display: block; 32 | } 33 | } 34 | 35 | .search-results { 36 | position: absolute; 37 | top: 200px; 38 | top: 12.5rem; 39 | left: 0; 40 | right: 0; 41 | bottom: 0; 42 | z-index: 600; 43 | overflow-x: scroll; 44 | -webkit-overflow-scrolling: touch; 45 | -ms-overflow-style: none; 46 | @include govuk-media-query(tablet) { 47 | padding: govuk-spacing(6); 48 | top: 100px; 49 | top: 6.25rem; 50 | } 51 | 52 | a:link, a:visited { 53 | text-decoration: none; 54 | color: $govuk-link-colour; 55 | } 56 | 57 | a:hover { 58 | text-decoration: underline; 59 | 60 | &:focus { 61 | text-decoration: none; 62 | } 63 | } 64 | a:focus { 65 | outline: none; 66 | @include govuk-focused-text; 67 | } 68 | } 69 | .search-results__inner { 70 | position: relative; 71 | background: govuk-colour("white"); 72 | border-top: 1px solid govuk-colour("mid-grey"); 73 | max-width: 40rem; 74 | padding: 15px; 75 | @include govuk-media-query(tablet) { 76 | padding: 15px 0px 50px 40px; 77 | border: 1px solid govuk-colour("mid-grey"); 78 | } 79 | } 80 | .search-results__title { 81 | @include govuk-font($size: 27, $weight: bold); 82 | margin-bottom: govuk-spacing(6); 83 | } 84 | .search-results__close { 85 | @include govuk-font($size: 16); 86 | position: absolute; 87 | top: 18px; 88 | right: 20px; 89 | appearance: none; 90 | -webkit-appearance: none; 91 | background: none; 92 | border: 0; 93 | padding: 0; 94 | cursor: pointer; 95 | 96 | &:focus { 97 | background-color: $govuk-focus-colour; 98 | outline: $govuk-focus-width solid transparent; 99 | box-shadow: inset 0 0 0 1px $govuk-focus-colour; 100 | } 101 | 102 | &:focus:not(:active):not(:hover) { 103 | border-color: $govuk-focus-colour; 104 | color: $govuk-focus-text-colour; 105 | background-color: $govuk-focus-colour; 106 | box-shadow: 0 2px 0 $govuk-focus-text-colour; 107 | } 108 | 109 | &::after { 110 | content: ''; 111 | display: inline-block; 112 | vertical-align: middle; 113 | padding-left: 8px; 114 | height: 18px; 115 | width: 18px; 116 | background: no-repeat image-url('/images/govuk-icn-close.png') center right; 117 | @include govuk-device-pixel-ratio { 118 | background-image: image-url('/images/govuk-icn-close@2x.png'); 119 | } 120 | background-size: contain; 121 | } 122 | } 123 | .search-results__close-label { 124 | position: absolute; 125 | left: -9999em; 126 | top: auto; 127 | width: 1px; 128 | height: 1px; 129 | overflow: hidden; 130 | } 131 | .search-result { 132 | margin-bottom: govuk-spacing(6); 133 | } 134 | .search-result mark { 135 | background-color: transparent; 136 | color: inherit; 137 | font-weight: bold; 138 | } 139 | -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/_modules/collapsible-navigation.js: -------------------------------------------------------------------------------- 1 | (function ($, Modules) { 2 | 'use strict' 3 | 4 | Modules.CollapsibleNavigation = function () { 5 | var $contentPane 6 | var $nav 7 | var $topLevelItems 8 | 9 | this.start = function ($element) { 10 | $contentPane = $('.app-pane__content') 11 | $nav = $element 12 | $topLevelItems = $nav.find('> ul > li') 13 | 14 | // Attach collapsible heading functionality,on mobile and desktop 15 | collapsibleHeadings() 16 | openActiveHeading() 17 | $contentPane.on('scroll', _.debounce(openActiveHeading, 100, { maxWait: 100 })) 18 | } 19 | 20 | function collapsibleHeadings () { 21 | for (var i = $topLevelItems.length - 1; i >= 0; i--) { 22 | var $topLevelItem = $($topLevelItems[i]) 23 | var $heading = $topLevelItem.find('> a') 24 | var $listing = $topLevelItem.find('> ul') 25 | var id = 'toc-' + $heading.text().toLowerCase().replace(/\s+/g, '-') 26 | // Only add collapsible functionality if there are children. 27 | if ($listing.length === 0) { 28 | continue 29 | } 30 | $topLevelItem.addClass('collapsible') 31 | var arrayOfIds = [] 32 | $listing.each(function (i) { 33 | var uniqueId = id + '-' + i 34 | arrayOfIds.push(uniqueId) 35 | $(this).addClass('collapsible__body') 36 | .attr('id', uniqueId) 37 | .attr('aria-expanded', 'false') 38 | }) 39 | $heading.addClass('collapsible__heading') 40 | .after('') 41 | $topLevelItem.on('click', '.collapsible__toggle', function (e) { 42 | e.preventDefault() 43 | var $parent = $(this).parent() 44 | toggleHeading($parent) 45 | }) 46 | } 47 | } 48 | 49 | function toggleHeading ($topLevelItem) { 50 | var isOpen = $topLevelItem.hasClass('is-open') 51 | var $heading = $topLevelItem.find('> a') 52 | var $body = $topLevelItem.find('.collapsible__body') 53 | var $toggleLabel = $topLevelItem.find('.collapsible__toggle-label') 54 | 55 | $topLevelItem.toggleClass('is-open', !isOpen) 56 | $body.attr('aria-expanded', isOpen ? 'false' : 'true') 57 | $toggleLabel.text(isOpen ? 'Expand ' + $heading.text() : 'Collapse ' + $heading.text()) 58 | } 59 | 60 | function openActiveHeading () { 61 | var $activeElement 62 | var currentPath = window.location.pathname 63 | var isActiveTrail = '[href*="' + currentPath + '"]' 64 | // Add an exception for the root page, as every href includes / 65 | if (currentPath === '/') { 66 | isActiveTrail = '[href="' + currentPath + window.location.hash + '"]' 67 | } 68 | for (var i = $topLevelItems.length - 1; i >= 0; i--) { 69 | var $element = $($topLevelItems[i]) 70 | var $heading = $element.find('> a') 71 | // Check if this item href matches 72 | if ($heading.is(isActiveTrail)) { 73 | $activeElement = $element 74 | break 75 | } 76 | // Otherwise check the children 77 | var $children = $element.find('li > a') 78 | var $matchingChildren = $children.filter(isActiveTrail) 79 | if ($matchingChildren.length) { 80 | $activeElement = $element 81 | break 82 | } 83 | } 84 | if ($activeElement && !$activeElement.hasClass('is-open')) { 85 | toggleHeading($activeElement) 86 | } 87 | } 88 | } 89 | })(jQuery, window.GOVUK.Modules) 90 | -------------------------------------------------------------------------------- /standards-catalogue/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of conduct for `alphagov` 2 | 3 | Contributors to repositories hosted in `alphagov` are expected to 4 | follow the Contributor Covenant Code of 5 | Conduct, and those working within Government are also expected to follow the Civil Service Code 6 | 7 | ## Civil Service Code 8 | 9 | The [Civil Service Code](https://www.gov.uk/government/publications/civil-service-code/the-civil-service-code) 10 | 11 | ## Contributor Covenant Code of Conduct 12 | 13 | > Note: 14 | > * where the code of conduct says "project" we mean GDS, `alphagov` and all repositories hosted within it. 15 | > * where the code of conduct says "maintainer" we mean `alphagov` organisation owners 16 | > * where the code of conduct says "leadership" we mean both `alphagov` organisation owners, line managers, and other leadership within GDS 17 | 18 | ### Our Pledge 19 | 20 | In the interest of fostering an open and welcoming environment, we as 21 | contributors and maintainers pledge to making participation in our project and 22 | our community a harassment-free experience for everyone, regardless of age, body 23 | size, disability, ethnicity, gender identity and expression, level of experience, 24 | nationality, personal appearance, race, religion, or sexual identity and 25 | orientation. 26 | 27 | ### Our Standards 28 | 29 | Examples of behavior that contributes to creating a positive environment 30 | include: 31 | 32 | * Using welcoming and inclusive language 33 | * Being respectful of differing viewpoints and experiences 34 | * Gracefully accepting constructive criticism 35 | * Focusing on what is best for the community 36 | * Showing empathy towards other community members 37 | 38 | Examples of unacceptable behavior by participants include: 39 | 40 | * The use of sexualized language or imagery and unwelcome sexual attention or 41 | advances 42 | * Trolling, insulting/derogatory comments, and personal or political attacks 43 | * Public or private harassment 44 | * Publishing others' private information, such as a physical or electronic 45 | address, without explicit permission 46 | * Other conduct which could reasonably be considered inappropriate in a 47 | professional setting 48 | 49 | ### Our Responsibilities 50 | 51 | Project maintainers are responsible for clarifying the standards of acceptable 52 | behavior and are expected to take appropriate and fair corrective action in 53 | response to any instances of unacceptable behavior. 54 | 55 | Project maintainers have the right and responsibility to remove, edit, or 56 | reject comments, commits, code, wiki edits, issues, and other contributions 57 | that are not aligned to this Code of Conduct, or to ban temporarily or 58 | permanently any contributor for other behaviors that they deem inappropriate, 59 | threatening, offensive, or harmful. 60 | 61 | ### Scope 62 | 63 | This Code of Conduct applies both within project spaces and in public spaces 64 | when an individual is representing the project or its community. Examples of 65 | representing a project or community include using an official project e-mail 66 | address, posting via an official social media account, or acting as an appointed 67 | representative at an online or offline event. Representation of a project may be 68 | further defined and clarified by project maintainers. 69 | 70 | ### Enforcement 71 | 72 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 73 | reported by contacting the project team at alphagov-code-of-conduct@digital.cabinet-office.gov.uk. All 74 | complaints will be reviewed and investigated and will result in a response that 75 | is deemed necessary and appropriate to the circumstances. The project team is 76 | obligated to maintain confidentiality with regard to the reporter of an incident. 77 | Further details of specific enforcement policies may be posted separately. 78 | 79 | Project maintainers who do not follow or enforce the Code of Conduct in good 80 | faith may face temporary or permanent repercussions as determined by other 81 | members of the project's leadership. 82 | 83 | ### Attribution 84 | 85 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 86 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 87 | 88 | [homepage]: https://www.contributor-covenant.org -------------------------------------------------------------------------------- /content/guidance/apimanagement/APIM-Design.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: APIM - 02 - Design 3 | weight: 832 4 | keywords: 'API Management' 5 | identifier: DSA-003 6 | name: APIManagement 7 | organisation: Data Standards Authority 8 | author_email: api-programme@digital.cabinet-office.gov.uk 9 | status: Draft 10 | startDate: 2021-03-23 11 | dateAdded: 2021-03-23 12 | dateUpdated: 2021-04-28 13 | --- 14 | 15 | ## Design 16 | 17 | 18 | _This is a DRAFT document for discussion. This is not finalised. All aspects of this document are subject to change. Please leave comments on any aspect of it._ 19 | 20 | #### Contents: 21 | - [01 - Introduction](APIM-Introduction.html) 22 | - [02 - Design](APIM-Design.html) 23 | - [03 - Deployment](APIM-Deployment.html) 24 | - [04 - Management](APIM-Management.html) 25 | - [05 - Discovery](APIM-Discovery.html) 26 | - [06 - Retirement](APIM-Retirement.html) 27 | 28 | 29 | Establishing design guidance helps maintain consistency across your API estate. It is difficult to manage APIs that are not consistent, so the more your APIs follow the same design principles and practices, the easier it will be to manage them at scale. 30 | 31 | The level of guidance you provide will depend on the size and structure of your organisation. For example, guidance would be very different for a small, homogeneous environment where every aspect of API design is mandated, and a large, federated organisation where many different technologies and approaches are already in use. 32 | 33 | ### Review and challenge assumptions 34 | Organisations often develop their API strategy based on the first few APIs they built, where choices that teams made in response to specific problems are then mandated across very different domains. If you have an existing API strategy in place, it is worthwhile to think about what assumptions in your API programme might be legacy. 35 | 36 | User research can help you challenge these assumptions and define needs. Some questions you might seek to answer include: 37 | 38 | - What technologies are in use, or might be in the future? 39 | - What are the different levels of maturity of development teams in the organisation? 40 | - Are the APIs produced primarily internal or external facing, or a mixture? 41 | - What SLAs should APIs meet - do you have different SLA tiers which are appropriate for different use cases? 42 | 43 | 44 | ### Bring developers into the design process 45 | API design guidance reduces friction by providing a framework within which a developer can start to work. 46 | 47 | It’s important to provide explanations for design choices. Being open with the decisions behind the guidance increases developer trust and helps get them on board with the process. 48 | 49 | ### Use standards 50 | 51 | Technology standards like OpenAPI can help take a lot of the guesswork out of software decisions, and can also lend credibility to your strategy as they reflect widely accepted ways of doing things. 52 | 53 | It is helpful to specify use cases for different API standards. As an example, you might require using REST for microservices and GraphQL for more data intensive processes. 54 | 55 | You should also consider what standards make sense for specific technical details. For example, how to use HTTP functionality, or requiring that all APIs follow a consistent approach to versioning. 56 | 57 | ### Make guidance clear and easily accessible 58 | Setting out decisions like these in a central place helps development teams get started on projects more quickly and with less effort. Some organisations simply keep these guidelines on a central document store or git repository, while some have dedicated tooling. Various tools are available to store and share API specifications, many of which have an open source version which allows you to try them out. 59 | 60 | Tooling like this can provide functionality including: 61 | 62 | - specification support 63 | - real time validation 64 | - auto-completion 65 | - auto generated documentation 66 | 67 | These tools often form part of an API Management suite, which also includes a developer hub and an API gateway, but can also be used as standalone design or governance modules. 68 | 69 | #### Contents: 70 | - [01 - Introduction](APIM-Introduction.html) 71 | - [02 - Design](APIM-Design.html) 72 | - [03 - Deployment](APIM-Deployment.html) 73 | - [04 - Management](APIM-Management.html) 74 | - [05 - Discovery](APIM-Discovery.html) 75 | - [06 - Retirement](APIM-Retirement.html) 76 | 77 | 78 | [Next](APIM-Deployment.html) 79 | -------------------------------------------------------------------------------- /standards-catalogue/config.rb: -------------------------------------------------------------------------------- 1 | ### Config from tech-docs-gem: start ### 2 | require "middleman" 3 | require "middleman-autoprefixer" 4 | require "middleman-sprockets" 5 | require "middleman-livereload" 6 | require "middleman-search" 7 | 8 | require "active_support/all" 9 | 10 | require "lib/schemaorg" 11 | require "lib/govuk_tech_docs/contribution_banner" 12 | require "lib/govuk_tech_docs/meta_tags" 13 | require "lib/govuk_tech_docs/tech_docs_html_renderer" 14 | require "lib/govuk_tech_docs/unique_identifier_extension" 15 | require "lib/govuk_tech_docs/unique_identifier_generator" 16 | 17 | # Project setup 18 | repo_name = "data-standards-authority" 19 | 20 | activate :sprockets 21 | 22 | sprockets.append_path File.expand_path("node_modules", __dir__) 23 | 24 | files.watch :source, path: File.expand_path("source", __dir__) 25 | 26 | set :markdown_engine, :redcarpet 27 | set :markdown, 28 | renderer: GovukTechDocs::TechDocsHTMLRenderer.new( 29 | with_toc_data: true, 30 | context: self, 31 | ), 32 | fenced_code_blocks: true, 33 | tables: true, 34 | no_intra_emphasis: true 35 | 36 | # Reload the browser automatically whenever files change 37 | configure :development do 38 | activate :livereload 39 | end 40 | 41 | set(:govuk_assets_path, "/assets/govuk/assets/") 42 | 43 | configure :build do 44 | set(:build_dir, "build/#{repo_name}") 45 | set(:http_prefix, "/#{repo_name}/") 46 | set(:govuk_assets_path, "/#{repo_name}/assets/govuk/assets/") 47 | end 48 | 49 | configure :build do 50 | activate :autoprefixer 51 | activate :minify_javascript, ignore: ["/raw_assets/*"] 52 | end 53 | 54 | config_file = ENV.fetch("CONFIG_FILE", "config/tech-docs.yml") 55 | config[:tech_docs] = YAML.load_file(config_file).with_indifferent_access 56 | activate :unique_identifier 57 | 58 | helpers do 59 | include GovukTechDocs::ContributionBanner 60 | include SchemaOrg 61 | 62 | def meta_tags 63 | @meta_tags ||= GovukTechDocs::MetaTags.new(config, current_page) 64 | end 65 | 66 | def format_date(date) 67 | date.strftime("%-e %B %Y") 68 | end 69 | 70 | def active_page(page_path) 71 | [ 72 | page_path == "/" && current_page.path == "index.html", 73 | "/#{current_page.path}" == page_path, 74 | !current_page.data.parent.nil? && current_page.data.parent.to_s == page_path, 75 | ].any? 76 | end 77 | 78 | def display_organisation(id) 79 | if data.organisations[id] 80 | link_to data.organisations[id].name, data.organisations[id].url 81 | else 82 | raise "maintainer_id must match an entry in organisations.yml" 83 | end 84 | end 85 | 86 | def display_tags(id) 87 | if data.tags[id] 88 | data.tags[id].name 89 | else 90 | raise "tags must match an entry in tags.yml" 91 | end 92 | end 93 | 94 | def display_status(type, id) 95 | if data.statuses[type] && data.statuses[type][id] 96 | status = data.statuses[type][id] 97 | "#{status.name}" 98 | else 99 | id 100 | end 101 | end 102 | 103 | def display_licence(id) 104 | licence = data.licences[id] 105 | if licence.url 106 | "#{licence.type} - #{licence.name}" 107 | else 108 | "#{licence.name}" 109 | end 110 | end 111 | 112 | def get_link_text(page) 113 | if page.data.title 114 | page.data.title 115 | elsif page.data.name 116 | page.data.name 117 | else 118 | page.path.delete_prefix("standards/").chomp("/index.html") 119 | end 120 | end 121 | 122 | def standard_to_schemaorg(page_data) 123 | SchemaOrg::Standard.new(data, page_data).to_json 124 | end 125 | end 126 | 127 | page "/*.xml", layout: false 128 | page "/*.json", layout: false 129 | page "/*.txt", layout: false 130 | page "/standards/*/index.*", layout: "standards_table" 131 | page "/taxonomies/*/index.*", layout: "taxonomy_table" 132 | 133 | activate :search do |search| 134 | search.resources = [""] 135 | 136 | search.fields = { 137 | title: { boost: 100, store: true, required: true }, 138 | content: { boost: 50, store: true }, 139 | url: { index: false, store: true }, 140 | } 141 | 142 | search.pipeline_remove = %w[stopWordFilter] 143 | 144 | search.tokenizer_separator = '/[\s\-/]+/' 145 | end 146 | ### Config from tech-docs-gem: end ### 147 | -------------------------------------------------------------------------------- /content/guidance/apimanagement/APIM-Discovery.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: APIM - 05 - Discovery 3 | weight: 833 4 | keywords: 'API Management' 5 | identifier: DSA-003 6 | name: APIManagement 7 | organisation: Data Standards Authority 8 | author_email: api-programme@digital.cabinet-office.gov.uk 9 | status: Draft 10 | startDate: 2021-03-23 11 | dateAdded: 2021-03-23 12 | dateUpdated: 2021-04-28 13 | --- 14 | 15 | ## Discovery 16 | 17 | 18 | _This is a DRAFT document for discussion. This is not finalised. All aspects of this document are subject to change. Please leave comments on any aspect of it._ 19 | 20 | #### Contents: 21 | - [01 - Introduction](APIM-Introduction.html) 22 | - [02 - Design](APIM-Design.html) 23 | - [03 - Deployment](APIM-Deployment.html) 24 | - [04 - Management](APIM-Management.html) 25 | - [05 - Discovery](APIM-Discovery.html) 26 | - [06 - Retirement](APIM-Retirement.html) 27 | 28 | ## Discovery 29 | 30 | Making your API easy to find is a critical part of the API management process. If people can’t find your APIs, they can’t use them. You can use an API catalogue to help users discover your APIs, find out what they do and how to use them. 31 | 32 | ### Decouple your API discovery layer from your dev portal and API gateway 33 | Development teams often rely solely on a developer portal to make their APIs discoverable. Most API management tooling includes modules for the API gateway, the developer portal, and an API catalogue. 34 | 35 | However, there are cases where it may not make sense for an API to sit on the gateway or the developer portal, but which should still be discoverable in a catalogue. This might be because the API is still in experimental stages, doesn’t meet standards, or because the team is not ready to hand over management of the API. 36 | 37 | It is then a good idea to have the catalogue as a separate entity, so it can make all APIs discoverable without being restricted to those which meet certain criteria. 38 | 39 | This helps: 40 | 41 | * promote an environment where innovation can happen in the open 42 | * avoids teams developing in silos to get around rules 43 | * helps transparency and reduces duplication of effort 44 | 45 | ### Consider who will be looking to find APIs in your organisation 46 | Most organisations have three levels of access for their APIs: 47 | 48 | * Private - internal and kept entirely within the organisation 49 | * Partner - shared externally with a limited set of trusted users/partners 50 | * Public - open to external users either directly or through a self-service sign up platform 51 | 52 | Consider how best to enable discovery for each group. You could do this with separate catalogues, but you should consider the cost and effort it would require to maintain these. You can also use access control to restrict visibility of APIs, or details of the APIs, to registered users at different levels of authentication. 53 | 54 | You should aim to expose as much detail to all users as possible. Even for sensitive datasets you should expose basic details of an API with information about how to get access. This helps developers understand the value of the API and start interacting with it while they wait for access approval. 55 | 56 | You should consult your internal security teams about what level of exposure is acceptable for each API. You might also find it helpful to review the metadata model available at the [government API catalogue](https://www.api.gov.uk/). This provides a basic discovery framework that does not increase the vulnerability of published resources. 57 | 58 | ### Link your catalogue to the Government API Catalogue 59 | Your internal catalogue should update the [government API catalogue](https://www.api.gov.uk/), either programmatically or with manual submissions. This catalogue is a centralised directory for discovery of government APIs, and any external APIs (whether inter-departmental, restricted or public) should be listed on there. 60 | 61 | Contact the API Catalogue team at [api-catalogue@digital.cabinet-office.gov.uk](mailto:api-catalogue@digital.cabinet-office.gov.uk) for more information and help with adding your APIs or connecting your internal catalogue. 62 | 63 | 64 | 65 | 66 | #### Contents: 67 | - [01 - Introduction](APIM-Introduction.html) 68 | - [02 - Design](APIM-Design.html) 69 | - [03 - Deployment](APIM-Deployment.html) 70 | - [04 - Management](APIM-Management.html) 71 | - [05 - Discovery](APIM-Discovery.html) 72 | - [06 - Retirement](APIM-Retirement.html) 73 | 74 | 75 | [Next](APIM-Retirement.html) 76 | -------------------------------------------------------------------------------- /standards-catalogue/Rakefile: -------------------------------------------------------------------------------- 1 | require "rspec/core/rake_task" 2 | require "rubocop/rake_task" 3 | require "json-schema" 4 | 5 | def schema(schema_name) 6 | JSON.parse(File.read(".schema/#{schema_name}.json")) 7 | end 8 | 9 | def does_file_match_schema(schema, file_to_validate) 10 | to_validate = YAML.load_file(file_to_validate) 11 | 12 | errors = JSON::Validator.fully_validate(schema, to_validate).to_a 13 | return true if errors.empty? 14 | 15 | puts "Validation failed while trying to validate `#{file_to_validate}`: " 16 | jj errors 17 | false 18 | end 19 | 20 | def is_valid_schema(schema, to_validate) 21 | errors = JSON::Validator.fully_validate(schema, to_validate).to_a 22 | return true if errors.empty? 23 | 24 | puts "Validation failed while trying to validate `#{to_validate}`: " 25 | jj errors 26 | false 27 | end 28 | 29 | def is_data_file_schema_compliant(schema, to_validate, key_validation) 30 | schema = schema(schema) 31 | objects = YAML.load_file(to_validate) 32 | errors = objects.map do |key, object| 33 | key_valid = key_validation[:regex] =~ key 34 | puts "#{to_validate} failed validation: `#{key}` #{key_validation[:message]}" unless key_valid 35 | is_valid_schema(schema, object) && key_valid 36 | end 37 | raise unless errors.all? 38 | end 39 | 40 | RSpec::Core::RakeTask.new(:spec) 41 | RuboCop::RakeTask.new 42 | 43 | task default: ["spec", "rubocop:auto_correct", "schema"] 44 | 45 | desc "Build site" 46 | task :build do 47 | sh("rsync -a ../content/ source") 48 | sh "bundle exec middleman build --clean --bail" 49 | end 50 | 51 | task schema: ["schema:standards", "schema:data_files"] 52 | 53 | namespace :schema do 54 | namespace :data_files do 55 | desc "Validate that the Status data file matches standards" 56 | task :sync_standards_status do 57 | schema = schema("standards") 58 | schema_options = schema["definitions"]["status"]["enum"] 59 | data_options = YAML.load_file("data/statuses.yml")["standard"] 60 | raise "Statuses are mismatched between schema and data file" unless schema_options == data_options.keys 61 | end 62 | 63 | desc "Validate organisations are schema compliant" 64 | task :organisations do 65 | key_validation = { 66 | regex: /^[a-z-]+$/, 67 | message: "must be hyphenated (kebab-cased) and only include lowercase letters", 68 | } 69 | is_data_file_schema_compliant("organisation", "data/organisations.yml", key_validation) 70 | end 71 | 72 | desc "Validate licences are schema compliant" 73 | task :licences do 74 | key_validation = { 75 | regex: /^[a-zA-Z0-9.-]+$/, 76 | message: "must be hyphenated (kebab-cased) and only include a mix of uppercase, lowercase, numbers and `.`", 77 | } 78 | is_data_file_schema_compliant("licence", "data/licences.yml", key_validation) 79 | end 80 | 81 | desc "Validate tags are schema compliant" 82 | task :tags do 83 | key_validation = { 84 | regex: /^[a-z-]+$/, 85 | message: "must be hyphenated (kebab-cased) and only include lowercase letters", 86 | } 87 | is_data_file_schema_compliant("tag", "data/tags.yml", key_validation) 88 | end 89 | end 90 | 91 | task data_files: %w[data_files:sync_standards_status data_files:organisations data_files:licences data_files:tags] 92 | 93 | desc "Validate Standards are schema compliant" 94 | task :standards do 95 | schema = schema("standards") 96 | errors = Dir.glob("../content/standards/*/*.md").map do |f| 97 | does_file_match_schema(schema, f) 98 | end 99 | raise unless errors.all? 100 | end 101 | end 102 | 103 | desc "Publish build to GitHub pages" 104 | task :publish do 105 | require "tmpdir" 106 | 107 | rev = `git rev-parse --short HEAD`.chomp 108 | 109 | publish_dir = ENV.fetch("CLONED_GH_PAGES_DIR") do 110 | tmp_dir = Dir.mktmpdir("publish-standards-catalogue") 111 | repo_url = `git config --get remote.origin.url`.chomp 112 | sh("git clone --single-branch --branch gh-pages #{repo_url} #{tmp_dir}") 113 | sh("echo #{rev}, #{publish_dir}") 114 | tmp_dir 115 | end 116 | 117 | sh("rsync -a --delete --exclude .git --exclude CNAME build/data-standards-authority/ #{publish_dir}") 118 | sh("git -C #{publish_dir} add --all") 119 | sh("git -C #{publish_dir} commit -m 'Publish #{rev}'") do |ok, _| 120 | if ok 121 | sh("git -C #{publish_dir} push") 122 | else 123 | puts "Nothing to commit, skipping push" 124 | end 125 | end 126 | end 127 | -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/_modules/in-page-navigation.js: -------------------------------------------------------------------------------- 1 | (function ($, Modules) { 2 | 'use strict' 3 | 4 | Modules.InPageNavigation = function InPageNavigation () { 5 | var $tocPane 6 | var $contentPane 7 | var $tocItems 8 | var $targets 9 | 10 | this.start = function start ($element) { 11 | $tocPane = $element.find('.app-pane__toc') 12 | $contentPane = $element.find('.app-pane__content') 13 | $tocItems = $('.js-toc-list').find('a') 14 | $targets = $contentPane.find('[id]') 15 | 16 | $contentPane.on('scroll', _.debounce(handleScrollEvent, 100, { maxWait: 100 })) 17 | 18 | if (Modernizr.history) { 19 | // Popstate is triggered when using the back button to navigate 'within' 20 | // the page, i.e. changing the anchor part of the URL. 21 | $(window).on('popstate', function (event) { 22 | restoreScrollPosition(event.originalEvent.state) 23 | }) 24 | 25 | if (history.state && history.state.scrollTop) { 26 | // Restore existing state when e.g. using the back button to return to 27 | // this page 28 | restoreScrollPosition(history.state) 29 | } else { 30 | // Store the initial position so that we can restore it even if we 31 | // never scroll. 32 | handleInitialLoadEvent() 33 | } 34 | } 35 | } 36 | 37 | function restoreScrollPosition (state) { 38 | if (state && typeof state.scrollTop !== 'undefined') { 39 | $contentPane.scrollTop(state.scrollTop) 40 | } 41 | } 42 | 43 | function handleInitialLoadEvent () { 44 | var fragment = fragmentForTargetElement() 45 | 46 | if (!fragment) { 47 | fragment = fragmentForFirstElementInView() 48 | } 49 | 50 | handleChangeInActiveItem(fragment) 51 | } 52 | 53 | function handleScrollEvent () { 54 | handleChangeInActiveItem(fragmentForFirstElementInView()) 55 | } 56 | 57 | function handleChangeInActiveItem (fragment) { 58 | storeCurrentPositionInHistoryApi(fragment) 59 | highlightActiveItemInToc(fragment) 60 | } 61 | 62 | function storeCurrentPositionInHistoryApi (fragment) { 63 | if (Modernizr.history && fragment) { 64 | history.replaceState( 65 | { scrollTop: $contentPane.scrollTop() }, 66 | '', 67 | fragment 68 | ) 69 | } 70 | } 71 | 72 | function highlightActiveItemInToc (fragment) { 73 | // Navigation items for single page navigation don't necessarily include the path name, but 74 | // navigation items for multipage navigation items do include it. This checks for either case. 75 | var $activeTocItem = $tocItems.filter( 76 | '[href="' + window.location.pathname + fragment + '"],[href="' + fragment + '"]' 77 | ) 78 | // Navigation items with children don't contain fragments in their url 79 | // Check to see if any nav items contain just the path name. 80 | if (!$activeTocItem.get(0)) { 81 | $activeTocItem = $tocItems.filter('[href="' + window.location.pathname + '"]') 82 | } 83 | if ($activeTocItem.get(0)) { 84 | $tocItems.removeClass('toc-link--in-view') 85 | $activeTocItem.addClass('toc-link--in-view') 86 | scrollTocToActiveItem($activeTocItem) 87 | } 88 | } 89 | 90 | function scrollTocToActiveItem ($activeTocItem) { 91 | var paneHeight = $tocPane.height() 92 | var linkTop = $activeTocItem.position().top 93 | var linkBottom = linkTop + $activeTocItem.outerHeight() 94 | 95 | var offset = null 96 | 97 | if (linkTop < 0) { 98 | offset = linkTop 99 | } else if (linkBottom >= paneHeight) { 100 | offset = -(paneHeight - linkBottom) 101 | } else { 102 | return 103 | } 104 | 105 | var newScrollTop = $tocPane.scrollTop() + offset 106 | 107 | $tocPane.scrollTop(newScrollTop) 108 | } 109 | 110 | function fragmentForTargetElement () { 111 | return window.location.hash 112 | } 113 | 114 | function fragmentForFirstElementInView () { 115 | var result = null 116 | 117 | $($targets.get().reverse()).each(function checkIfInView (index) { 118 | if (result) { 119 | return 120 | } 121 | 122 | var $this = $(this) 123 | 124 | if (Math.floor($this.position().top) <= 0) { 125 | result = $this 126 | } 127 | }) 128 | 129 | return result ? '#' + result.attr('id') : false 130 | } 131 | } 132 | })(jQuery, window.GOVUK.Modules) 133 | -------------------------------------------------------------------------------- /standards-catalogue/source/layouts/_header.erb: -------------------------------------------------------------------------------- 1 | 63 | -------------------------------------------------------------------------------- /standards-catalogue/source/accessibility.html.md.erb: -------------------------------------------------------------------------------- 1 | --- 2 | title: Accessibility statement for the Data Standards Authority Catalogue 3 | hide_in_navigation: true 4 | --- 5 | 6 | # Accessibility statement for the Data Standards Authority Catalogue 7 | 8 | This accessibility statement applies to the Data Standards Authority Catalogue at [alphagov.github.io/data-standards-authority](https://alphagov.github.io/data-standards-authority/). 9 | 10 | This website is run by the Data Standards Authority team at the Government Digital Service (GDS). We want as many people as possible to be able to use this website. For example, that means you should be able to: 11 | 12 | + change colours, contrast levels and fonts 13 | + zoom in up to 300% without problems 14 | + navigate most of the website using just a keyboard 15 | + navigate most of the website using speech recognition software 16 | + listen to most of the website using a screen reader (including the most recent versions of JAWS, NVDA and VoiceOver) 17 | 18 | We’ve also made the website text as simple as possible to understand. 19 | 20 | [AbilityNet](https://mcmw.abilitynet.org.uk/) has advice on making your device easier to use if you have a disability. 21 | 22 | ## How accessible this website is 23 | 24 | We know some parts of this website are not fully accessible for the following reasons: 25 | 26 | - one page has a redundant link 27 | - there are issues caused by our Technical Documentation Template 28 | 29 | ## Feedback and contact information 30 | 31 | If you need any part of this service in a different format like large print, audio recording or braille, email [api-standards-request@digital.cabinet-office.gov.uk](mailto:api-standards-request@digital.cabinet-office.gov.uk). 32 | 33 | We’ll aim to get back to you within 2 working days. 34 | 35 | ## Reporting accessibility problems with this website 36 | 37 | We’re always looking to improve the accessibility of this website. If you find any problems not listed on this page or think we’re not meeting accessibility requirements, email [api-standards-request@digital.cabinet-office.gov.uk](mailto:api-standards-request@digital.cabinet-office.gov.uk). 38 | 39 | ## Enforcement procedure 40 | 41 | The Equality and Human Rights Commission (EHRC) is responsible for enforcing the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018 42 | (the ‘accessibility regulations’). If you’re not happy with how we respond to your complaint, [contact the Equality Advisory and Support Service (EASS)](https://www.equalityadvisoryservice.com/). 43 | 44 | ## Technical information about this website’s accessibility 45 | 46 | GDS is committed to making its website accessible, in accordance with the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018. 47 | 48 | ## Compliance status 49 | 50 | This website is partially compliant with the [Web Content Accessibility Guidelines version 2.1](https://www.w3.org/TR/WCAG21/) AA standard, due to the non-compliances listed below. 51 | 52 | ### Non-accessible content 53 | 54 | The content listed below is non-accessible for the following reasons. 55 | 56 | #### Non-compliance with the accessibility regulations 57 | 58 | The [GOV.UK Platform as a Service (PaaS) page](https://www.api.gov.uk/central/gds/paas/#gov-uk-platform-as-a-service-paas) has a redundant link. This is not a fail, but should be changed under [WCAG 2.1 success criterion 2.4.4 Link Purpose (In Context)](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-refs.html). 59 | 60 | Also, some parts of this website are not fully accessible because of [issues caused by our Technical Documentation Template](https://tdt-documentation.london.cloudapps.digital/accessibility/#using-the-technical-documentation-template-for-your-own-documentation). 61 | 62 | ## How we tested this website 63 | 64 | We last tested this website for accessibility issues in September 2020. 65 | 66 | We used manual and automated tests to look for issues such as: 67 | 68 | - lack of keyboard accessibility 69 | - link text that’s not descriptive 70 | - non-unique or non-hierarchical headings 71 | - italics, bold and block capital formatting 72 | - inaccessible formatting in general 73 | - inaccessible language 74 | - inaccessible diagrams or images 75 | - lack of colour contrast for text, important graphics and controls 76 | - images not having meaningful alt text 77 | - problems when using assistive technologies such as screen readers and screen magnifiers 78 | 79 | ## What we’re doing to improve accessibility 80 | 81 | We plan to change the redundant links and fix the accessibility issues with the Technical Documentation Template by the end of 2020. 82 | 83 | ## Preparation of this accessibility statement 84 | 85 | This statement was prepared on 4 September 2020. It was last reviewed on 4 September 2020. 86 | 87 | This website was last tested in September 2020. The test was carried out by the technical writing team at GDS. We used the [WAVE Web Accessibility Evaluation Tool](https://wave.webaim.org/) and a checklist we created with the help of the GDS accessibility team. We tested all the website's pages. 88 | -------------------------------------------------------------------------------- /standards-catalogue/source/stylesheets/modules/_technical-documentation.scss: -------------------------------------------------------------------------------- 1 | .technical-documentation { 2 | @include govuk-font($size: 19, $line-height: 1.4); 3 | // Required for IE11 to render
    correctly 4 | display: block; 5 | margin: govuk-spacing(3); 6 | max-width: 40em; 7 | 8 | color: $govuk-text-colour; 9 | 10 | @include govuk-media-query(tablet) { 11 | margin: 0 govuk-spacing(6) govuk-spacing(6); 12 | } 13 | 14 | .has-search-results-open & { 15 | visibility: hidden; 16 | } 17 | 18 | > h1 { 19 | @extend %govuk-heading-xl; 20 | 21 | &:first-of-type { 22 | padding-top: govuk-spacing(6); 23 | } 24 | } 25 | 26 | > h2 { 27 | @extend %govuk-heading-l; 28 | padding-top: govuk-spacing(6); 29 | margin-top: govuk-spacing(3); 30 | } 31 | 32 | > h3 { 33 | @extend %govuk-heading-m; 34 | } 35 | 36 | > h4 { 37 | @extend %govuk-heading-s; 38 | } 39 | 40 | > p { 41 | @extend %govuk-body-m; 42 | } 43 | 44 | > strong, 45 | > b { 46 | @include govuk-typography-weight-bold; 47 | } 48 | 49 | > ul, 50 | > ol { 51 | @extend %govuk-list; 52 | } 53 | 54 | > ol { 55 | @extend %govuk-list--number; 56 | } 57 | 58 | > ul { 59 | @extend %govuk-list--bullet; 60 | } 61 | 62 | a { 63 | @extend %govuk-link; 64 | } 65 | 66 | > a { 67 | @extend %govuk-body-m; 68 | } 69 | 70 | hr { 71 | @extend %govuk-section-break; 72 | @extend %govuk-section-break--visible; 73 | @extend %govuk-section-break--xl; 74 | } 75 | 76 | table { 77 | @include govuk-responsive-margin(6, "bottom"); 78 | } 79 | 80 | pre + h2 { 81 | padding-top: govuk-spacing(4); 82 | } 83 | 84 | pre + h3, 85 | pre + h4 { 86 | padding-top: govuk-spacing(2); 87 | } 88 | 89 | img { 90 | max-width: 100%; 91 | width: auto; 92 | height: auto; 93 | } 94 | 95 | ol + p, ul + p, .table-container + p { 96 | margin-top: ceil(govuk-spacing(6) * (16 / 19)); 97 | 98 | @include govuk-media-query(tablet) { 99 | margin-top: govuk-spacing(6); 100 | } 101 | } 102 | 103 | blockquote { 104 | @include govuk-font($size: 19); 105 | background: govuk-colour("light-grey"); 106 | padding: govuk-spacing(3); 107 | margin: govuk-spacing(3); 108 | border-left: govuk-spacing(2) solid govuk-colour("mid-grey"); 109 | } 110 | 111 | // http://code.iamkate.com/html-and-css/fixing-browsers-broken-monospace-font-handling/ 112 | pre, 113 | code { 114 | // Restores the normal text size in Mozilla Firefox, Google Chrome, and Safari; this unusual style rule should also be used anywhere where you would otherwise set the font-family property to ‘monospace’. 115 | font-family: monospace, monospace; 116 | // Restores the normal text size in Internet Explorer and Opera. 117 | font-size: 1em; 118 | } 119 | 120 | pre { 121 | background: scale-color(govuk-colour("light-grey"), $lightness:50%); 122 | padding: 15px; 123 | overflow: auto; 124 | position: relative; 125 | border: 1px solid #bfc1c3; 126 | } 127 | 128 | pre code { 129 | background: none; 130 | color: inherit; 131 | padding: 0; 132 | } 133 | 134 | code { 135 | background: #f5f5f5; 136 | padding: 3px govuk-spacing(1); 137 | border-radius: 1px; 138 | 139 | font-family: monaco, Consolas, "Lucida Console", monospace; 140 | font-size: 15px; 141 | font-size: 0.9375rem; 142 | // Match the line-height outside of tables 143 | line-height: 1.4; 144 | color: #a71d5d; 145 | 146 | @include govuk-media-query(tablet) { 147 | font-size: 16px; 148 | font-size: 1rem; 149 | } 150 | 151 | // Handle long strings (URLs, long variable names, etc) by allowing them 152 | // to break anywhere if required. 153 | overflow-wrap: break-word; 154 | word-wrap: break-word; 155 | 156 | -ms-word-break: break-all; 157 | /* This is the dangerous one in WebKit, as it breaks things wherever */ 158 | word-break: break-all; 159 | /* Instead use this non-standard one: */ 160 | word-break: break-word; 161 | } 162 | 163 | // Support monospace headings for e.g. listing API endpoints 164 | h1, h2, h3, h4, h5, h6 { 165 | code { 166 | font-size: inherit; 167 | color: $govuk-text-colour; 168 | background: none; 169 | padding: 0; 170 | } 171 | } 172 | 173 | // Ensure that if a code element is wrapped with a link that it renders correctly. 174 | a code { 175 | color: inherit; 176 | } 177 | 178 | a:focus code { 179 | background: inherit; 180 | color: inherit; 181 | } 182 | 183 | .table-container { 184 | display: block; 185 | max-width: 100%; 186 | overflow-x: auto; 187 | 188 | margin-top: govuk-spacing(3); 189 | } 190 | 191 | table { 192 | width: 100%; 193 | 194 | border-collapse: collapse; 195 | border-spacing: 0; 196 | } 197 | 198 | th, td { 199 | padding: govuk-spacing(2) govuk-spacing(4) govuk-spacing(2) 0; 200 | 201 | background-color: transparent; 202 | border-bottom: 1px solid $govuk-border-colour; 203 | border-width: 0 0 1px 0; 204 | 205 | @include govuk-font($size: 16); 206 | vertical-align: top; 207 | text-align: left; 208 | } 209 | 210 | th { 211 | font-weight: bold; 212 | } 213 | 214 | td { 215 | p, ul, ol { 216 | margin: 0; 217 | } 218 | p+p, p+ul, p+ol, 219 | ul+p, ul+ol, 220 | ol+p { 221 | margin-top: govuk-spacing(2); 222 | } 223 | } 224 | } 225 | -------------------------------------------------------------------------------- /content/guidance/apimanagement/APIM-Deployment.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: APIM - 03 - Deployment 3 | weight: 833 4 | keywords: 'API Management' 5 | identifier: DSA-003 6 | name: APIManagement 7 | organisation: Data Standards Authority 8 | author_email: api-programme@digital.cabinet-office.gov.uk 9 | status: Draft 10 | startDate: 2021-03-23 11 | dateAdded: 2021-03-23 12 | dateUpdated: 2021-04-28 13 | --- 14 | 15 | ## Deployment 16 | 17 | 18 | _This is a DRAFT document for discussion. This is not finalised. All aspects of this document are subject to change. Please leave comments on any aspect of it._ 19 | 20 | #### Contents: 21 | - [01 - Introduction](APIM-Introduction.html) 22 | - [02 - Design](APIM-Design.html) 23 | - [03 - Deployment](APIM-Deployment.html) 24 | - [04 - Management](APIM-Management.html) 25 | - [05 - Discovery](APIM-Discovery.html) 26 | - [06 - Retirement](APIM-Retirement.html) 27 | 28 | 29 | Deploying your API involves more than just pushing code. There are a number of things you should put in place to support the publishing process. Assurance and testing processes ensure APIs meet requirements and function properly, and developer resources help consumers through the lifecycle of their integration. 30 | 31 | ### Assurance and assessment 32 | 33 | Assurance is part of governance, and is the process of making sure that APIs meet various organisational standards. For example, an assurance process will help teams make sure they are building APIs to follow the design guidelines of your organisation. 34 | 35 | Assurance is likely to be a review session, and might include assessment on API: 36 | 37 | * resourcing 38 | * user journeys 39 | * middleware 40 | * domain modelling 41 | * publishing 42 | 43 | Your assurance assessment programme should make sense for the teams who need to go through it. If development teams find the assurance process too rigid, they might try to avoid it, which will weaken your organisation’s governance model. Think about how you can make governance as light touch as possible, and how you can make it a positive experience for product teams. If review sessions have good outcomes for teams and provide them with useful feedback, other teams are more likely to submit to it. As a result your governance model will be more successfully embedded into organisational culture. 44 | 45 | ### Testing 46 | 47 | Testing is the process of making sure the APIs function properly, and is more likely to be an automatic process which validates the code. Testing should be an ongoing process, and regular validation of the API should be part of a monitoring scheme. 48 | 49 | Usually, testing is done by an automated tool against the specification, sometimes known as the contract. Contract testing in its simplest form includes: 50 | 51 | * checking the specification against internal policies to make sure that APIs submitted to the developer portal are compliant with internal standards 52 | * checking the API to make sure its responses match the specification and that deployed APIs are behaving correctly in production 53 | 54 | ### Developer portal 55 | 56 | A developer portal, also sometimes called a developer hub, is where developers can access everything they need to set up and manage their integration with your API. This usually includes: 57 | 58 | * documentation for your API 59 | * developer authorisation 60 | * self service tools for things like renewing API keys and changing their password 61 | * a test environment - for example a mock API, a ‘sandbox’ and test users 62 | * issue reporting and ticket support 63 | 64 | You can also use your developer portal to gather internal metrics about your API programme. For example, you might want to measure how quickly developers are able to set up a test version of an API. This is sometimes known as “time to live” or “time to 200” and is a useful metric to measure how easy your API is to integrate. It can also help you identify where there might be pain points for users. 65 | 66 | ### Documentation 67 | 68 | Your API documentation is the starting point for developers looking to use your API. 69 | 70 | You can use an API specification to generate and auto-update reference documentation for your API as you build and iterate it. However, do not rely solely on auto-generated documentation as it’s important to also include conceptual or practical documentation to provide developers with more context. 71 | 72 | You should work with a [technical writer](https://www.gov.uk/guidance/technical-writer) from the very start of your project. If you don’t have technical writing resources in your organisation, you can reach out to the [cross-government technical writing community](https://www.gov.uk/service-manual/communities/technical-writing-community). 73 | 74 | You can use the [GDS Technical Documentation Template](https://tdt-documentation.london.cloudapps.digital/#technical-documentation-template) to generate accessible documentation pages from simple Markdown files. It’s mainly used for standalone documentations sites (for example [GOV.UK Pay’s API documentation](https://docs.payments.service.gov.uk/#gov-uk-pay-technical-documentation)). The Tech Docs Template is a Middleman template, so if you’re using an API management tool, you might be able to build the template into your generated documentation.. 75 | 76 | Read the guidance on [how to document APIs](https://www.gov.uk/guidance/how-to-document-apis) and [writing API reference documentation](https://www.gov.uk/guidance/writing-api-reference-documentation). 77 | 78 | 79 | #### Contents: 80 | - [01 - Introduction](APIM-Introduction.html) 81 | - [02 - Design](APIM-Design.html) 82 | - [03 - Deployment](APIM-Deployment.html) 83 | - [04 - Management](APIM-Management.html) 84 | - [05 - Discovery](APIM-Discovery.html) 85 | - [06 - Retirement](APIM-Retirement.html) 86 | 87 | 88 | [Next](APIM-Management.html) 89 | -------------------------------------------------------------------------------- /content/guidance/addressbase/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Access and record address data using the UPRN standard and AddressBase 3 | weight: 813 4 | keywords: 'AddressBase' 5 | identifier: DSA-001 6 | name: AddressBase 7 | organisation: Data Standards Authority 8 | status: published 9 | startDate: 10 | dateAdded: 2021-06-28 11 | dateUpdated: 2021-06-28 12 | --- 13 | 14 | *This is a DRAFT document for discussion. This is not finalised. All aspects of this document are subject to change. Please leave comments on any aspect of it.* 15 | 16 | DRAFT Access and record address data using the UPRN standard and AddressBase DRAFT 17 | ====================================================================== 18 | 19 | ### Use free property and street information to add geospatial data to your projects 20 | 21 | Follow this guidance if you're a public sector employee who needs to use address data, such as property and street information, in your work. 22 | 23 | The guidance shares best practice in accessing address data using Ordnance Survey (OS) [AddressBase](https://www.ordnancesurvey.co.uk/business-government/products/addressbase). This is a way to access essential geospatial data which is free for public sector workers as part of the [Public Sector Geospatial Agreement (PSGA)](https://www.ordnancesurvey.co.uk/business-government/public-sector-geospatial-agreement). 24 | 25 | [AddressBase Core](https://www.ordnancesurvey.co.uk/business-government/products/addressbase-core) is a free and easy way for public sector bodies to identify a property in Great Britain and locate it on a map with precision. The property has to exist, and not have been demolished, or yet to be built. 26 | 27 | All public sector bodies should [use AddressBase Core](https://www.ordnancesurvey.co.uk/business-government/products/addressbase-core) for accessing address data rather than paying for other third party products. To be able to use AddressBase products for free, your organisation or project must be covered by the Public Sector Geospatial Agreement. You can [check if you are covered by the PSGA and if not, register for a membership](https://www.ordnancesurvey.co.uk/business-government/partner-member/member). 28 | 29 | Use the UPRN standard to identify property and street information 30 | ----------------------------------------------------------------- 31 | 32 | AddressBase Core allows you to access every [Unique Property Reference Number (UPRN)](https://www.geoplace.co.uk/addresses/uprn) in Great Britain. 33 | 34 | You must use the [UPRN](https://www.geoplace.co.uk/addresses/uprn) standard when [identifying places in the UK](https://www.gov.uk/government/publications/open-standards-for-government/identifying-property-and-street-information). This allows users to easily cross-reference between different data sets and means fewer errors in data exchange and communication. Every addressable location in Great Britain has a UPRN, and using this consistent standard can save money, time, resources, and lives. 35 | 36 | You should consider AddressBase your source of truth for all address data in Great Britain, and use AddressBase Core whenever possible before other solutions. 37 | 38 | Why you should use AddressBase 39 | ------------------------------ 40 | 41 | AddressBase's primary source of address data is taken from local authorities. Local authorities have a legal responsibility to capture and maintain address data for Great Britain. 42 | 43 | This means AddressBase's data is authentic and accurate. It includes locations for around 33 million addresses, as well as additional metadata. 44 | 45 | The core underlying data is updated constantly, many times a day. OS collate and quality check the data, and publish a new version of the whole data set on AddressBase every week. 46 | 47 | You can use AddressBase to: 48 | 49 | - include address data in any activity you are responsible for, as long as it is non-profit 50 | 51 | - make any information you have created that includes AddressBase data in print, online and as data - such as a CSV or an API - available to the public 52 | 53 | - meet your [INSPIRE publishing obligations](https://www.legislation.gov.uk/uksi/2018/1338/contents/made), making sure geospatial data is published in a consistent way 54 | 55 | - share address data with anybody who is involved in providing an immediate response in emergency situations, even if they are not licensed to use OS data 56 | 57 | - produce data suitable for third party research and development 58 | 59 | To be able to use AddressBase Core, your organisation or project must be covered by the Public Sector Geospatial Agreement. You should [check if you are covered by the PSGA and if not, register for a membership](https://www.ordnancesurvey.co.uk/business-government/partner-member/member). 60 | 61 | Check other resources for finding geospatial data beyond AddressBase Core 62 | ------------------------------------------------------------------------- 63 | 64 | If you need further geospatial data, including map tiles, searching within polygons, and data verification, you can use the OS [Places API](https://www.ordnancesurvey.co.uk/business-government/products/os-places-api). This API is also covered by the PSGA and is free to members. 65 | 66 | If your project or use case needs more advanced or specific features, there are other versions of AddressBase available. These include: 67 | 68 | - [AddressBase Plus](https://www.ordnancesurvey.co.uk/business-government/products/addressbase-plus) for up-to-date local authority addresses, multi-occupancy addresses and OS MasterMap Topographic Identifier (TOID) references. 69 | 70 | - [AddressBase Premium](https://www.ordnancesurvey.co.uk/business-government/products/addressbase-premium) which includes data in Geography Markup Language (GML) 3.2.1 of pre-build addresses, historic addresses, alternative addresses, OS MasterMap Topography and Integrated Transport Network Layer TOIDs 71 | 72 | - [AddressBase Islands](https://www.ordnancesurvey.co.uk/business-government/products/addressbase-islands) for address data in Northern Ireland, Isle of Man and the Channel Islands\ 73 | You can find more information about other AddressBase features, as well as contact details, [on OS's AddressBase website](https://www.ordnancesurvey.co.uk/business-government/products/addressbase). 74 | -------------------------------------------------------------------------------- /content/guidance/apimanagement/APIM-Introduction.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: APIM - 01 - Introduction 3 | weight: 831 4 | keywords: 'API Management' 5 | identifier: DSA-003 6 | name: APIManagement 7 | organisation: Data Standards Authority 8 | author_email: api-programme@digital.cabinet-office.gov.uk 9 | status: Draft 10 | startDate: 2021-03-23 11 | dateAdded: 2021-03-23 12 | dateUpdated: 2021-04-28 13 | --- 14 | 15 | 16 | ## Define an API management strategy 17 | 18 | _This is a DRAFT document for discussion. This is not finalised. All aspects of this document are subject to change. Please leave comments on any aspect of it._ 19 | 20 | #### Contents: 21 | - [01 - Introduction](APIM-Introduction.html) 22 | - [02 - Design](APIM-Design.html) 23 | - [03 - Deployment](APIM-Deployment.html) 24 | - [04 - Management](APIM-Management.html) 25 | - [05 - Discovery](APIM-Discovery.html) 26 | - [06 - Retirement](APIM-Retirement.html) 27 | 28 | 29 | ### API management tools help reduce development overhead and time to deployment by standardising design, monitoring, security and other aspects of the API life cycle. 30 | 31 | Good API governance comes from good API management, from design to deprecation. 32 | 33 | If you build or manage any number of APIs, it’s best practice to have API management in place. This guidance will outline some areas you should consider when making decisions about how to manage APIs in your team or organisation. 34 | 35 | 36 | ## Principles for your API strategy 37 | 38 | ### Build foundations early 39 | If you have any APIs that need access management, monitoring or documentation, you should at the very least use an API gateway. Even a single API will benefit from the standardised tools that an API gateway provides, by not having to develop and deploy those elements of functionality. If you later build more APIs, having an API gateway in place already will mean you don’t have to build those tools again, reducing duplication of effort for future teams. 40 | 41 | There will be cases where your current ecosystem doesn’t fit with this model, perhaps because you already have APIs in production which have their own security or monitoring, or because the APIs have been developed using disparate methods and technologies, in which case you should think about how you can put in place standardised patterns. This is about processes and governance that teams will use to build and deploy APIs, rather than the specific technology they use. As an example, you should consider how prescriptive you want your publishing pipeline to be. You might decide to have strict rules only for certain things like security, while allowing other areas to be more flexible. 42 | 43 | ### Keep the future in mind 44 | When putting together your API strategy, it’s important to consider what your organisation’s future needs are likely to be, not just think about the first few APIs. 45 | 46 | Maintain a high level view of your API ecosystem. Good API management provides a way to judge the maturity of an individual API compared to others in the estate, and allows you to determine how much resource needs to be invested in it. APIs at different stages of their life cycle require different levels of investment - a coherent strategy allows you to identify these needs and meet them. 47 | 48 | ### Meet user needs 49 | You should also think how your decisions might affect user behaviour. For example, you might decide that only APIs which have been through the process of assurance and testing will be visible in your catalogue. This might make teams reluctant to try new solutions that don’t fit the pattern, which could discourage innovation. Teams who aren’t ready to standardise or hand off management might simply not use it, and instead deploy APIs in an ad-hoc way. 50 | 51 | User research can help you gain insight on how teams are producing and consuming APIs, or what technologies they are using or considering using. 52 | 53 | A robust API management process will help build credibility and trust with users of your APIs. It’s important to demonstrate that your APIs are well designed and well supported. For example, being clear about how you retire APIs will reassure developers that they will not suddenly lose access to an API without notice. 54 | 55 | ### Define roles 56 | Depending on the size and structure of your organisation, you might have several teams involved in building and maintaining APIs. Your API management strategy can help set out things like: 57 | 58 | * who owns different parts of the API life cycle 59 | * what skills or roles API teams should include 60 | * where ownership of a particular service lies 61 | * how ownership changes as an API goes into service 62 | 63 | For example, it is common for a central team to run the API Gateway, and therefore have control over service levels and capacity. You should then consider how that responsibility might interact with the design and delivery responsibilities of an API owner, such as versioning. 64 | 65 | Having a clear structure for escalating issues will save a lot of time and energy in the future. Support from senior management or stakeholders can help formalise organisational structures and policies. 66 | 67 | ### What API Management strategy can help with 68 | 69 | An API management strategy can: 70 | 71 | * provide visibility of all your APIs, encouraging reuse 72 | * allow you to standardise common design patterns 73 | * help you automate many administrative and operational tasks 74 | * provide a central place for you to share API documentation and support 75 | * provide data and metrics to help you understand your API’s performance and usage 76 | * help you implement and maintain good security and data protection practices 77 | 78 | This guidance includes sections exploring each stage of the API life cycle: 79 | 80 | * Design - guidelines and policies for API production 81 | * Deployment - assessment, testing and rolling out to live 82 | * Management - ongoing maintenance and monitoring 83 | * Discovery - how developers discover your APIs 84 | * Retirement - decommissioning your API when it is no longer needed 85 | 86 | Each stage will benefit from having different tools and processes in place. 87 | 88 | 89 | 90 | #### Contents: 91 | - [01 - Introduction](APIM-Introduction.html) 92 | - [02 - Design](APIM-Design.html) 93 | - [03 - Deployment](APIM-Deployment.html) 94 | - [04 - Management](APIM-Management.html) 95 | - [05 - Discovery](APIM-Discovery.html) 96 | - [06 - Retirement](APIM-Retirement.html) 97 | 98 | 99 | [Next](APIM-Design.html) 100 | -------------------------------------------------------------------------------- /LICENCE.md: -------------------------------------------------------------------------------- 1 | # Open Government Licence v3 2 | 3 | You are encouraged to use and re-use the Information that is available under this licence freely and flexibly, with only a few conditions. 4 | 5 | ## Using Information under this licence 6 | 7 | Use of copyright and database right material expressly made available under this licence (the 'Information') indicates your acceptance of the terms and conditions below. 8 | 9 | The Licensor grants you a worldwide, royalty-free, perpetual, non-exclusive licence to use the Information subject to the conditions below. 10 | 11 | This licence does not affect your freedom under fair dealing or fair use or any other copyright or database right exceptions and limitations. 12 | 13 | ## You are free to: 14 | 15 | * copy, publish, distribute and transmit the Information; 16 | * adapt the Information; 17 | * exploit the Information commercially and non-commercially for example, by combining it with other Information, or by including it in your own product or application. 18 | 19 | ## You must (where you do any of the above): 20 | 21 | * acknowledge the source of the Information in your product or application by including or linking to any attribution statement specified by the Information Provider(s) and, where possible, provide a link to this licence; 22 | 23 | If the Information Provider does not provide a specific attribution statement, you must use the following: 24 | 25 | * Contains public sector information licensed under the Open Government Licence v3.0. 26 | 27 | If you are using Information from several Information Providers and listing multiple attributions is not practical in your product or application, you may include a URI or hyperlink to a resource that contains the required attribution statements. 28 | 29 | These are important conditions of this licence and if you fail to comply with them the rights granted to you under this licence, or any similar licence granted by the Licensor, will end automatically. 30 | 31 | ## Exemptions 32 | 33 | This licence does not cover: 34 | 35 | * personal data in the Information; 36 | * Information that has not been accessed by way of publication or disclosure under information access legislation (including the Freedom of Information Acts for the UK and Scotland) by or with the consent of the Information Provider; 37 | * departmental or public sector organisation logos, crests and the Royal Arms except where they form an integral part of a document or dataset; 38 | * military insignia; 39 | * third party rights the Information Provider is not authorised to license; 40 | * other intellectual property rights, including patents, trade marks, and design rights; and 41 | * identity documents such as the British Passport 42 | 43 | ### Non-endorsement 44 | 45 | This licence does not grant you any right to use the Information in a way that suggests any official status or that the Information Provider and/or Licensor endorse you or your use of the Information. 46 | 47 | ### No warranty 48 | 49 | The Information is licensed 'as is' and the Information Provider and/or Licensor excludes all representations, warranties, obligations and liabilities in relation to the Information to the maximum extent permitted by law. 50 | 51 | The Information Provider and/or Licensor are not liable for any errors or omissions in the Information and shall not be liable for any loss, injury or damage of any kind caused by its use. The Information Provider does not guarantee the continued supply of the Information. 52 | 53 | ### Governing Law 54 | 55 | This licence is governed by the laws of the jurisdiction in which the Information Provider has its principal place of business, unless otherwise specified by the Information Provider. 56 | 57 | ### Definitions 58 | In this licence, the terms below have the following meanings: 59 | 60 | 'Information' means information protected by copyright or by database right (for example, literary and artistic works, content, data and source code) offered for use under the terms of this licence. 61 | 62 | 'Information Provider' means the person or organisation providing the Information under this licence. 63 | 64 | 'Licensor' means any Information Provider which has the authority to offer Information under the terms of this licence or the Keeper of Public Records, who has the authority to offer Information subject to Crown copyright and Crown database rights and Information subject to copyright and database right that has been assigned to or acquired by the Crown, under the terms of this licence. 65 | 66 | 'Use' means doing any act which is restricted by copyright or database right, whether in the original medium or in any other medium, and includes without limitation distributing, copying, adapting, modifying as may be technically necessary to use it in a different mode or format. 67 | 68 | 'You', 'you' and 'your' means the natural or legal person, or body of persons corporate or incorporate, acquiring rights in the Information (whether the Information is obtained directly from the Licensor or otherwise) under this licence. 69 | 70 | ### About the Open Government Licence 71 | 72 | The National Archives has developed this licence as a tool to enable Information Providers in the public sector to license the use and re-use of their Information under a common open licence. The National Archives invites public sector bodies owning their own copyright and database rights to permit the use of their Information under this licence. 73 | 74 | The Keeper of the Public Records has authority to license Information subject to copyright and database right owned by the Crown. The extent of the offer to license this Information under the terms of this licence is set out in the [UK Government Licensing Framework](http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/re-use-and-licensing/ukglf/). 75 | 76 | This is version 3.0 of the Open Government Licence. The National Archives may, from time to time, issue new versions of the Open Government Licence. If you are already using Information under a previous version of the Open Government Licence, the terms of that licence will continue to apply. 77 | 78 | These terms are compatible with the Creative Commons Attribution License 4.0 and the Open Data Commons Attribution License, both of which license copyright and database rights. This means that when the Information is adapted and licensed under either of those licences, you automatically satisfy the conditions of the OGL when you comply with the other licence. The OGLv3.0 is Open Definition compliant. 79 | 80 | Further context, best practice and guidance can be found in the [UK Government Licensing Framework section](http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/) on The National Archives website. 81 | -------------------------------------------------------------------------------- /standards-catalogue/source/javascripts/_vendor/fixedsticky.js: -------------------------------------------------------------------------------- 1 | // https://github.com/filamentgroup/fixed-sticky 2 | ;(function( win, $ ) { 3 | 4 | function featureTest( property, value, noPrefixes ) { 5 | // Thanks Modernizr! https://github.com/phistuck/Modernizr/commit/3fb7217f5f8274e2f11fe6cfeda7cfaf9948a1f5 6 | var prop = property + ':', 7 | el = document.createElement( 'test' ), 8 | mStyle = el.style; 9 | 10 | if( !noPrefixes ) { 11 | mStyle.cssText = prop + [ '-webkit-', '-moz-', '-ms-', '-o-', '' ].join( value + ';' + prop ) + value + ';'; 12 | } else { 13 | mStyle.cssText = prop + value; 14 | } 15 | return mStyle[ property ].indexOf( value ) !== -1; 16 | } 17 | 18 | function getPx( unit ) { 19 | return parseInt( unit, 10 ) || 0; 20 | } 21 | 22 | var uniqueIdCounter = 0; 23 | 24 | var S = { 25 | classes: { 26 | plugin: 'fixedsticky', 27 | active: 'fixedsticky-on', 28 | inactive: 'fixedsticky-off', 29 | clone: 'fixedsticky-dummy', 30 | withoutFixedFixed: 'fixedsticky-withoutfixedfixed' 31 | }, 32 | keys: { 33 | offset: 'fixedStickyOffset', 34 | position: 'fixedStickyPosition', 35 | id: 'fixedStickyId' 36 | }, 37 | tests: { 38 | sticky: featureTest( 'position', 'sticky' ), 39 | fixed: featureTest( 'position', 'fixed', true ) 40 | }, 41 | // Thanks jQuery! 42 | getScrollTop: function() { 43 | var prop = 'pageYOffset', 44 | method = 'scrollTop'; 45 | return win ? (prop in win) ? win[ prop ] : 46 | win.document.documentElement[ method ] : 47 | win.document.body[ method ]; 48 | }, 49 | bypass: function() { 50 | // Check native sticky, check fixed and if fixed-fixed is also included on the page and is supported 51 | return ( S.tests.sticky && !S.optOut ) || 52 | !S.tests.fixed || 53 | win.FixedFixed && !$( win.document.documentElement ).hasClass( 'fixed-supported' ); 54 | }, 55 | update: function( el ) { 56 | if( !el.offsetWidth ) { return; } 57 | 58 | var $el = $( el ), 59 | height = $el.outerHeight(), 60 | initialOffset = $el.data( S.keys.offset ), 61 | scroll = S.getScrollTop(), 62 | isAlreadyOn = $el.is( '.' + S.classes.active ), 63 | toggle = function( turnOn ) { 64 | $el[ turnOn ? 'addClass' : 'removeClass' ]( S.classes.active ) 65 | [ !turnOn ? 'addClass' : 'removeClass' ]( S.classes.inactive ); 66 | }, 67 | viewportHeight = $( window ).height(), 68 | position = $el.data( S.keys.position ), 69 | skipSettingToFixed, 70 | elTop, 71 | elBottom, 72 | $parent = $el.parent(), 73 | parentOffset = $parent.offset().top, 74 | parentHeight = $parent.outerHeight(); 75 | 76 | if( initialOffset === undefined ) { 77 | initialOffset = $el.offset().top; 78 | $el.data( S.keys.offset, initialOffset ); 79 | $el.after( $( '
    ' ).addClass( S.classes.clone ).height( height ) ); 80 | } else { 81 | $el.next( '.' + S.classes.clone ).height( height ); 82 | } 83 | 84 | if( !position ) { 85 | // Some browsers require fixed/absolute to report accurate top/left values. 86 | skipSettingToFixed = $el.css( 'top' ) !== 'auto' || $el.css( 'bottom' ) !== 'auto'; 87 | 88 | if( !skipSettingToFixed ) { 89 | $el.css( 'position', 'fixed' ); 90 | } 91 | 92 | position = { 93 | top: $el.css( 'top' ) !== 'auto', 94 | bottom: $el.css( 'bottom' ) !== 'auto' 95 | }; 96 | 97 | if( !skipSettingToFixed ) { 98 | $el.css( 'position', '' ); 99 | } 100 | 101 | $el.data( S.keys.position, position ); 102 | } 103 | 104 | function isFixedToTop() { 105 | var offsetTop = scroll + elTop; 106 | 107 | // Initial Offset Top 108 | return initialOffset < offsetTop && 109 | // Container Bottom 110 | offsetTop + height <= parentOffset + parentHeight; 111 | } 112 | 113 | function isFixedToBottom() { 114 | // Initial Offset Top + Height 115 | return initialOffset + ( height || 0 ) > scroll + viewportHeight - elBottom && 116 | // Container Top 117 | scroll + viewportHeight - elBottom >= parentOffset + ( height || 0 ); 118 | } 119 | 120 | elTop = getPx( $el.css( 'top' ) ); 121 | elBottom = getPx( $el.css( 'bottom' ) ); 122 | 123 | if( position.top && isFixedToTop() || position.bottom && isFixedToBottom() ) { 124 | if( !isAlreadyOn ) { 125 | toggle( true ); 126 | } 127 | } else { 128 | if( isAlreadyOn ) { 129 | toggle( false ); 130 | } 131 | } 132 | }, 133 | destroy: function( el ) { 134 | var $el = $( el ); 135 | if (S.bypass()) { 136 | return $el; 137 | } 138 | 139 | return $el.each(function() { 140 | var $this = $( this ); 141 | var id = $this.data( S.keys.id ); 142 | $( win ).unbind( '.fixedsticky' + id ); 143 | 144 | $this 145 | .removeData( [ S.keys.offset, S.keys.position, S.keys.id ] ) 146 | .removeClass( S.classes.active ) 147 | .removeClass( S.classes.inactive ) 148 | .next( '.' + S.classes.clone ).remove(); 149 | }); 150 | }, 151 | init: function( el ) { 152 | var $el = $( el ); 153 | 154 | if( S.bypass() ) { 155 | return $el; 156 | } 157 | 158 | return $el.each(function() { 159 | var _this = this; 160 | var id = uniqueIdCounter++; 161 | $( this ).data( S.keys.id, id ); 162 | 163 | $( win ).bind( 'scroll.fixedsticky' + id, function() { 164 | S.update( _this ); 165 | }).trigger( 'scroll.fixedsticky' + id ); 166 | 167 | $( win ).bind( 'resize.fixedsticky' + id , function() { 168 | if( $el.is( '.' + S.classes.active ) ) { 169 | S.update( _this ); 170 | } 171 | }); 172 | }); 173 | } 174 | }; 175 | 176 | win.FixedSticky = S; 177 | 178 | // Plugin 179 | $.fn.fixedsticky = function( method ) { 180 | if ( typeof S[ method ] === 'function') { 181 | return S[ method ].call( S, this); 182 | } else if ( typeof method === 'object' || ! method ) { 183 | return S.init.call( S, this ); 184 | } else { 185 | throw new Error( 'Method `' + method + '` does not exist on jQuery.fixedsticky' ); 186 | } 187 | }; 188 | 189 | // Add fallback when fixed-fixed is not available. 190 | if( !win.FixedFixed ) { 191 | $( win.document.documentElement ).addClass( S.classes.withoutFixedFixed ); 192 | } 193 | 194 | })( window, jQuery ); 195 | -------------------------------------------------------------------------------- /standards-catalogue/Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | activesupport (7.0.7) 5 | concurrent-ruby (~> 1.0, >= 1.0.2) 6 | i18n (>= 1.6, < 2) 7 | minitest (>= 5.1) 8 | tzinfo (~> 2.0) 9 | addressable (2.8.5) 10 | public_suffix (>= 2.0.2, < 6.0) 11 | ast (2.4.2) 12 | autoprefixer-rails (10.4.13.0) 13 | execjs (~> 2) 14 | backports (3.24.1) 15 | chunky_png (1.4.0) 16 | coderay (1.1.3) 17 | coffee-script (2.4.1) 18 | coffee-script-source 19 | execjs 20 | coffee-script-source (1.12.2) 21 | compass (1.0.3) 22 | chunky_png (~> 1.2) 23 | compass-core (~> 1.0.2) 24 | compass-import-once (~> 1.0.5) 25 | rb-fsevent (>= 0.9.3) 26 | rb-inotify (>= 0.9) 27 | sass (>= 3.3.13, < 3.5) 28 | compass-core (1.0.3) 29 | multi_json (~> 1.0) 30 | sass (>= 3.3.0, < 3.5) 31 | compass-import-once (1.0.5) 32 | sass (>= 3.2, < 3.5) 33 | concurrent-ruby (1.2.2) 34 | contracts (0.17) 35 | diff-lcs (1.5.0) 36 | dotenv (2.8.1) 37 | em-websocket (0.5.3) 38 | eventmachine (>= 0.12.9) 39 | http_parser.rb (~> 0) 40 | erubis (2.7.0) 41 | eventmachine (1.2.7) 42 | execjs (2.8.1) 43 | factory_bot (6.2.1) 44 | activesupport (>= 5.0.0) 45 | fast_blank (1.0.1) 46 | fastimage (2.2.7) 47 | ffi (1.15.5) 48 | haml (6.1.2) 49 | temple (>= 0.8.2) 50 | thor 51 | tilt 52 | hamster (3.0.0) 53 | concurrent-ruby (~> 1.0) 54 | hashie (3.6.0) 55 | http_parser.rb (0.8.0) 56 | i18n (1.6.0) 57 | concurrent-ruby (~> 1.0) 58 | json (2.6.3) 59 | json-schema (4.0.0) 60 | addressable (>= 2.8) 61 | kramdown (2.4.0) 62 | rexml 63 | language_server-protocol (3.17.0.3) 64 | listen (3.8.0) 65 | rb-fsevent (~> 0.10, >= 0.10.3) 66 | rb-inotify (~> 0.9, >= 0.9.10) 67 | memoist (0.16.2) 68 | method_source (1.0.0) 69 | middleman (4.5.0) 70 | coffee-script (~> 2.2) 71 | haml (>= 4.0.5) 72 | kramdown (>= 2.3.0) 73 | middleman-cli (= 4.5.0) 74 | middleman-core (= 4.5.0) 75 | middleman-autoprefixer (3.0.0) 76 | autoprefixer-rails (~> 10.0) 77 | middleman-core (>= 4.0.0) 78 | middleman-cli (4.5.0) 79 | thor (>= 0.17.0, < 2.0) 80 | middleman-compass (4.0.1) 81 | compass (>= 1.0.0, < 2.0.0) 82 | middleman-core (>= 4.0.0) 83 | middleman-core (4.5.0) 84 | activesupport (>= 6.1, < 7.1) 85 | addressable (~> 2.4) 86 | backports (~> 3.6) 87 | bundler (~> 2.0) 88 | contracts (~> 0.13) 89 | dotenv 90 | erubis 91 | execjs (~> 2.0) 92 | fast_blank 93 | fastimage (~> 2.0) 94 | hamster (~> 3.0) 95 | hashie (~> 3.4) 96 | i18n (~> 1.6.0) 97 | listen (~> 3.0) 98 | memoist (~> 0.14) 99 | padrino-helpers (~> 0.15.0) 100 | parallel 101 | rack (>= 1.4.5, < 3) 102 | sassc (~> 2.0) 103 | servolux 104 | tilt (~> 2.0.9) 105 | toml 106 | uglifier (~> 3.0) 107 | webrick 108 | middleman-livereload (3.4.7) 109 | em-websocket (~> 0.5.1) 110 | middleman-core (>= 3.3) 111 | rack-livereload (~> 0.3.15) 112 | middleman-search-gds (0.11.2) 113 | execjs (~> 2.6) 114 | middleman-core (>= 3.2) 115 | nokogiri (~> 1.6) 116 | middleman-sprockets (4.1.1) 117 | middleman-core (~> 4.0) 118 | sprockets (>= 3.0) 119 | minitest (5.19.0) 120 | multi_json (1.15.0) 121 | nokogiri (1.15.4-arm64-darwin) 122 | racc (~> 1.4) 123 | nokogiri (1.15.4-x86_64-linux) 124 | racc (~> 1.4) 125 | padrino-helpers (0.15.3) 126 | i18n (>= 0.6.7, < 2) 127 | padrino-support (= 0.15.3) 128 | tilt (>= 1.4.1, < 3) 129 | padrino-support (0.15.3) 130 | parallel (1.23.0) 131 | parser (3.2.2.3) 132 | ast (~> 2.4.1) 133 | racc 134 | parslet (2.0.0) 135 | pry (0.14.2) 136 | coderay (~> 1.1) 137 | method_source (~> 1.0) 138 | public_suffix (5.0.3) 139 | racc (1.7.1) 140 | rack (2.2.8) 141 | rack-livereload (0.3.17) 142 | rack 143 | rainbow (3.1.1) 144 | rake (13.0.6) 145 | rb-fsevent (0.11.2) 146 | rb-inotify (0.10.1) 147 | ffi (~> 1.0) 148 | redcarpet (3.6.0) 149 | regexp_parser (2.8.1) 150 | rexml (3.2.6) 151 | rspec (3.12.0) 152 | rspec-core (~> 3.12.0) 153 | rspec-expectations (~> 3.12.0) 154 | rspec-mocks (~> 3.12.0) 155 | rspec-core (3.12.2) 156 | rspec-support (~> 3.12.0) 157 | rspec-expectations (3.12.3) 158 | diff-lcs (>= 1.2.0, < 2.0) 159 | rspec-support (~> 3.12.0) 160 | rspec-mocks (3.12.6) 161 | diff-lcs (>= 1.2.0, < 2.0) 162 | rspec-support (~> 3.12.0) 163 | rspec-support (3.12.1) 164 | rubocop (1.55.0) 165 | json (~> 2.3) 166 | language_server-protocol (>= 3.17.0) 167 | parallel (~> 1.10) 168 | parser (>= 3.2.2.3) 169 | rainbow (>= 2.2.2, < 4.0) 170 | regexp_parser (>= 1.8, < 3.0) 171 | rexml (>= 3.2.5, < 4.0) 172 | rubocop-ast (>= 1.28.1, < 2.0) 173 | ruby-progressbar (~> 1.7) 174 | unicode-display_width (>= 2.4.0, < 3.0) 175 | rubocop-ast (1.29.0) 176 | parser (>= 3.2.1.0) 177 | rubocop-capybara (2.18.0) 178 | rubocop (~> 1.41) 179 | rubocop-factory_bot (2.23.1) 180 | rubocop (~> 1.33) 181 | rubocop-govuk (4.12.0) 182 | rubocop (= 1.55.0) 183 | rubocop-ast (= 1.29.0) 184 | rubocop-rails (= 2.20.2) 185 | rubocop-rake (= 0.6.0) 186 | rubocop-rspec (= 2.22.0) 187 | rubocop-rails (2.20.2) 188 | activesupport (>= 4.2.0) 189 | rack (>= 1.1) 190 | rubocop (>= 1.33.0, < 2.0) 191 | rubocop-rake (0.6.0) 192 | rubocop (~> 1.0) 193 | rubocop-rspec (2.22.0) 194 | rubocop (~> 1.33) 195 | rubocop-capybara (~> 2.17) 196 | rubocop-factory_bot (~> 2.22) 197 | ruby-progressbar (1.13.0) 198 | sass (3.4.25) 199 | sassc (2.4.0) 200 | ffi (~> 1.9) 201 | servolux (0.13.0) 202 | sprockets (4.2.0) 203 | concurrent-ruby (~> 1.0) 204 | rack (>= 2.2.4, < 4) 205 | sqlite3 (1.6.3-arm64-darwin) 206 | sqlite3 (1.6.3-x86_64-linux) 207 | temple (0.10.2) 208 | thor (1.2.2) 209 | tilt (2.0.11) 210 | toml (0.3.0) 211 | parslet (>= 1.8.0, < 3.0.0) 212 | tzinfo (2.0.6) 213 | concurrent-ruby (~> 1.0) 214 | uglifier (3.2.0) 215 | execjs (>= 0.3.0, < 3) 216 | unicode-display_width (2.4.2) 217 | webrick (1.8.1) 218 | 219 | PLATFORMS 220 | arm64-darwin-21 221 | x86_64-linux 222 | 223 | DEPENDENCIES 224 | activesupport 225 | factory_bot 226 | json-schema 227 | middleman (>= 4.4.0, < 5.0) 228 | middleman-autoprefixer 229 | middleman-compass 230 | middleman-livereload 231 | middleman-search-gds 232 | middleman-sprockets 233 | pry 234 | rake 235 | redcarpet 236 | rspec 237 | rubocop-govuk 238 | sass 239 | sprockets 240 | sqlite3 241 | tzinfo-data 242 | wdm (~> 0.1.0) 243 | 244 | BUNDLED WITH 245 | 2.4.10 246 | -------------------------------------------------------------------------------- /content/guidance/apidomain/index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: api.gov.uk Domain Guidance 3 | weight: 850 4 | keywords: 'API Domains' 5 | identifier: DSA-005 6 | name: APIDomains 7 | organisation: Data Standards Authority 8 | author_email: api-programme@digital.cabinet-office.gov.uk 9 | status: published 10 | startDate: 2019-07-17 11 | dateAdded: 2021-05-24 12 | dateUpdated: 2021-01-19 13 | --- 14 | 15 | ## The most recent version of this document is published on [GOV.UK](https://www.gov.uk/guidance/get-an-api-domain-on-govuk) 16 | 17 | 18 | # Get an API domain on GOV.UK 19 | 20 | Contact the Government Digital Service (GDS) to get a domain for your API on GOV.UK. 21 | 22 | You can contact the Government Digital Service (GDS) to get a domain for your API on GOV.UK. 23 | 24 | You should only apply for an API domain after making sure your API meets the government’s [API technical and data standards](https://www.gov.uk/guidance/gds-api-technical-and-data-standards). If there are reasons for your API not meeting particular standards, you’ll need to discuss this with GDS as part of your application. 25 | 26 | ## Before you apply 27 | 28 | You must [appoint a domain name administrator](https://www.gov.uk/guidance/appoint-a-govuk-domain-name-administrator) to register and manage the domain. They will be responsible for: 29 | 30 | - choosing a Domain Name Service (DNS) provider - you can search for DNS providers on the [Digital Marketplace](https://www.gov.uk/digital-marketplace) and read our guidance on [choosing a good DNS provider](https://www.gov.uk/guidance/choose-a-good-registrar-or-dns-provider) 31 | - managing the DNS servers 32 | - managing Transport Layer Security (TLS) certificates for each API domain 33 | 34 | Your domain name administrator must have the authority to apply for a .api.gov.uk domain name on behalf of your organisation. Read the guidance on [getting written permission](https://www.gov.uk/guidance/get-permission-to-apply-for-a-govuk-domain-name) for more information. 35 | 36 | #### You must use a role-based email address in a public sector domain like ‘servicedesk@example.gov.uk’. Do not use an individual’s email address. 37 | 38 | GDS will need to be able to contact your domain name administrator, so you must keep this contact up to date. Make sure to regularly check that the email address is still active, and let GDS know if any contact details change. 39 | 40 | ## Apply for your domain 41 | 42 | ### 1\. Request the API domain from GDS 43 | 44 | Your domain name administrator will need to contact GDS at [api-domain-requests@digital.cabinet-office.gov.uk](mailto:api-domain-requests@digital.cabinet-office.gov.uk) with: 45 | 46 | - your chosen domain name 47 | - a role-based email address and phone number 48 | - [written permission from your organisation](https://www.gov.uk/guidance/get-permission-to-apply-for-a-govuk-domain-name) showing authorisation to apply for the domain name 49 | 50 | GDS will contact you to confirm that you’ll: 51 | 52 | - be running a single API off your domain 53 | - follow the versioning practices and other standards set out in the [API technical and data standards](https://www.gov.uk/guidance/gds-api-technical-and-data-standards) 54 | 55 | GDS will contact you to confirm the status of your application. 56 | 57 | ### 2\. Set up and activate your API domain 58 | 59 | Your DNS provider will have given you several DNS name server (NS) records. After GDS has approved your domain, send your NS records to [api-domain-requests@digital.cabinet-office.gov.uk](mailto:api-domain-requests@digital.cabinet-office.gov.uk) so GDS can delegate the domain. 60 | 61 | You must send at least 2 NS records for your domain, but you should send more if you can. Providing multiple NS records means that if one goes down, the DNS can look at the next one on the list. 62 | 63 | You must also add your API to the government’s [API Catalogue](https://www.api.gov.uk/) to help users find your API and show that your API meets government standards. 64 | 65 | ### 3\. Secure your API and domain 66 | 67 | You will need to keep your API and its domain name secure. You must: 68 | 69 | - use TLS v1.2 or above - do not use Secure Sockets Layer (SSL) or older versions of TLS 70 | - [use HTTPS](https://www.gov.uk/service-manual/technology/using-https), not HTTP - this will secure connections to your API, preserve user privacy, ensure data integrity and authenticate the server providing the API 71 | - avoid sending emails from .api.gov.uk subdomains - GDS has set top-level [SPF](https://www.gov.uk/government/publications/email-security-standards/sender-policy-framework-spf) and [DMARC](https://www.gov.uk/government/publications/email-security-standards/domain-based-message-authentication-reporting-and-conformance-dmarc) rules to discard any that do get sent 72 | - follow guidance on [keeping your domain protected from spoofing attacks](https://www.gov.uk/guidance/protect-domains-that-dont-send-email) 73 | - use a Certification Authority Authorisation (CAA) record on your .api.gov.uk domain - this stops attackers from getting another certificate authority to issue a certificate for the domain 74 | - comply with the [Minimum Cyber Security Standard](https://www.gov.uk/government/publications/the-minimum-cyber-security-standard) when managing your DNS entries 75 | 76 | If you’re hosting documentation or any other browser-based content, you must enable HTTP Strict Transport Security (HSTS) for your entire subdomain, including the includeSubDomains flag. 77 | 78 | You can find out more about [keeping your domain name secure](https://www.gov.uk/guidance/keeping-your-domain-name-secure). 79 | 80 | ### 4\. Manage your API and domain 81 | 82 | Keep GDS updated about any changes to the management or ownership of the domain by emailing [api-domain-requests@digital.cabinet-office.gov.uk](mailto:api-domain-requests@digital.cabinet-office.gov.uk). 83 | 84 | You must decommission your API and domain name when they are no longer needed, for example if the service they support shuts down. 85 | 86 | When decommissioning your API domain, make sure you: 87 | 88 | - give users of your APIs enough notice to update their service 89 | - contact GDS to decommission your API domain name 90 | - update your API documentation to say when you’re deprecating and retiring the API - you can also put a deprecation notice in your HTTP headers 91 | 92 | ## Hosting your API documentation 93 | 94 | It’s best practice to keep your [API documentation](https://www.gov.uk/guidance/how-to-document-apis) on the same domain as your API as they are part of the same product. 95 | 96 | GDS recommends publishing your documentation as a subdirectory of your domain, for example at name-of-api.api.gov.uk/docs. Using subdirectories means it’s easier to structure and version your documentation. Use consistent naming convention for your documentation across all your published APIs. 97 | 98 | Keep your documentation up to date with the correct endpoint URLs, and make sure the API Catalogue lists the correct URL to your documentation. 99 | 100 | ## Getting operations support 101 | 102 | If you have an issue you cannot resolve with your DNS supplier, you can email the GOV.UK team at [hostmaster@digital.cabinet-office.gov.uk](mailto:hostmaster@digital.cabinet-office.gov.uk). The team is available on weekdays between 9am and 5pm. 103 | 104 | If you have an emergency outside of these hours, you must contact your organisation’s single point of contact (SPOC) who will contact the support team for you. 105 | --------------------------------------------------------------------------------