Group

{
  "$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-group-schema.json",
  "title": "Group",
  "description": "A group is simply a collection of persons. Groups can be used to accommodate various usecases.\n\nGroups MAY optionally have a relation to an Offering, however the meaning of such relations is left unspecified and is left up to the implementer.\n",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/open-education-api-v5-openapi.yml#/components/schemas/Group",
  "type": "object",
  "required": [
    "groupId",
    "groupType",
    "name",
    "primaryCode"
  ],
  "properties": {
    "groupId": {
      "type": "string",
      "description": "Unique id for this group",
      "format": "uuid"
    },
    "primaryCode": {
      "description": "The primary human readable identifier for this group. This is often the source identifier as defined by the institution.",
      "$ref": "#/$defs/IdentifierEntry"
    },
    "groupType": {
      "$ref": "#/$defs/groupType"
    },
    "name": {
      "type": "array",
      "description": "The name of this group",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/LanguageTypedString"
      }
    },
    "description": {
      "type": "array",
      "description": "The description of this group",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/LanguageTypedString"
      }
    },
    "startDate": {
      "type": "string",
      "description": "The day on which this group starts being active, RFC3339 (full-date)",
      "format": "date"
    },
    "endDate": {
      "type": "string",
      "description": "The day on which this group ends being active, RFC3339 (full-date)",
      "format": "date"
    },
    "personCount": {
      "type": "number",
      "description": "The number of persons that are member of this group",
      "format": "int32",
      "minimum": 0
    },
    "otherCodes": {
      "type": "array",
      "description": "An array of additional human readable codes/identifiers for the entity being described.",
      "items": {
        "$ref": "#/$defs/IdentifierEntry"
      }
    },
    "consumers": {
      "description": "The additional consumer elements that can be provided, see the [documentation on support for specific consumers](https://openonderwijsapi.nl/v5/#/technical/consumers-and-profiles/) for more information about this mechanism.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Consumer"
      }
    },
    "organization": {
      "description": "The organization that manages this group. [`expandable`](.#tag/organization_model)\nBy default only the `organizationId` (a string) is returned. If the client requested an expansion of `organization` the full organization object should be returned.\n",
      "oneOf": [
        {
          "$ref": "#/$defs/Identifier",
          "title": "organizationId"
        },
        {
          "$ref": "#/$defs/Organization",
          "title": "Expanded organization"
        }
      ]
    },
    "ext": {
      "$ref": "#/$defs/Ext"
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "description": "The full street address",
      "required": [
        "addressType"
      ],
      "properties": {
        "addressType": {
          "$ref": "#/$defs/addressType"
        },
        "street": {
          "type": "string",
          "description": "The street name"
        },
        "streetNumber": {
          "type": "string",
          "description": "The street number"
        },
        "additional": {
          "type": "array",
          "description": "Further details like building name, suite, apartment number, etc.",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/LanguageTypedString"
          }
        },
        "postalCode": {
          "type": "string",
          "description": "Postal code"
        },
        "city": {
          "type": "string",
          "description": "name of the city / locality"
        },
        "countryCode": {
          "type": "string",
          "description": "the country code according to [iso-3166-1-alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)"
        },
        "geolocation": {
          "type": "object",
          "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": {
          "$ref": "#/$defs/Ext"
        }
      }
    },
    "Consumer": {
      "type": "object",
      "description": "Object for communicating data to a specific consumer (destination). This object has no relationship with the `consumer` query parameter.",
      "required": [
        "consumerKey"
      ],
      "properties": {
        "consumerKey": {
          "description": "The key of the consumer (destination) for which this information is intended. See the [consumer registry](https://openonderwijsapi.nl/v5/#/technical/consumers-and-profiles/) for more information.",
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "Ext": {
      "type": "object",
      "description": "Object for additional non-standard attributes"
    },
    "Identifier": {
      "type": "string",
      "description": "An identifier of another resource.",
      "format": "uuid"
    },
    "IdentifierEntry": {
      "type": "object",
      "properties": {
        "codeType": {
          "$ref": "#/$defs/codeType"
        },
        "code": {
          "description": "Human readable value for the code/identifier",
          "type": "string"
        }
      },
      "required": [
        "codeType",
        "code"
      ],
      "additionalProperties": false
    },
    "LanguageTypedString": {
      "type": "object",
      "description": "A String with an associated language code.",
      "properties": {
        "language": {
          "description": "The language used in the described entity. A string formatted according to RFC3066.",
          "type": "string",
          "pattern": "^[a-z]{2,4}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$"
        },
        "value": {
          "description": "String to describe the entity.",
          "type": "string"
        }
      }
    },
    "Organization": {
      "type": "object",
      "description": "A description of a group of people working together to achieve a goal",
      "required": [
        "organizationId",
        "organizationType",
        "name",
        "shortName",
        "primaryCode"
      ],
      "properties": {
        "organizationId": {
          "type": "string",
          "description": "Unique id of this organization",
          "format": "uuid",
          "readOnly": true
        },
        "primaryCode": {
          "description": "The primary human readable identifier for the organization. This is often the source identifier as defined by the institution.",
          "$ref": "#/$defs/IdentifierEntry",
          "readOnly": true
        },
        "organizationType": {
          "$ref": "#/$defs/organizationType"
        },
        "name": {
          "type": "array",
          "description": "The name of the organization",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/LanguageTypedString"
          }
        },
        "shortName": {
          "type": "string",
          "description": "Short name of the organization",
          "maxLength": 256
        },
        "description": {
          "type": "array",
          "description": "Any general description of the organization should clearly mention the type of higher education organization, especially in the case of a binary system. In Dutch; universiteit (university) or hogeschool (university of applied sciences).",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/LanguageTypedString"
          }
        },
        "addresses": {
          "type": "array",
          "description": "Addresses of this organization",
          "items": {
            "$ref": "#/$defs/Address"
          }
        },
        "link": {
          "type": "string",
          "description": "URL of the organization's website",
          "format": "uri",
          "maxLength": 2048
        },
        "logo": {
          "type": "string",
          "description": "Logo of this organization",
          "format": "uri",
          "maxLength": 2048
        },
        "otherCodes": {
          "type": "array",
          "description": "An array of additional human readable codes/identifiers for the entity being described.",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/IdentifierEntry"
          }
        },
        "parent": {
          "description": "The organizational unit which is the parent of this organization. [`expandable`](#tag/organization_model)\nBy default only the `organizationId` (a string) is returned. If the client requested an expansion of `organization` the full organization object should be returned.\n",
          "oneOf": [
            {
              "$ref": "#/$defs/Identifier",
              "title": "organizationId"
            },
            {
              "$ref": "#/$defs/Organization",
              "title": "Organization object"
            }
          ]
        },
        "children": {
          "type": "array",
          "description": "All the organizational units for which this organization is the parent. [`expandable`](#tag/organization_model)\nBy default only the `organizationId` (a string) is returned. If the client requested an expansion of `organization` the full organization object should be returned.\n",
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/Identifier",
                "title": "organizationId"
              },
              {
                "$ref": "#/$defs/Organization",
                "title": "Organization object"
              }
            ]
          }
        },
        "consumers": {
          "description": "The additional consumer elements that can be provided, see the [documentation on support for specific consumers](https://openonderwijsapi.nl/v5/#/technical/consumers-and-profiles/) for more information about this mechanism.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Consumer"
          }
        },
        "ext": {
          "$ref": "#/$defs/Ext"
        }
      }
    },
    "addressType": {
      "type": "string",
      "description": "Address type\n- postal: post\n- visit: bezoek\n- deliveries: bezorg\n- billing: factuur\n- teaching: the address where education takes place\n",
      "enum": [
        "postal",
        "visit",
        "deliveries",
        "billing",
        "teaching"
      ]
    },
    "codeType": {
      "type": "string",
      "description": "The code/identifier type. \n\nThis is an *extensible enumeration*. Use `x-` to prefix custom values\n\nThe predefined values are:\n  - `brin`: The registration number for a Dutch educational institution that is issued by the Dutch Ministry of Education, Culture and Science\n  - `crohoCreboCode`: programs with a CREBO and CROHO number are accredited by the Dutch Ministry of Education, Culture and Science (OCW)\n  - `programCode`: Identifier for the program (collection of courses)\n  - `componentCode`: The code for a component (part of a course)\n  - `offeringCode`: The code to identify a specific offering (program, course or component offering)\n  - `organizationId`: The identifier for the organization\n  - `buildingId`: The number or code to identify a building\n  - `bagId`: The identification of a building as it is known in the Dutch Building Administration (BAG)\n  - `roomCode`: The code for a room\n  - `systemId`: Identifier assigned to an entity in context of a specific system\n  - `productId`: Identifier assigned to a specific product\n  - `nationalIdentityNumber`: Identifier assigned by the governement of the person. e.g. a social security number in the USA\n  - `studentNumber`: Identifier for the student\n  - `studielinkNumber`: Identifier for the person as determined by Studielink\n  - `esi`: European Student Identifier\n  - `userName`: The name of a user\n  - `accountId`: Identifier assigned to a specific account\n  - `emailAdress`: An email address\n  - `groupCode`: The identifier for a group (of persons)\n  - `isbn`: International Standard Book Number that serve as product identifiers for Books\n  - `issn`: International Standard Book Number that serve as product identifiers for periodicals\n  - `orcId`: Open Researcher and Contributor ID\n  - `uuid`: A universally unique identifier\n  - `schacHome`: Home organization using the domain name of the organization\n  - `identifier`: Generic Identifier\n",
      "x-ooapi-extensible-enum": [
        "brin",
        "crohoCreboCode",
        "programCode",
        "componentCode",
        "offeringCode",
        "organizationId",
        "buildingId",
        "bagId",
        "roomCode",
        "systemId",
        "productId",
        "nationalIdentityNumber",
        "studentNumber",
        "studielinkNumber",
        "esi",
        "userName",
        "accountId",
        "emailAdress",
        "groupCode",
        "isbn",
        "issn",
        "orcId",
        "uuid",
        "schacHome",
        "identifier"
      ]
    },
    "groupType": {
      "type": "string",
      "description": "The type of this group\n- learning group: A collection of participants carrying out common learning activities\n- class: A collection of participants carrying out jointly scheduled educational activities\n- team: A collection of members of a team, either students, employees or mixed.\n",
      "enum": [
        "learning group",
        "class",
        "team"
      ]
    },
    "organizationType": {
      "type": "string",
      "description": "The type of this organization. Each OOAPI endpoint should have a single organization with type `root`, describing the root organization.\n- root: the root of this organization, representing the Educational Institution itself\n- institute: instituut\n- department: departement\n- faculty: faculteit\n- branch: vestiging\n- academy: academie\n- school: school\n",
      "enum": [
        "root",
        "institute",
        "department",
        "faculty",
        "branch",
        "academy",
        "school"
      ]
    }
  }
}