Physical data model for death notification events

Context

The purpose of this RFC is to agree upon the physical data model required to integrate Life Events from the General Register Office (GRO) to GOV.UK One Login. In scope required for MVP is a death notification event which originates from GRO’s Registration Online (RON) system.

Decisions about encryption and signing of these event payloads are out of scope.

Change log

2023-08

First draft to share internally and with the Department for Work and Pensions (DWP).

2023-09

Changes for consistency and future-proofing:

follow standard event naming conventions by updating event names/URIs to match ‘registered’ and ‘registration updated’
change deathRegistrationID to deathRegistration
modify that identifier to be a Uniform Resource Name (URN) based on the original ID
no longer wrap recordUpdateTime and deathRegistrationTime in an object with a value property
include freeFormatBirthDate property

Death event structure

A death notification event is represented using a JSON object that conforms to the payload required of a Security Event Token (SET, see IETF RFC 8417).

We refer to this as the ‘event payload’.

The iss (issuer), iat (issued at) and jti (JWT identifier) claims as defined by IETF JSON Web Token (JWT) are required.

Other JWT claims such as txn may be present in the payload and should follow the requirements of this specification or the SET profile.

Two types of event are defined in this specification - a ‘death registered’ event and a ‘death registration updated’ event. The data model is broadly the same but the significance of certain properties depends on the type of event.

In both cases, the value of the events claim is a JSON object with a single member, where the name indicates the type of the event, and the value is an ‘event object’ as described in the rest of this document.

ⓘ Note

We intentionally define ‘event object’ as distinct from ‘event payload’ so that it’s easy to be precise when talking about the different levels of the JSON structure.

Classes and types

The specific classes and types described here will be found in future within the GOV.UK One Login vocabulary, and the relevant source is available on GitHub.

For now, JSON Schema files can be found at:

We mention JSON types such as arrays, strings and objects, but also more specific types which imply some particular validation.

We refer to a ‘list’ type where we mean a JSON array in which the order may be significant.

The ‘DateTime’ type refers to a complete ISO date and time as described by Schema.org. All such properties must include a time zone specifier and the time zone should be UTC (even when daylight savings time applies).

The ‘ISODate’ type contains a complete or partial ISO date, without a ‘time’ part and in which the ‘day’ and ‘month’ parts are optional.

Death registered event

The toe (time of event) claim must correspond to the deathRegistrationTime property.

The event object will have the name

https://vocab.account.gov.uk/v1/deathRegistered

⚠ Important

We may change the name of these event objects in future, for example we may decide to include a version number. For example, https://vocab.account.gov.uk/v1/deathRegistered/v3 could indicate ‘the third version of the death registered event in the first version of the event vocabulary’. If we decide to do this, the consequences will be discussed in a separate ADR.

The event object schema is described below in common event object properties.

Death registration updated event

The toe (time of event) claim must correspond to the recordUpdateTime property.

The event object will have the name

https://vocab.account.gov.uk/v1/deathRegistrationUpdated

The event object schema is described below in common event object properties. The following properties are also defined:

Property	Required	Description
`recordUpdateTime`	Required	A DateTime representing the date/time the record was amended.
`deathRegistrationUpdateReason`	Required	An identifier indicating the reason for the update.

Record update time

The recordUpdateTime property is a DateTime and should specify the timezone as UTC, which we expect to be represented via a Z suffix.

The string is therefore expected to be in a yyyy-MM-ddThh:mm:ssZ format.

Record update reason

The value for the deathRegistrationUpdateReason property must be one of the following identifiers:

formal_correction
quality_assurance
typographical
cancelled
cancellation_removed

Common event object properties

The following properties are common to both types of event. Some properties are marked as ‘expected’ which means we expect to see them in our initial implementation which uses the RON. However, data from other sources may vary.

Property	Required	Description
`subject`	Required	An object containing details of a person that has died for matching against existing records.
`deathRegistration`	Expected	A URI representing the entry in the register.
`deathDate`		An object containing details of a person’s death date.
`freeFormatDeathDate`		A string containing free format death date information, used where the death date could not be expressed as a partial or complete ISO date. This property is expected to be present if `deathDate` is not present, but could be used alongside `deathDate` in some cases.
`deathRegistrationTime`		A DateTime representing the moment when a person’s death was registered.

Subject properties

The value for subject is an object with the following properties:

Property	Required	Description
`name`	Required	A list of names.
`sex`	Expected	A list with a single value representing the person’s legal sex.
`birthDate`		A list representing facts about the person’s date of birth.
`freeFormatBirthDate`		A string containing free format birth date information, used where the birth date could not be expressed as a partial or complete ISO date. This property is expected to be present if `birthDate` is not present, but could be used alongside `birthDate` in some cases.
`address`	Expected	A list representing postal addresses at which the user resided.

Name list

The value for name is a list of name objects with the following properties:

Property	Required	Description
`nameParts`	Required	A list of name parts as described by the core identity atttributes section.
`description`		A human-readable description that may help with manual matching in cases where multiple name objects are in the list.

There must be at least one entry in the list of name objects. Where a person currently has (or has previously had) more than one name, there will be more than one entry in the list.

The first entry in the list must reflect the person’s full name when they died, as held on the official register.

Where a record shows that the person changed their name as a result of marriage or civil partnership, their given names must be duplicated, together with their family name at birth (often described as a ‘maiden name’), into another entry in the list.

Where a record shows that the person went by one or more other aliases, each alias (as a complete set of name parts, usually multiple given names and a family name) is a separate entry in the list. Each of these objects must include duplicates of any given names or family names that are common with other entries in the list so that it represents a full name.

Person sex (list)

The sex property captures a person’s legal sex.

A list of objects is used for consistency with other personal attributes that can change over time. Exactly one entry is allowed in a list for a life event originating from an official register.

ⓘ Note

Some sources in the UK use the term ‘gender’ to refer to ‘legal sex’.

The properties allowed in each object are as follows:

Property	Type	Required	Allowed values
`value`	string	Required	`Male`, `Female`, `Indeterminate`

Birth date (list)

The birthDate property is a list of objects because in some cases there may be a historical record of incorrect birth dates, that were previously considered to be correct. The value from the register (believed by the authoritative source to be correct) must appear first in the list and is expected to be the only entry.

The properties allowed in each object are as follows:

Property	Type	Required	Description	Allowed values
`value`	ISODate	Required	A possibly-partial ISO date.	`yyyy-MM-dd`, `yyyy-MM`, `yyyy`
`validFrom`	DateTime	Not expected.	The earliest point in time that the historical record considered the incorrect birthDate value to be correct.
`validUntil`	DateTime	Not expected.	The latest point in time that the historical record considered the incorrect birthDate value to be correct.
`description`	string	Not expected.

Address (list)

The address property captures any postal addresses associated with a person in the register. The most recent known address per the register must be first in the list.

The address structure section describes the objects appearing in the list.

Warning There is no guarantee that a complete address object will be populated.

Death date properties

The value for deathDate is an object with the following properties:

Property	Type	Required	Description	Allowed values
`value`	ISODate	Required	A possibly-partial ISO date.	`yyyy-MM-dd`, `yyyy-MM`, `yyyy`
`description`	string		A qualifier relating to the date, used when a partial date is provided. For example, ‘On or about’, ‘Deceased found on’, ‘Dead body found on’.

If a date of death is not known or cannot be represented as a complete or partial ISO date, freeFormatDeathDate may be used instead.

Death registration URI

deathRegistration must contain a URI for the relevant entry in the register of deaths, and is expected to be a federated content URN based on an originator’s identifier.

Death registration time

The deathRegistrationTime property is a DateTime and is expected for registration events but not for update events.

It should specify the timezone as UTC, which we expect to be represented via a Z suffix.

The string is therefore expected to be in a yyyy-MM-ddThh:mm:ssZ format.

Examples of output from the Life Events Platform

Examples of output from the Life Events Platform are currently available in GitHub.

Future work

In future we may capture a level of trust as defined by the UK Trust Framework.

This could apply to the entire event, but might be overridden for specific attributes.

Change control

Adding a property to an object should not be considered as a breaking change to the schema.

ⓘ Note

We’ll add further notes about how this specification may change over time in a future update.

Address Structure

Date: 2023-02-07 Version: 1.0.3

The definition of the Address schema for data for Identity Proofing and Verification (IPV).

1. Background

Data design consistent with widely acceptable practices leading to interoperability and adoption across government. The intention is to define the shape and interpretation of the Canonical Address Model.

The aim is to model the Address Structure to that of the Address collector on to the Credential Issuer through to the Relying Party.

Standards referenced:

2. Attributes/Fields Included

Canonical Address Field	type	maxlength	Mandatory	Definition
validFrom	Date		N	See metadata
validUntil	Date		N	See metadata
uprn	integer	12	N	Unique Property Reference Number (UK addresses only)
organisationName	string	60	N
departmentName	string	60	N
subBuildingName	string	30	N
buildingNumber	string	30	N
buildingName	string	60	N
dependentStreetName	string	60	N
streetName	string	60	N
doubleDependentAddressLocality	string	60	N
dependentAddressLocality	string	60	N
addressLocality	string	30	N
postalCode	string	9	N
addressCountry	string	2	N	Two-letter ISO 3166-1 alpha-2 country code

All fields, unless defined in the table above, have a definition given by the OS Places API, per the mapping below.

Addresses are UK (ISO 3166-1 code GB) addresses by default, unless specified in the addressCountry field.

Metadata

validFrom and validUntil are ISO 8601 strings representing the date that the user moved into, and away from, a particular address, if known.

If a user tells us that an address is their current address, then validUntil must be omitted.

If the month is unknown, then we will represent that as 01; similarly an unknown day-of-month will be represented as 01.

Ommitting year or month is permitted under ISO 8601 but we limit ourselves to complete dates as required by RFC 3339 because this is easily validated using JSON Schema and maximally interoperable.

3. JSON Schema

Will link to JSON Schema when available

4. Examples of JSON

Building name and UPRN

{
  "uprn": 10002345923,
  "buildingName": "SAWLEY MARINA",
  "streetName": "INGWORTH ROAD",
  "dependentAddressLocality": "LONG EATON",
  "addressLocality": "NOTTINGHAM",
  "postalCode": "BH12 1JY",
  "addressCountry": "GB"
}

Building number and name

{
  "uprn": 10022812929,
  "organisationName": "FINCH GROUP",
  "subBuildingName": "UNIT 2B",
  "buildingNumber": "16",
  "buildingName": "COY POND BUSINESS PARK",
  "dependentStreetName": "KINGS PARK",
  "streetName": "BIG STREET",
  "doubleDependentAddressLocality": "SOME DISTRICT",
  "dependentAddressLocality": "LONG EATON",
  "addressLocality": "GREAT MISSENDEN",
  "postalCode": "HP16 0AL",
  "addressCountry": "GB"
}

Building name without UPRN

{
  "buildingName": "R103",
  "dependentStreetName": "KINGS PARK",
  "streetName": "CREEK ROAD",
  "doubleDependentAddressLocality": "",
  "addressLocality": "CANVEY ISLAND",
  "postalCode": "SS8 8QA",
  "addressCountry": "GB"
}

Sub building name with building name

{
  "subBuildingName": "FLAT 11",
  "buildingName": "BLASHFORD",
  "streetName": "ADELAIDE ROAD",
  "addressLocality": "LONDON",
  "postalCode": "NW3 3RX",
  "addressCountry": "GB"
}

Sub building name with building number

{
  "subBuildingName": "FLAT 6",
  "buildingNumber": "45",
  "streetName": "NAVARINO ROAD",
  "addressLocality": "LONDON",
  "postalCode": "E8 1AG",
  "addressCountry": "GB"
}

Building number with dependent address locality

{
  "uprn": 151001847,
  "buildingNumber": "13",
  "streetName": "CHURCH CRESCENT",
  "dependentAddressLocality": "NEW PITSLIGO",
  "addressLocality": "FRASERBURGH",
  "postalCode": "AB43 6LP",
  "addressCountry": "GB"
}

Building number

{
  "uprn": 100110116546,
  "buildingNumber": "3",
  "streetName": "HILLEL WALK",
  "addressLocality": "MIDDLESBROUGH",
  "postalCode": "TS5 8DG",
  "addressCountry": "GB"
}

5. Mapping of fields to data sources and reference standards

Canonical	Experian CrossCore	Schema.Org	OS Places / AddressBase	Comment
uprn	addressIdentifier		UPRN	Unique Property Reference Number
organisationName	subBuilding		ORGANISATION_NAME
departmentName	subBuilding		DEPARTMENT_NAME
subBuildingName	subBuilding		SUB_BUILDING_NAME	May be used in combination with buildingName or buildingNumber
buildingNumber	buildingNumber		BUILDING_NUMBER
buildingName	buildingName		BUILDING_NAME
dependentStreetName	street		DEPENDENT_THOROUGHFARE_NAME
streetName	street		THOROUGHFARE_NAME
doubleDependentAddressLocality			DOUBLE_DEPENDENT_LOCALITY
dependentAddressLocality	locality		DEPENDENT_LOCALITY
addressLocality	postTown	addressLocality	POST_TOWN	Naming convention from schema.org
postalCode	postal	postalCode	POST_CODE	Naming convention from schema.org
addressCountry	countryCode	addressCountry		2-letter ISO code per schema.org, not a COUNTRY_CODE per AddressBase which are single-character codes refering to constituent countries of the UK, and not a 3-letter ISO code as used by Experian.

Care must be taken when mapping to or from address formats that are line-based (ie “address 1”, “address 2”, etc). A field such as addressLocality maps to a different line of the address, depending on the presence of other fields (in this case dependentAddressLocality and doubleDependentAddressLocality).

Core identity attributes

History

March 2022 - approved for implementation January 2023 - mappings from other formats clarified

1. Background

We have decided to return verified identity data to relying parties (RPs) using a JWT-encoded Verifiable Credential (VC), signed by the single point of trust.

The Verifiable Credential will contain only data that has been proven to the GPG 45 level of confidence indicated. Other attributes (those which we can’t prove are part of the user’s verified identity) will be returned separately.

2. Attributes included

This RFC describes how the core identity attributes (name and date of birth) will be represented as they are provided by the Single Point of Trust.

We also need to be able to represent the level of confidence achieved.

Our identity assurance process may also give us confidence in non-core attributes such as address and passport number.

These may be returned separately to the RP, in which case they will need to be scored according to whether we were able to link them to the proven core identity attributes. This is out of scope for this RFC.

The Single Point of Trust needs to be told which attributes are to be included in the Verifiable Credential: this is out of scope for this RFC.

3. General requirements

Desirable properties of our representation of identities to relying parties are:

consistency with the way we represent identity data internally (eg between credential issuers);
the ability to represent a complete view of the user’s identity attributes, including relevant metadata; and
allowing future change in predictable and backward-compatible ways;
to support matching of data we collect (and prove) against government systems that may contain inconsistent data.

Only verified attributes (claims) may appear in the Core Identity verifiable credential; unverified claims must not be present.

Most claims appear as properties of credentialSubject (which is an object within the vc JWT claim defined by the VC JWT encoding). There are some exceptions where JWT claims are used.

All claims within credentialSubject will be provided as arrays, to support future use cases where multiple identity attributes have been linked to a single identity.

Each attribute is contained within a JSON object: we use the validFrom and validUntil properties as metadata, add other metadata properties as required, and represent the attribute itself using the value property.

All identifiers (such as the subject identifier sub) must be a URI.

4. Names

We want:

to be able to represent multiple distinct names, if that’s the most convenient way for a user (or a credential issuer) to represent a change of name;
for each name to be able to have metadata attached to it (for example, perhaps in future, a language code);
for each name to be composed of multiple parts, each one either being a given name or a family name;
for each part to be able to have separate metadata (for example, validity periods, so that we can conveniently represent the situation where just one part of a user’s name changes);
to be able to attach metadata to either the entire name (i.e. all of the parts) as well as to individual parts.

The credentialSubject will have a name property. Each name contains an array of objects.

The array is ordered: a current name (one with no validUntil property) must be first.

Each object represents a name that the user is, or has been, known by. It has the following properties:

validFrom - a schema.org Date or DateTime
validUntil - a schema.org Date or DateTime
nameParts - an array of objects as described below

The nameParts array is ordered, reflecting the either the user’s preferred order, or the order of names on a particular identity document.

ⓘ Note

The order of name parts may be ignored when comparing names, for example in a matching process. Comparison and matching rules are outside the scope of this specification.

Each object in nameParts represents a part of a name, and describes how an individual uses (or acquired) that part of their name. It has the following properties:

value - a String (schema.org Text) containing some smallest unit of a user’s name
validFrom - a schema.org Date or DateTime
validUntil - a schema.org Date or DateTime
type - either GivenName or FamilyName

ⓘ Note

It’s possible to capture a change of name either using multiple name objects (with varying validity periods), or with a single name object that contains nameParts of varying validity periods. Some representations will be therefore be equivalent to each other: we anticipate that in some cases this is obvious, but no definition of name equivalence is given by this specification. No parts of the system support anything other than a “current name”, at the time of writing.

Mapping to OpenID Connect

OpenID Connect provides various name-related claims, and the following mapping is suggested to help consumers understand the format this specification proposes.

All OpenID Connect fields map only to the user’s current name (the first entry in the name array); name parts are split or joined using a space character.

name: derived by joining all of the name parts, in order (we have not yet defined a representation for titles and suffixes)
given_name: derived by joining all of the name parts of type GivenName, in order
family_name: derived by joining all of the name parts of type FamilyName, in order
middle_name: no mapping from this specification’s format (to avoid unwanted duplication)

To go from the OpenID Connect claims to this specification’s format, a single name object could be constructed as follows:

nameParts starts as an empty array
given_name is split, and each part is assigned type GivenName, and appended to the array
middle_name is split, and each part is assigned type GivenName, and appended to the array
family_name is copied as-is to a single FamilyName name part (regardless of any spaces present) and appended to the array

ⓘ Note

family_name is transposed to a single name part. This is based on the UK-centric assumption that most end users for One Login have a single family name, which may contain a space (e.g. “Duncan Smith”). Considering names in a global context across multiple cultures, this expectation does not hold. Consumers of this format should understand that multiple FamilyName parts may be used by One Login in future.

Mapping from other formats

Some name representations don’t have a single obvious mapping, either to this specification’s format, or to OpenID Connect.

In these circumstances, a transformation must be chosen that is correct for as many users as possible, and it is reasonable to make improvements to that transformation as user needs are better understood, and as the capabilities of attribute providers (credential issuers) increase.

ⓘ Note

For example, a UK passport machine readable zone (MRZ) cannot distinguish between

a hyphenated surname (eg “Brown-green”)

a compound surname without a hyphen (eg “Duncan Smith”), and

two family names as found in Portuguese culture (eg “Sousa Carvalho”).

All these cases appear as a single string with the parts of the name separated by a space character.

We have to choose between representing these as a single FamilyName part (containing spaces), or multiple FamilyName parts. Unless we can confirm a preference from the user, we may choose to use a single name part as we are likely to have more users with hyphenated or compound surnames in comparison to Portuguese users whose names should be kept separate.

5. Date of birth

We want:

to allow multiple values for dates of birth to be recorded;
to be able to include metadata in future if necessary.

We always expect to include year, month and day whenever a date of birth is supplied.

The credentialSubject will have a birthDate property. Each birthDate contains an array of objects.

ⓘ Note

While users only have one date of birth, previously-believed values may still be helpful for matching, so representation of multiple dates of birth is rare but could one day be required. At MVP, the Single Point of Trust will only output a single date of birth, but this representation might be useful in future.

The array is ordered: the date of birth that the issuer believes to be correct (the one with no validUntil property) must be first.

ⓘ Note

This ensures compatibility with existing implementations should we ever capture multiple dates of birth.

Each object represents a date of birth that some system believed was true for the user. It has the following properties:

value - a schema.org Date that is the user’s date of birth
validFrom - a schema.org Date or DateTime`
validUntil - a schema.org Date or DateTime`

6. Level of confidence

The level of confidence achieved is strictly speaking neither a property of the credential subject (the user), nor of the account - it is a property of the credential itself and good for only as long as the VC we are issuing is valid.

For greater consistency with Vectors of Trust, we represent this in the JWT directly (see ADR 12).

This is also consistent with the approach taken in the Verifiable Credentials Data Model which says that if in the JWT “specific claim names and header parameters are present, their respective counterpart in the standard verifiable credential and verifiable presentation MAY be omitted to avoid duplication”.

The JWT claims are as follows:

vot - P1 for low confidence, P2 for medium confidence, etc.
vtm - https://oidc.account.gov.uk/trustmark or some variation of that, depending on the environment

7. Other JWT claims

We also require the Core Identity JWT to include the following other JWT claims defined by RFC 7519:

sub (must be a URI)
nbf
exp
iat
iss (must be a URI)

ⓘ Note

A jti claim (or corresponding VC id property) is not included, because we do not want to create identifiers that could be correlated. If we do need credential identifiers, a new one would be generated each time the user presents their identity to a relying party.

8. Other JSON objects / properties

The vc object may have an @context property (to support future processing as JSON-LD) and this should be ignored by verifiers (see schemas, below).

The vc object must have a type property, which is an array containing the following strings: "VerifiableCredential", "VerifiableIdentityCredential".

9. Example JWT

In this example, JWT headers are not shown, but alg must be set per JWS. Other headers (for example typ) should, if present, be constrained according to the Verifiable Credential data model.


{
  "sub": "urn:fdc:gov.uk:2022:JG0RJI1pYbnanbvPs-j4j5-a-PFcmhry9Qu9NCEp5d4",
  "nbf": 1670336441,
  "iss": "https://identity.account.gov.uk/",
  "vot": "P2",
  "exp": 1670338241,
  "iat": 1670336441,
  "vtm": "https://oidc.account.gov.uk/trustmark",
  "vc": {
    "type": [
      "VerifiableCredential",
      "VerifiableIdentityCredential"
    ],
    "credentialSubject": {
      "name": [
        {
          "nameParts": [
            {
              "value": "Jane",
              "type": "GivenName"
            },
            {
              "value": "Wright",
              "type": "FamilyName"
            }
          ],
          "validFrom": "2019-04-01"
        },
        {
          "nameParts": [
            {
              "value": "Jane",
              "type": "GivenName"
            },
            {
              "value": "Wright",
              "type": "FamilyName"
            }
          ],
          "validUntil": "2019-04-01"
        }
      ],
      "birthDate": [
        {
          "value": "1989-07-06"
        }
      ]
    }
  }
}

10. Schemas

Relying parties should be able to process the data we generate using either JSON-LD-aware tooling, or using standard JSON tools and libraries. Therefore, we will be conservative in the JSON that we generate, and we’ll publish and iterate a JSON Schema that constrains the JSON documents that the system can produce.

A draft JSON-Schema is under development.

Relying parties that do not use JSON-LD-aware tooling should be aware of the following requirement in the Verifiable Credentials Data Model:

All libraries or processors MUST ensure that the order of the values in the @context property is what is expected for the specific application.

However, as the context URI for our schema has not yet been settled, this requirement SHOULD in practice be ommitted for now as an intentional (but temporary) violation.

Relying parties MUST NOT dynamically load any JSON-LD context across the public Internet. RPs that decide to use JSON-LD-aware tooling MUST cache static copies of the applicable contexts, and have a process in place for updating them securely.