user-results

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/folio/main/json-schema/folio-user-results-schema.json",
  "title": "user-results",
  "description": "Collection of users",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/folio-edge-users-openapi.yml#/components/schemas/user-results",
  "type": "object",
  "properties": {
    "users": {
      "description": "List of userdata items",
      "type": "array",
      "id": "usersData",
      "items": {
        "type": "object",
        "$ref": "#/$defs/userdata"
      }
    },
    "totalRecords": {
      "type": "integer"
    },
    "resultInfo": {
      "$ref": "#/$defs/result-info",
      "readonly": true
    }
  },
  "$defs": {
    "metadata": {
      "title": "Metadata Schema",
      "description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
      "type": "object",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    },
    "result-info": {
      "description": "Faceting of result sets",
      "type": "object",
      "properties": {
        "totalRecords": {
          "type": "integer",
          "description": "Total number of records"
        },
        "responseTime": {
          "type": "number",
          "description": "Response time"
        },
        "diagnostics": {
          "type": "array",
          "description": "Array of diagnostic information",
          "items": {
            "type": "object",
            "description": "Diagnostic information",
            "properties": {
              "source": {
                "type": "string",
                "description": "Source reporting the diagnostic information"
              },
              "code": {
                "type": "string",
                "description": "Diagnostic Code"
              },
              "message": {
                "type": "string",
                "description": "Diagnostic Message"
              },
              "module": {
                "type": "string",
                "description": "Module reporting diagnostic information"
              },
              "recordCount": {
                "type": "integer",
                "description": "Record Count for diagnostics"
              },
              "query": {
                "type": "string",
                "description": "CQL Query associated with results"
              }
            }
          }
        }
      }
    },
    "tags": {
      "title": "tags",
      "description": "List of simple tags that can be added to an object",
      "type": "object",
      "properties": {
        "tagList": {
          "description": "List of tags",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "userdata": {
      "title": "User Schema",
      "description": "A user",
      "type": "object",
      "properties": {
        "username": {
          "description": "A unique name belonging to a user. Typically used for login",
          "type": "string"
        },
        "id": {
          "description": "A globally unique (UUID) identifier for the user",
          "type": "string"
        },
        "externalSystemId": {
          "description": "An ID that corresponds to an external authority",
          "type": "string"
        },
        "barcode": {
          "description": "The library barcode for this user",
          "type": "string"
        },
        "active": {
          "description": "A flag to determine if a user can log in, take out loans, etc.",
          "type": "boolean"
        },
        "blocked": {
          "description": "A flag to determine if the user has manual blocks",
          "type": "boolean"
        },
        "type": {
          "description": "The class of user",
          "type": "string"
        },
        "patronGroup": {
          "description": "A UUID corresponding to the group the user belongs to",
          "type": "string"
        },
        "patronGroupName": {
          "type": "string",
          "description": "A group name corresponding to the group the user belongs to"
        },
        "departments": {
          "description": "A UUIDs corresponding to the departments the user belongs to",
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "$ref": "#/$defs/uuid"
          }
        },
        "meta": {
          "description": "Deprecated",
          "type": "object"
        },
        "proxyFor": {
          "description": "Deprecated",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "personal": {
          "description": "Personal information about the user",
          "type": "object",
          "properties": {
            "lastName": {
              "description": "The user's surname",
              "type": "string"
            },
            "firstName": {
              "description": "The user's given name",
              "type": "string"
            },
            "middleName": {
              "description": "The user's middle name (if any)",
              "type": "string"
            },
            "preferredFirstName": {
              "description": "The user's preferred name",
              "type": "string"
            },
            "email": {
              "description": "The user's email address",
              "type": "string"
            },
            "phone": {
              "description": "The user's primary phone number",
              "type": "string"
            },
            "mobilePhone": {
              "description": "The user's mobile phone number",
              "type": "string"
            },
            "dateOfBirth": {
              "type": "string",
              "description": "The user's birth date",
              "format": "date-time"
            },
            "addresses": {
              "description": "Physical addresses associated with the user",
              "type": "array",
              "minItems": 0,
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "description": "A unique id for this address",
                    "type": "string"
                  },
                  "countryId": {
                    "description": "The country code for this address",
                    "type": "string"
                  },
                  "addressLine1": {
                    "description": "Address, Line 1",
                    "type": "string"
                  },
                  "addressLine2": {
                    "description": "Address, Line 2",
                    "type": "string"
                  },
                  "city": {
                    "description": "City name",
                    "type": "string"
                  },
                  "region": {
                    "description": "Region",
                    "type": "string"
                  },
                  "postalCode": {
                    "description": "Postal Code",
                    "type": "string"
                  },
                  "addressTypeId": {
                    "description": "A UUID that corresponds with an address type object",
                    "type": "string"
                  },
                  "primaryAddress": {
                    "description": "Is this the user's primary address?",
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            },
            "preferredContactTypeId": {
              "description": "Id of user's preferred contact type",
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "lastName"
          ]
        },
        "enrollmentDate": {
          "description": "The date in which the user joined the organization",
          "type": "string",
          "format": "date-time"
        },
        "expirationDate": {
          "description": "The date for when the user becomes inactive",
          "type": "string",
          "format": "date-time"
        },
        "createdDate": {
          "description": "Deprecated",
          "type": "string",
          "format": "date-time"
        },
        "updatedDate": {
          "description": "Deprecated",
          "type": "string",
          "format": "date-time"
        },
        "metadata": {
          "type": "object",
          "$ref": "#/$defs/metadata"
        },
        "tags": {
          "type": "object",
          "$ref": "#/$defs/tags"
        },
        "customFields": {
          "description": "Object that contains custom field",
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "uuid": {
      "description": "UUID",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    }
  }
}