govuk-one-login / data-vocab Goto Github PK

Teams maintain their own types that reflect the data model of the vocab schema.

This can lead to inconsistency between the canonical model (vocab) and the implementation, which can lead to issues.

The vocab project should offer types that teams can consume as a build-time asset. These types can be checked against the implementation by the TypeScript transpiler to enable inconsistencies to be detected earlier.

When we moved the classes into a subdirectory, a side effect was that the URI field, which is automatically generated by LinkML, now references (and links to) a URI that does not actually exist.

There are redirects for property names so I don't think this is a problem for those.

If the main reason for moving the classes into a subdirectory was so that the menu worked better, and we're now looking at manually specifying what's in the menu instead, we may just want to go back to having everything in the top level.

We need a working 404 page, currently this is a mess.

See https://govuk-one-login.github.io/data-vocab/v1/dsfsdf for an example.

There are a few things that are broken about the table of contents:

• the 'V1' link is the root of all TOC items and links to a completely obscure @context property that probably shouldn't even be in the metamodel. (It's only there until we can figure out how to generate JSON Schemas that allow JSON-LD @context properties some other way.)
• the 'GOV.UK Vocabulary' item at the top should probably link to the home page ie duplicate the 'Vocabulary' link in the top menu bar (but see #21).
• the home/credentials item in the TOC is a bit strange, though have a full contents somewhere is probably a good thing.

Link in menu bar doesn't work because in Github pages we're not at the root of the domain. Might as well fix this even tho it will hopefully soon be moot.

We aren't currently publishing any of the life events (death registered/registration updated).

We are currently only publishing the JSON Schemas for those events, but not any documentation for them.

This is because they aren't linked from the credentials.yaml file.

We can review this once the new layout is in place, but as life events are not an actual feature of the platform at this time, it's definitely not urgent to fix this (and arguably we should hold off doing so, at least until discussion with HMPO or CDDO might agree it's useful).

The AddressCredentialClass needs a JWT class to go with it, as this is what we should create a JSON Schema for and validate against. This would be consistent with our approach for other types of VC.

It also needs a description.

The IdentityAssertionCredentialClass does have a matching IdentityAssertionCredentialJWTClass however it also needs a description.

We currently have to write descriptions that contain HTML markup in a special format which is:

• the first line must not be wrapped in a block element like <p>
• subsequent paragraphs can exist and you can optionally wrap them in <p></p> tags or some other block level element if you need

For example, the following results in incorrect HTML markup:

description: |
      <p>
        A [VC](https://www.w3.org/TR/vc-data-model/) representing an identity check that contributes to identity confidence per UK government standards such as
        [Good Practice Guide (GPG) 45](https://www.gov.uk/government/publications/identity-proofing-and-verification-of-an-individual).
      </p>
      <p>
        In GOV.UK One Login this VC is always [issued in JWT format](IdentityCheckCredentialJWTClass).
      </p>

However the following markdown-only format works fine:

description: |
      A [VC](https://www.w3.org/TR/vc-data-model/) representing an identity check that contributes to identity confidence per UK government standards such as [Good Practice Guide (GPG) 45](https://www.gov.uk/government/publications/identity-proofing-and-verification-of-an-individual).

      In GOV.UK One Login this VC is always [issued in JWT format](../CoreIdentityJWTClass).

Note that in this case the | YAML block style indicator is essential, because otherwise newlines will be replaced by spaces.

Aside: in some cases, we've written this using HTML markup for the second paragraph, which means we can avoid using the special block style indicator, but arguably looks a bit strange:

description: A [VC](https://www.w3.org/TR/vc-data-model/) representing an identity check that contributes to identity confidence per UK government standards such as [Good Practice Guide (GPG) 45](https://www.gov.uk/government/publications/identity-proofing-and-verification-of-an-individual).

      <p>In GOV.UK One Login this VC is always [issued in JWT format](../CoreIdentityJWTClass).</p>

The root cause of this seems to be a bug in mkdocs (or its markdown processor) rather than anything unexpected happening in LinkML.

So this is probably not simple for us to fix, and this ticket mostly serves to document why we may adopt a particular style of multiline string that avoids HTML markup and always uses the | block style indicator.

What

Create a CODEOWNERS file containing a list of all individuals and groups who are able to approve Pull Requests to the data-vocab repository.

Why

Unless you know it's not easy to determine who the approvers are for the data-vocab repository. By creating a CODEOWNERS file all individuals and groups who are able to approve Pull Request will automatically be added to the Pull Request and therefore improving developer experience.

A tactical amendment has been made to allow for the generation of the site documentation for Classes, Slots, Enums and Types to be made into sub-directories to allow govuk-mkdocs navigation menu to be built into categories. The markdown generator within linkml needs to be amended so this isn't mandatory and could be triggered as a command line option.

It's easy to see a link to "name" on the home page click it, only to be plunged straight into a JSON Schema document.

This isn't user friendly - JSON schemas need relegating elsewhere, linked to from the relevant human-readable pages.

Part of the reason that schema generation is so slow, is that something in LinkML's gen-json-schema command is contacting the interwebs for unknown purposes.

I can't immediately think of a reason why this would be good, and maybe whatever URI resolution it's doing could be turned off.

Teams maintain their own data model classes that reflect the data model of the vocab schema.

This can lead to inconsistency between the canonical model (vocab) and the implementation, which can lead to issues.

The vocab project should offer data model classes that teams can consume as a build-time asset. These types can be checked against the implementation by the Java compiler to enable inconsistencies to be detected earlier.