> For the complete documentation index, see [llms.txt](https://experience-digital-transform.gitbook.io/experience-digital-transformation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://experience-digital-transform.gitbook.io/experience-digital-transformation/national-learner-registry/learner-registry/data-schema-and-registry-structure.md). # Data Schema and Registry Structure What a schema is, required fields, data consistency, and schema versioning. {% embed url="" %} ## What a Data Schema Is A data schema defines what information can be stored in a registry and how that information is organised. It describes the attributes of a learner profile, the data types that can be used, and the rules that the data must follow before it can be stored. Within the GovStack Digital Registries Building Block, schemas are a core mechanism for maintaining authoritative records. They provide a predictable structure that allows registry data to be validated, searched, exchanged, and reused consistently across services and organisations. In the National Learner Registry, the schema defines the structure of a learner profile. Every learner record stored in the registry follows the same schema, which ensures that learner information is collected and managed consistently. {% hint style="warning" %} A schema should not be confused with a registry record. The schema defines the **structure** of the learner profile, while a registry record contains **information about a specific learner**. {% endhint %} ## Fields, Field Types and Validation Rules A registry schema is composed of fields. Each field represents a specific attribute of the entity maintained by the registry and defines how this information is stored, validated, and interpreted. Together, fields form the structure of a registry record and support consistent search, reporting, and data exchange. The GovStack Digital Registries specification promotes structured and standardised data models. Instead of relying on unrestricted text, registries define explicit data types and validation requirements. This improves data quality and supports interoperability between systems. The table below uses examples from this project's registries to show how fields can be typed and validated: | Field | Type | Validation | | -------------------------- | ------- | ---------------------------------------------------------------------------- | | First Name | String | Minimum and maximum number of characters, permitted or prohibited characters | | Last Name | String | Minimum and maximum number of characters, permitted or prohibited characters | | Date of Birth | Date | Date format, earliest and latest allowed date | | Email Address | String | Email format, allowed domains | | Special Support Needs | Boolean | — | | Previous Education History | Array | — | ## Required Fields for the Learner Registry Within the Student Registration & Enrolment process, learner information is collected during registration and reviewed before the final learner record is created. After approval, the approved learner information becomes part of the authoritative Learner Profile, which contains — or may be expanded to contain — the following attributes: * Unique Learner Identifier (ULID) * Full Name * National ID Number * Date of Birth * Email Address * Phone Number * Residential Address * Educational Institution * Special Support Needs Indicator * Support Needs Description * Previous Education History {% hint style="info" %} **Workflow data vs. authoritative registry data.** Information related to application processing remains outside the National Learner Registry. Application statuses, validation outcomes, approval decisions, rejection reasons, reviewer information, and signer information are stored in the *Applications of Student Registration and Enrolment* registry instead. This reflects the separation between authoritative registry data and workflow or application data: the National Learner Registry stores the final learner profile, while the application registry stores the process history and review context. {% endhint %} ## How Data Consistency Is Maintained Data consistency ensures that registry information remains accurate, complete, and reliable throughout the lifecycle of a record — especially important for authoritative registries, since their information can be reused across multiple services. The GovStack Digital Registries Building Block supports consistency through structured schemas, validation rules, controlled updates, access permissions, and auditability. Within this PoC, every Learner Profile must comply with the schema defined for the National Learner Registry. Educational institutions are not entered as free text — instead, they are selected through a controlled relationship with an Educational Institution directory, helping ensure that learners are linked to consistent and reusable institution records. Additional quality controls are applied before approved information enters the National Learner Registry: learner data is collected through the registration process, reviewed by authorised users, and only then written to the authoritative registry. ## How the Schema Supports Reporting, Search and Future Integrations The structure of a registry determines how effectively information can be searched, analysed, and exchanged — a consistent schema supports one of the key principles of the GovStack Digital Registries Building Block: the reuse of authoritative data across multiple services. Because all Learner Profile records follow the same structure, registry information can be searched, filtered, and aggregated consistently. Standardised attributes such as learner identifiers, names, dates of birth, and educational institution references can be used to generate reliable reports and statistics. Since each field has a defined data type and validation rules, other services or systems can exchange registry data more reliably and with less additional transformation. Within this PoC, authorised users can search learner records by identifiers, names, dates of birth, or institution references. Across the project registries, the same structured approach can support reporting on learner populations, registration trends, institutional participation, certificate issuance, and support requirements. ## Schema Versioning Registry structures evolve as requirements change. New policies, regulations, or services may require additional fields, updated validation rules, or new relationships between records. Schema versioning provides a controlled way to manage these changes while maintaining governance and traceability. The GovStack Digital Registries Building Block recognises schema evolution as an important lifecycle management capability — registry operators must be able to update data models while preserving visibility into what changed and when. Within this PoC, future requirements may introduce new learner attributes, additional references to other registries or internal directories, or updated validation requirements; versioned schemas allow the registry structure to evolve in a controlled way without losing traceability of previous configurations. {% hint style="warning" %} **Schema versioning is not record versioning.** Schema versioning tracks changes to the *structure* of the registry — fields, data types, validation rules, permissions, and configuration. Record versioning tracks changes to *individual records* — for example, updates to a specific learner profile. Together, these capabilities support governance, auditability, and long-term maintainability of the National Learner Registry. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://experience-digital-transform.gitbook.io/experience-digital-transformation/national-learner-registry/learner-registry/data-schema-and-registry-structure.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.