User Types

A user type is the schema of a kind of user. It declares the fields that users of that type have, beyond the standard ones, together with their types and validation rules. Every user create and update is validated against the schema of the user's type.

With user types you can, without changing any code:

• add custom fields (a phone number, a birth date, a list of addresses, a loyalty tier…),
• make fields required, unique, or limited to a set of values,
• build a hierarchy of types (Customer and Employee both extending Person),
• let a back office generate forms from the schema.

Inheritance#

User types inherit from each other through baseType. Every chain ends in the built-in base-user type, which declares the standard fields of all users:

base-user is abstract: no user can have it as their type, you always create your own types. It is not stored in the database and is not returned by the list endpoint, but GET /user-types/all and GET /user-types/base-user include it.

base-user (abstract)
└── person (abstract)       + phone, birth_date
    ├── customer            + loyalty_tier, addresses
    └── employee (sealed)   + department, employee_no

A type has all the fields of its ancestors plus its own.

A type can't be both abstract and sealed, and a chain can't loop back on itself.

The user type object#

{
	"_id": "66f1c0d2a4b5c6d7e8f90130",
	"name": "Customer",
	"slug": "customer",
	"description": "People who buy from us",
	"baseType": "person",
	"isAbstract": false,
	"isSealed": false,
	"allowAdditionalProperties": false,
	"properties": {
		"loyalty_tier": {
			"type": "enum",
			"displayName": "Loyalty Tier",
			"items": [
				{ "displayName": "Bronze", "value": "bronze" },
				{ "displayName": "Silver", "value": "silver" },
				{ "displayName": "Gold", "value": "gold" }
			],
			"defaultValue": "bronze"
		},
		"customer_no": {
			"type": "string",
			"isRequired": true,
			"isUnique": true,
			"regexPattern": "^C[0-9]{8}$"
		},
		"addresses": {
			"type": "array",
			"maxCount": 5,
			"itemSchema": {
				"type": "object",
				"properties": {
					"label": { "type": "string", "isRequired": true },
					"city": { "type": "string", "isRequired": true },
					"location": { "type": "location" }
				}
			}
		}
	},
	"membership_id": "66f1c0d2a4b5c6d7e8f90123",
	"sys": { "created_at": "2026-01-01T12:00:00Z", "created_by": "admin" }
}

Fields#

Each entry of properties describes one field. The key is the field name as it appears on users.

Common options#

Field types#

Primitive types

Formatted types

Date and time values are stored in UTC. A datetime without an offset is read as UTC.

Examples#

A phone number:

"phone": {
	"type": "string",
	"displayName": "Phone",
	"maxLength": 20,
	"regexPattern": "^\\+?[0-9 ()-]{7,20}$"
}

A birth date that must be in the past century:

"birth_date": {
	"type": "date",
	"minValue": "1926-01-01"
}

A list of interests chosen from a set:

"interests": {
	"type": "enum",
	"isMultiple": true,
	"items": [
		{ "displayName": "Sports", "value": "sports" },
		{ "displayName": "Music", "value": "music" },
		{ "displayName": "Travel", "value": "travel" }
	]
}

The manager of an employee, who must be an employee too:

"manager": {
	"type": "reference",
	"referenceType": "single",
	"contentType": "employee"
}

Unique fields#

When a field is marked isUnique, ErtisAuth creates a MongoDB unique index for it:

• Uniqueness is checked within the membership, among the users of the type that declares the field unique and of the types derived from it.
• Empty values are not counted: many users may leave a unique field empty.
• username and email_address are unique within the membership.

When you mark a field as unique and some users already share a value, the user type change is rejected with 409 UniqueFieldHasDuplicates, which names the duplicate. Clean up the duplicates first.

A user write with a duplicate value answers 400 ValidationException with a field error (see Users).

Unique fields inside array items are checked by the application, not by an index.

Redeclaring inherited fields#

A type can't declare a field that one of its base types already declares (400 SchemaValidationException, "field is already exist in base type"). The exception is a field declared with isVirtual: true in the derived type: it is accepted as long as its type is the same as the inherited one (otherwise 400 SchemaValidationException, "The field type cannot be overwritten on virtual fields").

Endpoints#

All routes are under /memberships/{membershipId}.

Get a user type#

GET /memberships/{membershipId}/user-types/{id}

Returns the type with the fields inherited from its base types.

Field relations#

GET /memberships/{membershipId}/user-types/relations/customer

Groups the fields of a type by the type that declares them, up to base-user. Useful to build forms with one section per level:

{
	"base-user": [ "firstname", "lastname", "username", "email_address", "role", "…" ],
	"person": [ "phone", "birth_date" ],
	"customer": [ "loyalty_tier", "customer_no", "addresses" ]
}

Create a user type#

curl -X POST https://auth.example.com/memberships/<membership_id>/user-types \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"name": "Employee",
		"baseType": "person",
		"isSealed": true,
		"properties": {
			"department": { "type": "string", "isRequired": true },
			"employee_no": { "type": "integer", "isUnique": true, "minimum": 1 }
		}
	}'

Response 201 Created: the user type.

Update a user type#

PUT /memberships/{membershipId}/user-types/{id}

The body has the same fields as the create request and replaces the type: send all its own properties, not only the changed ones.

• Existing users are not rewritten. A new required field without a default value makes later updates of existing users fail until they get a value, so give new required fields a defaultValue or fill them in first.
• The slug of a type that is in use (by users or by derived types) can't change: a new slug is ignored, since users refer to their type by slug.
• An update without any change answers 409 IdenticalDocumentError.

Delete a user type#

DELETE /memberships/{membershipId}/user-types/{id}

Response 204 No Content. A type that still has users or derived types can't be deleted: 400 UserTypeCanNotBeDelete.

Events#

UserTypeCreated, UserTypeUpdated and UserTypeDeleted. See Events.