Your workplace needs more WOW. Get ready for MHR's World of Work 2026
Image
Metadata
What is Metadata?
Metadata is data that describes other data, but does not form part of the data it is describing. A simple example of this is the information that is displayed when you right-click on a file and select 'properties'. The properties view displays information such as the type of file, which application the file opens with, the size of the file and when it was created.
How is metadata utilised with People First APIs?
Let's take a look at one of the example requests which was the first to be carried out in the 'Quick Start Guide'. You don't have to have read the quick start guide in order to understand this explanation.
Displayed below is the 'data' element from the 'Create Person Resource Template' response object. The response object is made up of two child objects, 'data' and 'metadata', which can have further nested child objects or fields within them. The 'person' object within the 'data' object is what forms the actual resource template.
This resource template is a blank version of the resource which is ready to be populated with a person's data / info. These fields are pre-labelled to guide the user / client on what should go in the field e.g. 'firstName', 'lastName' and 'title'. Most of the fields are pretty intuitively labelled in order to guide the user as to what kind of information should be entered into the field, however what about the field labelled 'legislation'? It's not immediately obvious exactly what should be entered into this field to satisfy the criteria. This is where metadata comes in.
{
"data": {
"person": {
"_links": {},
"firstName": "",
"lastName": "",
"title": "",
"otherNames": "",
"knownAs": "",
"pronouns": "",
"previousLastName": "",
"startDate": "",
"personalReference": "",
"socialSecurityNumbers": [
{
"legislation": "",
"socialSecurityNumber": "",
"_status": "new"
}
]
}
}
}
Displayed below is the 'metdata' part of the response object for 'Create Person Resource Template'. If we scroll down the metadata object about half way we can see the metadata nested object which relates to the 'legislation' field highlighted in red. This object provides information on which values can be entered into the legislation field. The first thing to note is that the field 'mandatory' has a value of 'true' meaning that this field cannot be left empty, whereas other fields where the value is 'false' can be left empty. Looking through the values array it is now easy to realise that 'legislation' is in reference to a country's legislation. For the purposes of this example we will be choosing the legislation of the 'United Kingdom', so we populate the legislation field with the 'id' within the 'United Kingdom' object ('47c23873-057b-4b22-b2d9-a1a31ccec3fb') and that field is then complete with valid information.
{
"meta": {
"links": {
"self": {
"href": "/hrm/people/resourcetemplate?annotate=t"
}
},
"person.personalReference": {
"hidden": "true",
"disabled": "true"
},
"person.startDate": {
"mandatory": "true"
},
"person.lastName": {
"mandatory": "true"
},
"person.firstName": {
"mandatory": "true"
},
"person.title": {
"mandatory": "true",
"values": [
{
"value": "Dr",
"id": "cf14f246-385f-4fb3-b90f-a1254ef5520e",
"code": "TITLE0006"
},
{
"value": "Miss",
"id": "5175ae20-63d7-48e3-824d-72d35d1e960c",
"code": "TITLE0004"
},
{
"value": "Mr",
"id": "9e188b9d-737b-4c9d-92bb-199d8a6fba5c",
"code": "TITLE0001"
},
{
"value": "Mrs",
"id": "930fe73a-c2d5-446c-9819-75823d4fd7fe",
"code": "TITLE0005"
},
{
"value": "Ms",
"id": "77165d3e-aebb-41fd-891e-5fc7ce169ace",
"code": "TITLE0003"
},
{
"value": "Professor",
"id": "1a564fa5-4de3-4a6a-bca3-2869c20414eb",
"code": "TITLE0002"
}
]
},
"person.socialSecurityNumbers": {
"mandatory": "true",
"links": {
"template": {
"href": "/hrm/people/resourcetemplate?organisationId=00000000-0000-0000-0000-000000000000"
}
}
},
"person.socialSecurityNumbers.legislation": {
"mandatory": "true",
"values": [
{
"value": "Isle of Man",
"id": "6895aa29-fe9d-4ee8-a349-91f19554677f",
"code": "IOM"
},
{
"value": "Malaysia",
"id": "96bf4445-11fe-4ab2-910e-a34101d3a00a",
"code": "MYS"
},
{
"value": "Other",
"id": "909e4ce5-9acd-44b7-9d21-a9f671f45f62",
"code": "OTHER"
},
{
"value": "Republic of Ireland",
"id": "9f1a256d-6a8e-4d59-b7a6-e7b4e9dae64e",
"code": "ROI"
},
{
"value": "Singapore",
"id": "630de51f-f7c8-407c-8439-201ee9bbb6ee",
"code": "SG"
},
{
"value": "States of Guernsey",
"id": "b98ef498-d2e7-4d50-871a-7313253ef007",
"code": "SOG"
},
{
"value": "States of Jersey",
"id": "c23f94c9-232e-4875-a9e4-84d9d4a1ab57",
"code": "SOJ"
},
{
"value": "United Kingdom",
"id": "47c23873-057b-4b22-b2d9-a1a31ccec3fb",
"code": "UK"
},
{
"value": "United States of America",
"id": "b1291fff-e37c-4323-a395-812cfd159395",
"code": "US"
}
]
},
"person.socialSecurityNumbers.socialSecurityNumber": {
"mandatory": "true"
},
"person.pronouns": {
"values": [
{
"value": "He/Him",
"id": "eefac58f-030e-419f-9bf0-4f454e79838d",
"code": "GP1"
},
{
"value": "She/Her",
"id": "6b43db2e-0de7-4238-870e-e0094afa1e49",
"code": "GP2"
},
{
"value": "They/Them",
"id": "cc0edab2-535c-4537-8fc9-68f95f077547",
"code": "GP3"
}
]
}
}
}
This section of the API documentation relating to 'metadata' has provided a basic explanation as to what metadata is and how we can use it in relation to the People First APIs. Metadata can provide information about a particular data field, what info can be entered into that data field, and also if a data field is mandatory or not. The utility of metadata reaches even further than this section, and should be explored further in order to get the most from People First APIs.
