Google Workspace Admin SDK Directory API Models

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/kinlane/google-workspace/json-schema/google-workspace-user-schema.json",
  "title": "Google Workspace Admin SDK Directory API Models",
  "description": "JSON Schema definitions for core resource models in the Google Workspace Admin SDK Directory API, including User, Group, and OrgUnit representations.",
  "$defs": {
    "UserName": {
      "type": "object",
      "title": "User Name",
      "description": "Represents the name of a Google Workspace user, containing given name, family name, and a derived full name.",
      "properties": {
        "givenName": {
          "type": "string",
          "description": "The user's first name. Required when creating a user account.",
          "maxLength": 60
        },
        "familyName": {
          "type": "string",
          "description": "The user's last name. Required when creating a user account.",
          "maxLength": 60
        },
        "fullName": {
          "type": "string",
          "description": "The user's full name formed by concatenating the first and last name values. Read-only.",
          "readOnly": true
        },
        "displayName": {
          "type": "string",
          "description": "The user's display name."
        }
      },
      "required": ["givenName", "familyName"]
    },

    "UserEmail": {
      "type": "object",
      "title": "User Email",
      "description": "An email address associated with a Google Workspace user account.",
      "properties": {
        "address": {
          "type": "string",
          "format": "email",
          "description": "The user's email address."
        },
        "type": {
          "type": "string",
          "description": "The type of the email account, such as home, work, or other."
        },
        "customType": {
          "type": "string",
          "description": "A custom type string when type is set to custom."
        },
        "primary": {
          "type": "boolean",
          "description": "Indicates if this is the user's primary email."
        }
      }
    },

    "UserPhone": {
      "type": "object",
      "title": "User Phone",
      "description": "A phone number associated with a Google Workspace user account.",
      "properties": {
        "value": {
          "type": "string",
          "description": "A human-readable phone number."
        },
        "type": {
          "type": "string",
          "description": "The type of phone number, such as mobile, home, work, or other."
        },
        "customType": {
          "type": "string",
          "description": "A custom type string when type is set to custom."
        },
        "primary": {
          "type": "boolean",
          "description": "Indicates if this is the user's primary phone number."
        }
      }
    },

    "UserAddress": {
      "type": "object",
      "title": "User Address",
      "description": "A physical address associated with a Google Workspace user account.",
      "properties": {
        "type": {
          "type": "string",
          "description": "The address type, such as home, work, or other."
        },
        "customType": {
          "type": "string",
          "description": "A custom type string when type is set to custom."
        },
        "streetAddress": {
          "type": "string",
          "description": "The street address."
        },
        "locality": {
          "type": "string",
          "description": "The town or city of the address."
        },
        "region": {
          "type": "string",
          "description": "The abbreviated province or state."
        },
        "postalCode": {
          "type": "string",
          "description": "The ZIP or postal code."
        },
        "country": {
          "type": "string",
          "description": "Country name."
        },
        "countryCode": {
          "type": "string",
          "description": "The country code using ISO 3166-1 standard."
        },
        "formatted": {
          "type": "string",
          "description": "A full and unstructured postal address."
        },
        "poBox": {
          "type": "string",
          "description": "The post office box."
        },
        "extendedAddress": {
          "type": "string",
          "description": "For extended addresses such as an apartment or suite number."
        },
        "primary": {
          "type": "boolean",
          "description": "If this is the user's primary address."
        },
        "sourceIsStructured": {
          "type": "boolean",
          "description": "Indicates if the user-supplied address was formatted."
        }
      }
    },

    "UserOrganization": {
      "type": "object",
      "title": "User Organization",
      "description": "An organization entry associated with a Google Workspace user, representing their employment or affiliation.",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the organization."
        },
        "title": {
          "type": "string",
          "description": "The user's title within the organization."
        },
        "department": {
          "type": "string",
          "description": "Specifies the department within the organization."
        },
        "description": {
          "type": "string",
          "description": "The description of the organization."
        },
        "costCenter": {
          "type": "string",
          "description": "The cost center of the user's organization."
        },
        "location": {
          "type": "string",
          "description": "The physical location of the organization."
        },
        "domain": {
          "type": "string",
          "description": "The domain the organization belongs to."
        },
        "symbol": {
          "type": "string",
          "description": "Text string symbol of the organization."
        },
        "type": {
          "type": "string",
          "description": "The type of organization."
        },
        "customType": {
          "type": "string",
          "description": "A custom type string when type is set to custom."
        },
        "primary": {
          "type": "boolean",
          "description": "Indicates if this is the user's primary organization."
        },
        "fullTimeEquivalent": {
          "type": "integer",
          "description": "The full-time equivalent millipercent within the organization (100000 = 100%)."
        }
      }
    },

    "UserLocation": {
      "type": "object",
      "title": "User Location",
      "description": "A physical location associated with a Google Workspace user.",
      "properties": {
        "type": {
          "type": "string",
          "description": "The location type, such as desk or default."
        },
        "customType": {
          "type": "string",
          "description": "A custom type string when type is set to custom."
        },
        "area": {
          "type": "string",
          "description": "A textual location, useful for display purposes."
        },
        "buildingId": {
          "type": "string",
          "description": "Building identifier."
        },
        "floorName": {
          "type": "string",
          "description": "Floor name/number."
        },
        "floorSection": {
          "type": "string",
          "description": "Floor section (a more specific location within the floor)."
        },
        "deskCode": {
          "type": "string",
          "description": "Most specific textual code of individual desk location."
        }
      }
    },

    "User": {
      "type": "object",
      "title": "Google Workspace User",
      "description": "Represents a user account in a Google Workspace domain. Users are the primary entities managed through the Admin SDK Directory API. A user account provides access to Google Workspace services and is associated with an organizational unit.",
      "properties": {
        "kind": {
          "type": "string",
          "const": "admin#directory#user",
          "description": "The type of the API resource. Always admin#directory#user.",
          "readOnly": true
        },
        "id": {
          "type": "string",
          "description": "The unique ID for the user. A user id can be used as a user request URI userKey.",
          "readOnly": true
        },
        "etag": {
          "type": "string",
          "description": "ETag of the resource.",
          "readOnly": true
        },
        "primaryEmail": {
          "type": "string",
          "format": "email",
          "description": "The user's primary email address. This property is required to create a user account and must be unique across the domain."
        },
        "name": {
          "$ref": "#/$defs/UserName",
          "description": "Holds the given and family names of the user, and the read-only fullName value."
        },
        "isAdmin": {
          "type": "boolean",
          "description": "Indicates a user with super administrator privileges. Can only be changed via the makeAdmin method.",
          "readOnly": true
        },
        "isDelegatedAdmin": {
          "type": "boolean",
          "description": "Indicates if the user is a delegated administrator.",
          "readOnly": true
        },
        "lastLoginTime": {
          "type": "string",
          "format": "date-time",
          "description": "The last time the user logged in, in ISO 8601 date-time format.",
          "readOnly": true
        },
        "creationTime": {
          "type": "string",
          "format": "date-time",
          "description": "User's Google Workspace account creation time, in ISO 8601 date-time format.",
          "readOnly": true
        },
        "deletionTime": {
          "type": "string",
          "format": "date-time",
          "description": "The time the user's account was deleted, in ISO 8601 date-time format.",
          "readOnly": true
        },
        "agreedToTerms": {
          "type": "boolean",
          "description": "Indicates if the user has completed an initial login and accepted the Terms of Service agreement.",
          "readOnly": true
        },
        "password": {
          "type": "string",
          "description": "Stores the password for the user account. Required when creating a user. Must be 8-100 ASCII characters. Never returned in API responses.",
          "writeOnly": true,
          "minLength": 8,
          "maxLength": 100
        },
        "hashFunction": {
          "type": "string",
          "description": "Stores the hash format of the password property.",
          "enum": ["MD5", "SHA-1", "crypt"]
        },
        "suspended": {
          "type": "boolean",
          "description": "Indicates if the user is suspended."
        },
        "suspensionReason": {
          "type": "string",
          "description": "The reason a user account is suspended. Only returned if the suspended property is true.",
          "readOnly": true
        },
        "changePasswordAtNextLogin": {
          "type": "boolean",
          "description": "Indicates if the user is forced to change their password at next login."
        },
        "ipWhitelisted": {
          "type": "boolean",
          "description": "If true, the user's IP address is subject to a deprecated allowlist configuration."
        },
        "customerId": {
          "type": "string",
          "description": "The unique ID for the customer's Google Workspace account.",
          "readOnly": true
        },
        "orgUnitPath": {
          "type": "string",
          "description": "The full path of the parent organization associated with the user. If the parent is the top-level organization, it is represented as a forward slash (/)."
        },
        "isMailboxSetup": {
          "type": "boolean",
          "description": "Indicates if the user's Google mailbox has been created.",
          "readOnly": true
        },
        "includeInGlobalAddressList": {
          "type": "boolean",
          "description": "Indicates if the user's profile is visible in the Google Workspace global address list."
        },
        "thumbnailPhotoUrl": {
          "type": "string",
          "format": "uri",
          "description": "Photo URL of the user. Read-only.",
          "readOnly": true
        },
        "thumbnailPhotoEtag": {
          "type": "string",
          "description": "ETag of the user's photo.",
          "readOnly": true
        },
        "archived": {
          "type": "boolean",
          "description": "Indicates if the user is archived."
        },
        "recoveryEmail": {
          "type": "string",
          "format": "email",
          "description": "Recovery email of the user."
        },
        "recoveryPhone": {
          "type": "string",
          "description": "Recovery phone of the user. The phone number must be in E.164 format, starting with the plus sign (+)."
        },
        "isEnrolledIn2Sv": {
          "type": "boolean",
          "description": "Is enrolled in 2-step verification.",
          "readOnly": true
        },
        "isEnforcedIn2Sv": {
          "type": "boolean",
          "description": "Is 2-step verification enforced.",
          "readOnly": true
        },
        "emails": {
          "type": "array",
          "description": "A list of the user's email addresses.",
          "items": {
            "$ref": "#/$defs/UserEmail"
          }
        },
        "phones": {
          "type": "array",
          "description": "A list of the user's phone numbers.",
          "items": {
            "$ref": "#/$defs/UserPhone"
          }
        },
        "addresses": {
          "type": "array",
          "description": "A list of the user's addresses.",
          "items": {
            "$ref": "#/$defs/UserAddress"
          }
        },
        "organizations": {
          "type": "array",
          "description": "A list of organizations the user belongs to.",
          "items": {
            "$ref": "#/$defs/UserOrganization"
          }
        },
        "locations": {
          "type": "array",
          "description": "The user's locations.",
          "items": {
            "$ref": "#/$defs/UserLocation"
          }
        },
        "relations": {
          "type": "array",
          "description": "A list of the user's relationships to other users.",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "description": "The name or email of the related person."
              },
              "type": {
                "type": "string",
                "description": "The relation type."
              },
              "customType": {
                "type": "string",
                "description": "A custom type string when type is set to custom."
              }
            }
          }
        },
        "externalIds": {
          "type": "array",
          "description": "A list of external IDs for the user, such as employee or network ID.",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "description": "The value of the external ID."
              },
              "type": {
                "type": "string",
                "description": "The type of external ID."
              },
              "customType": {
                "type": "string",
                "description": "A custom type string when type is set to custom."
              }
            }
          }
        },
        "websites": {
          "type": "array",
          "description": "A list of the user's websites.",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "format": "uri",
                "description": "The URL of the website."
              },
              "type": {
                "type": "string",
                "description": "The website type."
              },
              "customType": {
                "type": "string",
                "description": "A custom type string when type is set to custom."
              },
              "primary": {
                "type": "boolean",
                "description": "Indicates if this is the user's primary website."
              }
            }
          }
        },
        "languages": {
          "type": "array",
          "description": "The user's languages.",
          "items": {
            "type": "object",
            "properties": {
              "languageCode": {
                "type": "string",
                "description": "An ISO 639 language code string."
              },
              "customLanguage": {
                "type": "string",
                "description": "A custom language string."
              },
              "preference": {
                "type": "string",
                "description": "Controls whether the specified languageCode is the user's preferred language."
              }
            }
          }
        },
        "gender": {
          "type": "object",
          "description": "The user's gender.",
          "properties": {
            "type": {
              "type": "string",
              "description": "The gender type: male, female, other, or unknown."
            },
            "customGender": {
              "type": "string",
              "description": "A custom gender string when type is other."
            },
            "addressMeAs": {
              "type": "string",
              "description": "How the user should be addressed."
            }
          }
        },
        "keywords": {
          "type": "array",
          "description": "The user's keywords.",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "description": "The keyword value."
              },
              "type": {
                "type": "string",
                "description": "The keyword type."
              },
              "customType": {
                "type": "string",
                "description": "A custom type string when type is set to custom."
              }
            }
          }
        },
        "notes": {
          "type": "object",
          "description": "Notes for the user.",
          "properties": {
            "value": {
              "type": "string",
              "description": "The contents of the notes."
            },
            "contentType": {
              "type": "string",
              "description": "The content type of the notes body.",
              "enum": ["text_plain", "text_html"]
            }
          }
        },
        "customSchemas": {
          "type": "object",
          "description": "Custom fields of the user. The key is the schema name. The value is an object with field name/value pairs for the schema.",
          "additionalProperties": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "required": ["primaryEmail", "name"]
    },

    "Group": {
      "type": "object",
      "title": "Google Workspace Group",
      "description": "Represents a group in a Google Workspace domain. Groups can be used for email distribution, access control, and collaboration. A group has an email address and can contain users, other groups, and service accounts as members.",
      "properties": {
        "kind": {
          "type": "string",
          "const": "admin#directory#group",
          "description": "The type of the API resource. Always admin#directory#group.",
          "readOnly": true
        },
        "id": {
          "type": "string",
          "description": "The unique ID of the group.",
          "readOnly": true
        },
        "etag": {
          "type": "string",
          "description": "ETag of the resource.",
          "readOnly": true
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "The group's email address. Required when creating a group. Must be unique."
        },
        "name": {
          "type": "string",
          "description": "The group's display name."
        },
        "description": {
          "type": "string",
          "description": "An extended description to help users determine the purpose of a group.",
          "maxLength": 4096
        },
        "adminCreated": {
          "type": "boolean",
          "description": "True if this group was created by an administrator rather than a user.",
          "readOnly": true
        },
        "directMembersCount": {
          "type": "string",
          "description": "The number of users that are direct members of the group. Members of child groups are not counted.",
          "readOnly": true
        },
        "aliases": {
          "type": "array",
          "description": "A list of the group's alias email addresses.",
          "readOnly": true,
          "items": {
            "type": "string",
            "format": "email"
          }
        },
        "nonEditableAliases": {
          "type": "array",
          "description": "A list of the group's non-editable alias email addresses outside of the account's primary domain.",
          "readOnly": true,
          "items": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "required": ["email"]
    },

    "OrgUnit": {
      "type": "object",
      "title": "Google Workspace Organizational Unit",
      "description": "Represents an organizational unit in a Google Workspace domain. Organizational units allow administrators to configure user service access, apply policies, and manage settings hierarchically. The hierarchy is limited to 35 levels of depth.",
      "properties": {
        "kind": {
          "type": "string",
          "const": "admin#directory#orgUnit",
          "description": "The type of the API resource. Always admin#directory#orgUnit.",
          "readOnly": true
        },
        "etag": {
          "type": "string",
          "description": "ETag of the resource.",
          "readOnly": true
        },
        "name": {
          "type": "string",
          "description": "The organizational unit's path name. For example, an organizational unit with parent path /corp and name sales is derived as /corp/sales."
        },
        "description": {
          "type": "string",
          "description": "Description of the organizational unit."
        },
        "orgUnitPath": {
          "type": "string",
          "description": "The full path to the organizational unit. A derived property based on parentOrgUnitPath and the name.",
          "readOnly": true
        },
        "orgUnitId": {
          "type": "string",
          "description": "The unique ID of the organizational unit.",
          "readOnly": true
        },
        "parentOrgUnitPath": {
          "type": "string",
          "description": "The organizational unit's parent path. Required unless parentOrgUnitId is set."
        },
        "parentOrgUnitId": {
          "type": "string",
          "description": "The unique ID of the parent organizational unit. Required unless parentOrgUnitPath is set."
        },
        "blockInheritance": {
          "type": "boolean",
          "description": "Deprecated. Setting this field has no effect.",
          "deprecated": true
        }
      },
      "required": ["name"]
    },

    "Users": {
      "type": "object",
      "title": "Users List",
      "description": "A paginated list response containing Google Workspace user resources.",
      "properties": {
        "kind": {
          "type": "string",
          "const": "admin#directory#users",
          "readOnly": true
        },
        "etag": {
          "type": "string",
          "readOnly": true
        },
        "users": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/User"
          }
        },
        "nextPageToken": {
          "type": "string",
          "description": "Token for retrieving the next page of results."
        }
      }
    },

    "Groups": {
      "type": "object",
      "title": "Groups List",
      "description": "A paginated list response containing Google Workspace group resources.",
      "properties": {
        "kind": {
          "type": "string",
          "const": "admin#directory#groups",
          "readOnly": true
        },
        "etag": {
          "type": "string",
          "readOnly": true
        },
        "groups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Group"
          }
        },
        "nextPageToken": {
          "type": "string",
          "description": "Token for retrieving the next page of results."
        }
      }
    },

    "OrgUnits": {
      "type": "object",
      "title": "OrgUnits List",
      "description": "A list response containing Google Workspace organizational unit resources.",
      "properties": {
        "kind": {
          "type": "string",
          "const": "admin#directory#orgUnits",
          "readOnly": true
        },
        "etag": {
          "type": "string",
          "readOnly": true
        },
        "organizationUnits": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/OrgUnit"
          }
        }
      }
    }
  }
}