> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vumasign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The core vocabulary

> The keys Vumasign publishes for the data every South African form asks for, and your organisation's own keys beside them.

export const personGenderOptions = "male, female";

export const coreSubjectKeys = "spouse, dependant_<n>, beneficiary_<n>, witness_<n>";

export const coreNamespaces = "person, employer, employment, residential_address, postal_address, bank";

export const vocabularyLabelsMax = "5";

export const vocabularyScope = "templates:read";

export const coreKeyCount = "50";

export const coreVocabularyVersion = "1.0.0";

A template's keys come in three kinds. **Core** keys are a vocabulary Vumasign publishes: people,
South African ID and passport, contact details, addresses, employment, employers and banking.
Map your data to them once and every template named with them is addressed the same way.
**Organisation** keys are every other key your own templates use, in the naming grammar
(`namespace.attribute`, see [Naming fields](/concepts/naming-fields)). **Legacy** keys are any
other spelling a template still carries from before; they work as addresses and are names to
replace.

## Reading it

[`GET /api/v1/vocabulary`](/api-reference/get-vocabulary) answers with both lists, for a key
holding <code>{vocabularyScope}</code>, test or live. It carries an `ETag`, and `If-None-Match`
answers with no body while nothing has changed.

* `core` is version {coreVocabularyVersion}, {coreKeyCount} keys, with the subject keys the core
  standardises: <code>{coreSubjectKeys}</code>, where n counts from one.
* `organisation` lists the keys your organisation's live templates use and the core does not:
  each key's type (a field type, or `choice` for a question), how many templates use it, up to
  {vocabularyLabelsMax} labels printed beside the boxes that carry it, and for a question the
  option values in use. It is derived from your templates whenever you read it, archived templates
  left out, and it never lists another organisation's keys.

## How the core changes

The core uses semantic versioning. A minor version adds keys, options or synonyms. A key or an
option value is never renamed or removed; at most it is deprecated, with the key that replaces it.
A template named with a core key never needs renaming because the core moved.

## Using a core key

* `person.*`, the two address namespaces and `employment.*` describe a person. With `subject`
  null they are the form's principal person, the one the signer answers for; with `subject` set to
  `spouse`, the spouse's. `employer.*` and `bank.*` describe the organisation and take no subject.
* A key in a core namespace (<code>{coreNamespaces}</code>) must be a core key: a key such as
  `person.sa_idnumber` is refused with the core key it most likely means.
* A `choice` key is a question (or a dropdown), and its options are fixed: a question named with
  `person.gender` offers <code>{personGenderOptions}</code>, and its boxes take those option values.
* A core key is refused on a field of a kind it does not describe: a date key on a tickbox, or a
  choice key on a text box.

## The keys

### `person.*`

Subject-capable: with `subject` null it is the form’s principal person; with a subject, that person’s.

| Key | Label | Type | Options | What belongs here |
| - | - | - | - | - |
| `person.title` | Title | `choice` | `mr`, `mrs`, `ms`, `miss`, `dr`, `prof` | The form of address printed before a name. Not a job title (that is `employment.job_title`). |
| `person.first_names` | First names | `text` | | Every given name, as on the identity document. Not initials, and not a preferred or known-as name. |
| `person.last_name` | Surname | `text` | | The family name, as on the identity document. Not a maiden name unless the form asks for the current surname. |
| `person.initials` | Initials | `text` | | The initials of the first names, for example `J.M.` Not a signature initial. |
| `person.sa_id_number` | South African ID number | `sa_id` | | The 13-digit South African identity number. Not a passport number. |
| `person.passport_number` | Passport number | `text` | | The number of a passport, for a person without a South African ID number. Not the ID number. |
| `person.passport_country` | Passport country | `text` | | The country that issued the passport. Not the country of residence. |
| `person.date_of_birth` | Date of birth | `date` | | The day the person was born. Not an age. |
| `person.gender` | Gender | `choice` | `male`, `female` | The gender the form asks for, as the two options printed on most South African forms. |
| `person.marital_status` | Marital status | `choice` | `single`, `married`, `divorced`, `widowed`, `life_partner` | Whether the person is married, and how. Not the spouse’s details. |
| `person.relationship_to_principal` | Relationship to the principal | `choice` | `spouse`, `child`, `parent`, `sibling`, `other` | How a subject (a spouse, dependant or beneficiary) is related to the form’s principal person. |
| `person.email` | Email address | `email` | | The person’s own email address. Not an employer’s contact address (that is `employer.contact_email`). |
| `person.mobile_number` | Mobile number | `phone` | | The person’s cellphone number. |
| `person.home_phone` | Home telephone | `phone` | | A landline at home. Not a cellphone. |
| `person.work_phone` | Work telephone | `phone` | | A telephone number at work. Not the employer’s switchboard on an employer section. |
| `person.income_tax_number` | Income tax number | `text` | | The person’s SARS income tax reference number. Not a company’s PAYE reference. |
| `person.home_language` | Home language | `text` | | The language the person speaks at home. |
| `person.occupation` | Occupation | `text` | | What the person does for a living, in general terms. Not a job title at one employer. |

### `residential_address.*`

Subject-capable: with `subject` null it is the form’s principal person; with a subject, that person’s.

| Key | Label | Type | Options | What belongs here |
| - | - | - | - | - |
| `residential_address.line_1` | Residential address line 1 | `text` | | The first line of the residential address: a street number and name, a unit, or a box number. |
| `residential_address.line_2` | Residential address line 2 | `text` | | The second line of the residential address, when the form prints one. |
| `residential_address.suburb` | Suburb | `text` | | The suburb of the residential address. Not the city. |
| `residential_address.city` | City or town | `text` | | The city or town of the residential address. |
| `residential_address.postal_code` | Postal code | `text` | | The four-digit postal code of the residential address. |
| `residential_address.province` | Province | `choice` | `eastern_cape`, `free_state`, `gauteng`, `kwazulu_natal`, `limpopo`, `mpumalanga`, `north_west`, `northern_cape`, `western_cape` | The South African province of the residential address. |
| `residential_address.country` | Country | `text` | | The country of the residential address. |

### `postal_address.*`

Subject-capable: with `subject` null it is the form’s principal person; with a subject, that person’s.

| Key | Label | Type | Options | What belongs here |
| - | - | - | - | - |
| `postal_address.line_1` | Postal address line 1 | `text` | | The first line of the postal address: a street number and name, a unit, or a box number. |
| `postal_address.line_2` | Postal address line 2 | `text` | | The second line of the postal address, when the form prints one. |
| `postal_address.suburb` | Suburb | `text` | | The suburb of the postal address. Not the city. |
| `postal_address.city` | City or town | `text` | | The city or town of the postal address. |
| `postal_address.postal_code` | Postal code | `text` | | The four-digit postal code of the postal address. |
| `postal_address.province` | Province | `choice` | `eastern_cape`, `free_state`, `gauteng`, `kwazulu_natal`, `limpopo`, `mpumalanga`, `north_west`, `northern_cape`, `western_cape` | The South African province of the postal address. |
| `postal_address.country` | Country | `text` | | The country of the postal address. |

### `employment.*`

Subject-capable: with `subject` null it is the form’s principal person; with a subject, that person’s.

| Key | Label | Type | Options | What belongs here |
| - | - | - | - | - |
| `employment.employee_number` | Employee number | `text` | | The number the employer knows the person by. Not a payroll or tax reference. |
| `employment.job_title` | Job title | `text` | | The person’s position at their employer. Not their form of address (that is `person.title`). |
| `employment.start_date` | Employment start date | `date` | | The day the person started with this employer. |
| `employment.monthly_salary` | Monthly salary | `number` | | Gross pay a month, in rand. Not an annual figure. |
| `employment.annual_salary` | Annual salary | `number` | | Gross pay a year, in rand. Not a monthly figure. |

### `employer.*`

Not subject-capable: it describes the organisation, and a subject is refused.

| Key | Label | Type | Options | What belongs here |
| - | - | - | - | - |
| `employer.name` | Employer name | `text` | | The employer’s registered name. Not a trading name. |
| `employer.trading_name` | Trading name | `text` | | The name the employer trades under, when it differs from the registered name. |
| `employer.registration_number` | Company registration number | `text` | | The employer’s CIPC registration number. Not a PAYE or VAT reference. |
| `employer.paye_reference_number` | PAYE reference number | `text` | | The employer’s SARS PAYE reference number. Not a person’s income tax number. |
| `employer.contact_name` | Employer contact person | `text` | | The person at the employer a form names as its contact, for example someone in HR. |
| `employer.contact_email` | Employer contact email | `email` | | The employer contact’s email address. Not the employee’s. |
| `employer.contact_phone` | Employer contact telephone | `phone` | | The employer contact’s telephone number. Not the employee’s. |

### `bank.*`

Not subject-capable: it describes the organisation, and a subject is refused.

| Key | Label | Type | Options | What belongs here |
| - | - | - | - | - |
| `bank.account_holder` | Account holder | `text` | | The name the bank account is held in. |
| `bank.bank_name` | Bank | `text` | | The name of the bank. |
| `bank.branch_code` | Branch code | `text` | | The bank’s branch or universal branch code. |
| `bank.account_number` | Account number | `text` | | The bank account number. Not a card number. |
| `bank.account_type` | Account type | `choice` | `cheque`, `savings`, `transmission` | The kind of bank account. |
| `bank.debit_order_day` | Debit order day | `number` | | The day of the month a debit order runs, from 1 to 31. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.