{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/open-education-api/main/json-schema/open-education-api-person-properties-schema.json",
  "title": "PersonProperties",
  "description": "A person that has a relationship with this institution",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/open-education-api-openapi.yml#/components/schemas/PersonProperties",
  "type": "object",
  "anyOf": [
    {
      "required": [
        "surname",
        "primaryCode",
        "activeEnrolment"
      ]
    },
    {
      "title": "With required given name",
      "required": [
        "givenName",
        "primaryCode",
        "activeEnrolment"
      ]
    },
    {
      "title": "With required preferred name",
      "required": [
        "preferredName",
        "primaryCode",
        "activeEnrolment"
      ]
    }
  ],
  "properties": {
    "primaryCode": {
      "description": "The primary human readable identifier for the person. This is often the source identifier as defined by the institution.",
      "$ref": "#/$defs/IdentifierEntry"
    },
    "givenName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The first name of this person",
      "maxLength": 256
    },
    "alternateName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The Name a person chooses to use. this is part of a Self Sovereign name e.g. in the eduId process comparable to schema.org alternateName",
      "maxLength": 256
    },
    "preferredName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The name how the person would like to be called. Usually first name of this person. In line with ISO/IEC 24760 – Identity Management Vocabulary",
      "maxLength": 256
    },
    "surnamePrefix": {
      "type": [
        "string",
        "null"
      ],
      "description": "The prefix of the family name of this person"
    },
    "surname": {
      "type": "string",
      "description": "The family name of this person",
      "maxLength": 256
    },
    "displayName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The name of this person which will be displayed",
      "maxLength": 256
    },
    "initials": {
      "type": [
        "string",
        "null"
      ],
      "description": "The initials of this person"
    },
    "idCheckName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The name of the person as printed on official identification documents\n(driving licence, passport or identity card). This MUST be formatted as\n\"surname prefix surname, given names\" (separating surnamePrefix and surname\nwith a single space, and surname and given names with a comma and space).\n\nIf the surname or given names are not available or are secret, the values\n\"secret\" and \"not_available\" are recommended. The surname prefix may be\nomitted. E.g. \"van der Graaf, Jacobus Adrianus\". \n\nOptionally, the value of\nthe student number can be added to this field by appending it at the end,\nseparated by a comma. E.g. \"van der Graaf, Jacobus Adrianus, s12345678\"\n"
    },
    "activeEnrolment": {
      "type": "boolean",
      "description": "Whether this person has an active enrolment."
    },
    "dateOfBirth": {
      "type": [
        "string",
        "null"
      ],
      "description": "The date of birth of this person, using the `full-date` format as defined in \nRFC 3339 (section 5.6).\n",
      "format": "date"
    },
    "cityOfBirth": {
      "type": [
        "string",
        "null"
      ],
      "description": "The city of birth of this person"
    },
    "countryOfBirth": {
      "oneOf": [
        {
          "$ref": "#/$defs/Country"
        },
        {
          "type": "null"
        }
      ]
    },
    "nationality": {
      "oneOf": [
        {
          "$ref": "#/$defs/Nationality"
        },
        {
          "type": "null"
        }
      ]
    },
    "dateOfNationality": {
      "type": [
        "string",
        "null"
      ],
      "description": "The date of nationality of this person, using the `full-date` format as defined in \nRFC 3339 (section 5.6).\n",
      "format": "date"
    },
    "affiliations": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/personAffiliation"
      }
    },
    "email": {
      "type": [
        "string",
        "null"
      ],
      "description": "The primary email address of this person",
      "format": "email",
      "maxLength": 256
    },
    "secondaryEmail": {
      "type": [
        "string",
        "null"
      ],
      "description": "The secondary email address of this person",
      "format": "email",
      "maxLength": 256
    },
    "telephoneNumber": {
      "type": [
        "string",
        "null"
      ],
      "description": "The telephone number of this person",
      "maxLength": 256
    },
    "mobileNumber": {
      "type": [
        "string",
        "null"
      ],
      "description": "The mobile number of this person",
      "maxLength": 256
    },
    "photoSocial": {
      "type": [
        "string",
        "null"
      ],
      "description": "The url of the informal picture of this person",
      "format": "uri",
      "maxLength": 2048
    },
    "photoOfficial": {
      "type": [
        "string",
        "null"
      ],
      "description": "The url of the official picture of this person",
      "format": "uri",
      "maxLength": 2048
    },
    "gender": {
      "oneOf": [
        {
          "$ref": "#/$defs/gender"
        },
        {
          "type": "null"
        }
      ]
    },
    "titlePrefix": {
      "type": [
        "string",
        "null"
      ],
      "description": "A title prefix to be used for this person"
    },
    "titleSuffix": {
      "type": [
        "string",
        "null"
      ],
      "description": "A title suffix to be used for this person"
    },
    "office": {
      "type": [
        "string",
        "null"
      ],
      "description": "The name of the office where this person is located"
    },
    "address": {
      "oneOf": [
        {
          "$ref": "#/$defs/Address"
        },
        {
          "type": "null"
        }
      ]
    },
    "ICEName": {
      "type": [
        "string",
        "null"
      ],
      "description": "Full name of In Case of Emergency contact",
      "maxLength": 256
    },
    "ICEPhoneNumber": {
      "type": [
        "string",
        "null"
      ],
      "description": "Phone number of In Case of Emergency contact",
      "maxLength": 256
    },
    "ICERelation": {
      "oneOf": [
        {
          "$ref": "#/$defs/ICERelationType"
        },
        {
          "type": "null"
        }
      ]
    },
    "languageOfChoice": {
      "type": [
        "array",
        "null"
      ],
      "description": "The language(s) of choice for this person according to RFC4647. For details see the descriptions in the Language schema.",
      "items": {
        "$ref": "#/$defs/Language"
      }
    },
    "otherCodes": {
      "type": [
        "array",
        "null"
      ],
      "description": "An array of additional human readable codes/identifiers for the entity being described.",
      "items": {
        "$ref": "#/$defs/IdentifierEntry"
      }
    },
    "assignedNeeds": {
      "description": "Assigned resources or time based on the needs of a person. \nThey describe which needs the student requires under which conditions e.g. 15% extra time for tests that requires maths skills.\nThese needs can later in the flows be mapped to a personalNeed for a specific association.\nExamples of such assignedNeeds: \"ExtraTimeOnlyMaths25%\", \"ExtraTimeOnlyMaths30Min\", \"ExtraTimeDigitalTests25%\"\n",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "description": "Human readable value for the code/identifier",
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "array",
              "null"
            ],
            "description": "The description of this assignedNeed.",
            "minItems": 1,
            "items": {
              "$ref": "#/$defs/LanguageTypedString"
            }
          },
          "startDateTime": {
            "type": [
              "string",
              "null"
            ],
            "description": "The moment on which this assigned need starts, RFC3339 (date-time)",
            "format": "date-time"
          },
          "endDateTime": {
            "type": [
              "string",
              "null"
            ],
            "description": "The moment on which this assigned need ends, RFC3339 (date-time)",
            "format": "date-time"
          }
        }
      },
      "minItems": 0
    },
    "consumer": {
      "oneOf": [
        {
          "$ref": "#/$defs/Consumer"
        },
        {
          "type": "null"
        }
      ]
    },
    "ext": {
      "oneOf": [
        {
          "$ref": "#/$defs/Ext"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "description": "The full street address",
      "required": [
        "addressType"
      ],
      "properties": {
        "addressType": {
          "$ref": "#/$defs/addressType"
        },
        "street": {
          "type": [
            "string",
            "null"
          ],
          "description": "The street name"
        },
        "streetNumber": {
          "type": [
            "string",
            "null"
          ],
          "description": "The street number"
        },
        "additional": {
          "type": [
            "array",
            "null"
          ],
          "description": "Further details like building name, suite, apartment number, etc.",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/LanguageTypedString"
          }
        },
        "postCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "Code to help sort and deliver mail also known as Postal code and ZIP code"
        },
        "city": {
          "type": [
            "string",
            "null"
          ],
          "description": "name of the city / locality"
        },
        "countryCode": {
          "oneOf": [
            {
              "$ref": "#/$defs/Country"
            },
            {
              "type": "null"
            }
          ]
        },
        "geolocation": {
          "type": [
            "object",
            "null"
          ],
          "description": "Geolocation of the entrance of this address (WGS84 coordinate reference system)",
          "required": [
            "latitude",
            "longitude"
          ],
          "properties": {
            "latitude": {
              "type": "number",
              "format": "double"
            },
            "longitude": {
              "type": "number",
              "format": "double"
            }
          }
        },
        "ext": {
          "oneOf": [
            {
              "$ref": "#/$defs/Ext"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "Consumer": {
      "type": "object",
      "description": "The additional elements of a consumer that may be provided, see the [documentation on support for specific consumers](https://oeapi.eu/v6.0/#/technical/consumers-and-profiles/) for further information about this mechanism.",
      "required": [
        "consumerKey"
      ],
      "properties": {
        "consumerKey": {
          "description": "The key of the consumer (destination) for which this information is intended. See the [consumer registry](https://oeapi.eu/v6.0/#/technical/consumers-and-profiles/). This key is used to select the additional data to be presented in the request.",
          "type": "string"
        },
        "exampleProperty": {
          "description": "An example of an additional property",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": true
    },
    "Country": {
      "type": "object",
      "description": "An object indicating a country based on at least one iso-3166 code. In situations where more than one ISO-3166 code is provided, the codes must refer to the same country.\n",
      "properties": {
        "iso3166-1-alpha2": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 2,
          "maxLength": 2,
          "description": "A country code based on https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2"
        },
        "iso3166-1-alpha3": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 3,
          "maxLength": 3,
          "description": "A country code based on https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3"
        },
        "iso3166-2": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 5,
          "maxLength": 6,
          "description": "A country subdivision code based on https://en.wikipedia.org/wiki/ISO_3166-2"
        },
        "iso3166-3": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 4,
          "maxLength": 4,
          "description": "A code for a country that no longer exists is listed on ISO 3166-3 (https://en.wikipedia.org/wiki/ISO_3166-3).\nImplementations should refrain from using the original ISO 3166-1 code for such a country since country codes\ncan be reassigned to new countries once the original country code is officially declared obsolete.\n"
        }
      }
    },
    "Ext": {
      "type": "object",
      "description": "Object for additional non-standard attributes"
    },
    "ICERelationType": {
      "type": "string",
      "description": "The type of relationship between the person and their In Case of Emergency (ICE) contact:\n\n- partner: Spouse or life partner\n- parent: Biological, adoptive, or legal parent\n- other: Any other type of relationship (e.g. sibling, friend, neighbour)\n\nThis is an *extensible enumeration*. Use the prefix `x-` for custom values.\n",
      "x-ooapi-extensible-enum": [
        "partner",
        "parent",
        "other"
      ]
    },
    "IdentifierEntry": {
      "type": "object",
      "properties": {
        "codeType": {
          "$ref": "#/$defs/codeType"
        },
        "code": {
          "description": "Human readable value for the code/identifier",
          "type": "string"
        }
      },
      "required": [
        "codeType",
        "code"
      ],
      "additionalProperties": false
    },
    "Language": {
      "description": "The language used in the described entity. The value **must be a language tag that conforms to RFC 5646** (Tags for Identifying Languages, BCP 47):\nhttps://www.rfc-editor.org/rfc/rfc5646.html\n\nA tag consists of the following components, in this exact order:\n1. **language** – two‑ to three‑letter codes (ISO 639‑1/‑2) **or** four‑letter codes (ISO 639‑5) **or** five‑ to eight‑letter registered language subtags.\n2. **script** – optional, four letters in Title‑Case (e.g. `Latn`, `Hant`).\n3. **region** – optional, either two uppercase letters (ISO 3166‑1) **or** three digits (UN M.49).\n4. **variant** – zero or more subtags, each either five‑ to eight‑alphanumerics or a digit followed by three alphanumerics (e.g. `1901`, `oxendict`).\n5. **extension** – zero or more extensions. Each extension starts with a *singleton* (a single alphanumeric character except `x`) followed by one or more subtags of two‑ to eight‑alphanumerics (e.g. `u‑co‑phonebk`).\n6. **private‑use** – optional, the letter `x` followed by one or more subtags of one‑ to eight‑alphanumerics (e.g. `x‑private`).\n\nThe most common form is a two‑letter language code (ISO 639‑1) optionally followed by a hyphen and a two‑letter country code (ISO 3166‑1), for example `en` or `en‑GB`.\n\nMore specific tags are also valid, for instance `zh‑Hant‑TW` (Traditional Chinese as used in Taiwan).\n\nFor sign languages two conventions are recognised:\n* `sgn` – e.g. `nl‑sgn‑NL` (Dutch Sign Language)\n* `s`   – e.g. `nl‑s‑NL` (Dutch Sign Language)\n",
      "type": "string",
      "minLength": 2,
      "pattern": "^(?:(?:[A-Za-z]{2,3}(?:-[A-Za-z]{3}){0,2}|[A-Za-z]{4}|[A-Za-z]{5,8})(?:-[A-Za-z]{4})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*?(?:-(?:[A-WY-Za-wy-z0-9](?:-[A-Za-z0-9]{2,8})+))*?(?:-x(?:-[A-Za-z0-9]{1,8})+)?|x(?:-[A-Za-z0-9]{1,8})+)$"
    },
    "LanguageTypedString": {
      "type": "object",
      "description": "A String with an associated language code. IF this object is used both fields are mandatory.",
      "required": [
        "language",
        "value"
      ],
      "properties": {
        "language": {
          "$ref": "#/$defs/Language"
        },
        "value": {
          "description": "String to describe the entity.",
          "type": "string"
        }
      }
    },
    "Nationality": {
      "type": "object",
      "description": "An object indicating nationality based on at least one iso-3166 code. In situations where more than one iso-3166 code is provided the codes have address the same country.\n",
      "properties": {
        "iso3166-1-alpha2": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 2,
          "maxLength": 2,
          "description": "A country code based on https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2"
        },
        "iso3166-1-alpha3": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 3,
          "maxLength": 3,
          "description": "A country code based on https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3"
        },
        "iso3166-3": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 4,
          "maxLength": 4,
          "description": "A nationality code for a country that no longer exists on https://en.wikipedia.org/wiki/ISO_3166-3 It is not advised to use the original iso3166-1 for such a country since country codes can get reassigned to new countries ones the original country code is officially obsolete. It is possible that a person has a nationality of a country that does not exist any more (after a country got split up like CZ and YU)\\ and never applied for nationality of one of the new countries.\n"
        }
      }
    },
    "addressType": {
      "type": "string",
      "description": "The type of address, indicating its intended use:\n  \n- postal: Used for receiving post\n- visit: Used for physical visits\n- deliveries: Used for deliveries\n- invoicing: Used for invoicing purposes\n- teaching: The location where educational activities take place\n\nThis is an *extensible enumeration*. Use the prefix `x-` for custom values.\n",
      "x-ooapi-extensible-enum": [
        "postal",
        "visit",
        "deliveries",
        "invoicing",
        "teaching"
      ]
    },
    "codeType": {
      "type": "string",
      "description": "The type of code or identifier.\n\nThe predefined values are:\n\n| Code                      | Description                                                       |\n|---------------------------|-------------------------------------------------------------------|\n| `account_id`              | Identifier for an account.                                        |\n| `bag_id`                  | Identifier for a building in the Dutch Building and Address       |\n|                           | Registry (BAG).                                                   |\n| `building_id`             | Identifier for a building.                                        |\n| `component_code`          | Identifier for a component (part of a course).                    |\n| `eckid`                   | Identifier assigned within the Dutch *Educatieve ContentKeten iD* |\n|                           | framework. It enables persistent identification and exchange of   |\n|                           | digital learning resources within the Dutch educational sector for|\n|                           | EQF levels 1, 2, 3 and 4. Comparable international approaches     |\n|                           | include LRMI, DOI and Handle                                      |\n|                           | identifiers for learning resources.                               |\n| `email_address`           | An email address.                                                 |\n| `esi`                     | European Student Identifier.                                      |\n| `group_code`              | Identifier for a group of people.                                 |\n| `group_type_code`         | Identifier for the type of group.                                 |\n| `identifier`              | Generic identifier.                                               |\n| `institution_code`        | Registration number of an educational institution. In the         |\n|                           | Netherlands, the former BRIN code has been replaced by the        |\n|                           | institution code, issued by the Ministry of Education, Culture    |\n|                           | and Science (OCW).                                                |\n| `isbn`                    | International Standard Book Number (for books).                   |\n| `issn`                    | International Standard Serial Number (for periodicals).           |\n| `kvk_organisation_id`     | Identifier for a KvK (Dutch Chamber of Commerce) registered       |\n|                           | organisation.                                                     |\n| `kvk_establishment_id`    | Identifier for a specific establishment of a KvK                  |\n|                           | (Dutch Chamber of Commerce) registered organisation.              |\n| `leerbedrijf_id`          | Dutch registration/accreditation id for organisations offering    |\n|                           | internships for vocational education students.                    |\n| `national_identity_number`| Government-assigned personal identifier (e.g. NI number in the UK,|\n|                           | or *personnummer* in Sweden).                                     |\n| `offering_code`           | Identifier for a specific offering (programme, course or          |\n|                           | component).                                                       |\n| `organisation_id`         | Identifier for an organisation.                                   |\n| `orcid`                   | Open Researcher and Contributor ID.                               |\n| `product_id`              | Identifier for a product.                                         |\n| `programme_code`          | Identifier of a programme (a recognised collection of courses).   |\n|                           | In the Netherlands, the former CREBO and CROHO codes have been    |\n|                           | replaced by the programme code as registered in RIO, under the    |\n|                           | authority of OCW.                                                 |\n| `room_code`               | Identifier for a room.                                            |\n| `schac_home`              | Home organisation represented by its domain name.                 |\n| `student_number`          | Identifier for a student.                                         |\n| `studielink_number`       | Identifier assigned to a student by Studielink (Dutch central     |\n|                           | enrolment system).                                                |\n| `system_id`               | Identifier used within a specific system.                         |\n| `username`                | User login name.                                                  |\n| `uuid`                    | Universally unique identifier.                                    |\n\nThis is an *extensible enumeration*. Use the prefix `x-` for custom values.\n",
      "x-ooapi-extensible-enum": [
        "account_id",
        "bag_id",
        "building_id",
        "component_code",
        "eckid",
        "email_address",
        "esi",
        "group_code",
        "group_type_code",
        "identifier",
        "institution_code",
        "isbn",
        "issn",
        "kvk_organisation_id",
        "kvk_establishment_id",
        "leerbedrijf_id",
        "offering_code",
        "organisation_id",
        "orcid",
        "product_id",
        "programme_code",
        "room_code",
        "schac_home",
        "student_number",
        "studielink_number",
        "system_id",
        "username",
        "uuid",
        "national_identity_number"
      ]
    },
    "gender": {
      "type": "string",
      "description": "The gender of this person, based on international standards for education and data interoperability.\n\nThe values follow practices from agencies such as:\n- European Commission (EULF, INSPIRE, GeoDCAT-AP)\n- Edustandaard, EUNIS\n\n- m: male\n- f: female\n- x: non-binary or gender-diverse, officially registered\n- o: other gender identity, not officially classified as m/f/x\n- u: unknown or not registered\n- n: not applicable, e.g. for non-person entities or gender-irrelevant use cases\n",
      "x-ooapi-extensible-enum": [
        "m",
        "f",
        "x",
        "o",
        "u",
        "n"
      ]
    },
    "personAffiliation": {
      "type": "string",
      "description": "The affiliations of this person — the roles or relationships a person has with the organisation providing this endpoint:\n\n- student: Enrolled learner or participant in educational offerings\n- employee: Staff member employed by the organisation (e.g. teacher, administrator)\n- guest: External person temporarily affiliated, without formal student or employee status\n\nThis is an extensible enumeration. Use the prefix `x-` for custom values.\n",
      "x-ooapi-extensible-enum": [
        "student",
        "employee",
        "guest"
      ]
    }
  }
}