matrix-spec/data/event-schemas/schema/m.room.power_levels.yaml

---
$schema: https://json-schema.org/draft/2020-12/schema

allOf:
  - $ref: core-event-schema/state_event.yaml
description: |-
  This event specifies the minimum level a user must have in order to perform a
  certain action. It also specifies the levels of each user in the room.

  If a `user_id` is in the `users` list, then that `user_id` has the
  associated power level. Otherwise they have the default level
  `users_default`. If `users_default` is not supplied, it is assumed to be
  0. If the room contains no `m.room.power_levels` event, the room's creator has
  a power level of 100, and all other users have a power level of 0.

  Except for membership events and redactions, the level required to
  send a certain event is governed purely by `events`, `state_default`
  and `events_default`. If an event type is specified in `events`, then
  the user must have at least the level specified in order to send that
  event. If the event type is not supplied, it defaults to `events_default`
  for message events and `state_default` for state events.

  If there is no `state_default` in the `m.room.power_levels` event, or
  there is no `m.room.power_levels` event, the `state_default` is 50.
  If there is no `events_default` in the `m.room.power_levels` event,
  or there is no `m.room.power_levels` event, the `events_default` is 0.

  Membership events are not subject to `events`, `events_default`, or
  `state_default`. Instead, the power level required to invite a user
  to the room, kick a user from the room, or ban a user from the room
  is defined by `invite`, `kick`, and `ban`, respectively. The levels
  for `kick` and `ban` default to 50 if they are not specified in the
  `m.room.power_levels` event, or if the room contains no
  `m.room.power_levels` event. `invite` defaults to 0 in either case.
  Other membership values are handled during event authorization. See
  the authorization rules in [room versions](/rooms) for further details.

  For redactions of a user's own events, the required power level is
  determined by the `m.room.redaction` event power level, as per `events`
  and `events_default`. The power level required to redact an event sent
  by another user is _additionally_ governed by `redact`. The level for
  `redact` defaults to 50 if it is not specified in the `m.room.power_levels`
  event, or if the room contains no `m.room.power_levels` event.

  **Note:**

  The allowed range for power level values is `[-(2**53)+1, (2**53)-1]`,
  as required by the [Canonical JSON specification](/appendices/#canonical-json).  

properties:
  content:
    properties:
      ban:
        description: The level required to ban a user. Defaults to 50 if unspecified.
        type: integer
      events:
        additionalProperties:
          type: integer
        description: |-
          The level required to send specific event types. This is a mapping from event type to power level required.

          Though not a default, when the server sends the initial power levels event during [room creation](/client-server-api#creation)
          in [room versions](/rooms) 12 and higher, the `m.room.tombstone` event MUST be explicitly defined and given
          a power level higher than `state_default`. For example, power level 150. Clients may override this using the
          described `power_level_content_override` field.          
        x-changedInMatrixVersion:
          "1.16": Described `m.room.tombstone` defaults during creation of a room version 12 or higher room.
        title: Event power levels
        type: object
      events_default:
        description: |-
            The default level required to send message events. Can be
            overridden by the `events` key.  Defaults to 0 if unspecified.            
        type: integer
      invite:
        description: The level required to invite a user. Defaults to 0 if unspecified.
        type: integer
      kick:
        description: The level required to kick a user. Defaults to 50 if unspecified.
        type: integer
      redact:
        description: The level required to redact an event sent by another user. Defaults to 50 if unspecified.
        type: integer
      state_default:
        description: |-
            The default level required to send state events. Can be overridden
            by the `events` key. Defaults to 50 if unspecified.            
        type: integer
      users:
        patternProperties:
          "^@":
            x-pattern-format: mx-user-id
            type: integer
        description: |-
          The power levels for specific users. This is a mapping from `user_id` to power level for that user.

          **Note**: In [room versions](/rooms) 12 and higher it is not permitted to specify the room creators here.          
        x-changedInMatrixVersion:
          "1.16": Added a note that room creators cannot be specified here in room versions 12 and higher.
        title: User power levels
        type: object
      users_default:
        x-changedInMatrixVersion:
          "1.16": The room creator power level now changes depending on room version.
        description: |-
            The power level for users in the room whose `user_id` is not mentioned in the `users` key. Defaults to 0 if
            unspecified.

            **Note**: In [room versions](/rooms) 1 through 11, when there is no `m.room.power_levels`
            event in the room, the room creator has a power level of 100, and all other users have a
            power level of 0.

            **Note**: In room versions 12 and higher, room creators have infinite power level regardless
            of the existence of `m.room.power_levels` in the room. When `m.room.power_levels` is not
            in the room however, all other users have a power level of 0.            
        type: integer
      notifications:
        properties:
          room:
            type: integer
            description: The level required to trigger an `@room` notification. Defaults to 50 if unspecified.
        additionalProperties:
          type: integer
        description: |-
            The power level requirements for specific notification types.
            This is a mapping from `key` to power level for that notifications key.            
        title: Notifications
        type: object
    type: object
  state_key:
    description: A zero-length string.
    pattern: '^$'
    type: string
  type:
    enum:
      - m.room.power_levels
    type: string
title: Defines the power levels (privileges) of users in the room.
type: object