Skip to main content

Permission

Description​

Defines a specific permission required to execute an operation, often associated with a Command or Query Handler.

Definition Schema​

The definition for a permission component expects the following structure:

{
  "$defs": {
    "EnumDefinitionInputDTO": {
      "example": {
        "base_class_name": "BaseStringEnum",
        "members": [
          {
            "name": "CREATE_USER",
            "value": "user:create"
          }
        ],
        "name": "UserAction"
      },
      "properties": {
        "name": {
          "description": "The name for the generated enum class (e.g., 'ItemAction')",
          "title": "Name",
          "type": "string"
        },
        "members": {
          "description": "List of members for this enum.",
          "items": {
            "$ref": "#/$defs/EnumMemberInputDTO"
          },
          "title": "Members",
          "type": "array"
        },
        "base_class_name": {
          "description": "Name of the base enum class to inherit from (e.g., 'BaseStringEnum')",
          "title": "Base Class Name",
          "type": "string"
        }
      },
      "required": [
        "name",
        "members",
        "base_class_name"
      ],
      "title": "EnumDefinitionInputDTO",
      "type": "object"
    },
    "EnumMemberInputDTO": {
      "description": "Defines a constant for an Action, Resource, or Scope enum.",
      "example": {
        "name": "READ_ITEM",
        "value": "read_item"
      },
      "properties": {
        "name": {
          "description": "The ALL_CAPS name for the enum member (e.g., 'CREATE_POST')",
          "title": "Name",
          "type": "string"
        },
        "value": {
          "description": "The string value for the enum member (e.g., 'create_post')",
          "title": "Value",
          "type": "string"
        }
      },
      "required": [
        "name",
        "value"
      ],
      "title": "EnumMemberInputDTO",
      "type": "object"
    }
  },
  "description": "DTO for defining a custom Permission subclass and its associated enums.",
  "example": {
    "action_enum": {
      "base_class_name": "BaseStringEnum",
      "members": [
        {
          "name": "UPDATE",
          "value": "update"
        }
      ],
      "name": "ProfileAction"
    },
    "custom_permission_class_name": "CanUpdateOwnProfile",
    "resource_enum": {
      "base_class_name": "BaseStringEnum",
      "members": [
        {
          "name": "PROFILE",
          "value": "profile"
        }
      ],
      "name": "ProfileResource"
    },
    "scope_enum": {
      "base_class_name": "BaseStringEnum",
      "members": [
        {
          "name": "OWN",
          "value": "own"
        }
      ],
      "name": "ProfileScope"
    },
    "scope_is_list": false
  },
  "properties": {
    "custom_permission_class_name": {
      "description": "Name of the custom Permission subclass to generate (e.g., 'CanManageUserProfilePermission')",
      "title": "Custom Permission Class Name",
      "type": "string"
    },
    "action_enum": {
      "$ref": "#/$defs/EnumDefinitionInputDTO"
    },
    "resource_enum": {
      "$ref": "#/$defs/EnumDefinitionInputDTO"
    },
    "scope_enum": {
      "anyOf": [
        {
          "$ref": "#/$defs/EnumDefinitionInputDTO"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "scope_is_list": {
      "default": false,
      "description": "If true, scope type hint will be List[CustomScope] | None, else CustomScope | None",
      "title": "Scope Is List",
      "type": "boolean"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Docstring of the permission class.",
      "title": "Description"
    },
    "resource_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Flattened string value of the resource.",
      "title": "Resource Name"
    },
    "actions": {
      "description": "List of flattened string values for actions.",
      "items": {
        "type": "string"
      },
      "title": "Actions",
      "type": "array"
    },
    "scope_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Flattened string value of the scope, if any.",
      "title": "Scope Name"
    }
  },
  "required": [
    "custom_permission_class_name",
    "action_enum",
    "resource_enum"
  ],
  "title": "CustomPermissionClassInputDTO",
  "type": "object"
}

Naming and Location Conventions​

Class: PascalCase, typically ends with 'Permission'. File: ${handler_permission_name}.py (based on ${handler_permission_name}). Location: app/application/${bounded_ctx}/handlers. (Requires context: ['bounded_ctx'])

Example Definition​

{
  "custom_permission_class_name": "CanUpdateOwnProfile",
  "action_enum": {
    "name": "ProfileAction",
    "base_class_name": "BaseStringEnum",
    "members": [
      {
        "name": "UPDATE",
        "value": "update"
      }
    ]
  },
  "resource_enum": {
    "name": "ProfileResource",
    "base_class_name": "BaseStringEnum",
    "members": [
      {
        "name": "PROFILE",
        "value": "profile"
      }
    ]
  },
  "scope_enum": {
    "name": "ProfileScope",
    "base_class_name": "BaseStringEnum",
    "members": [
      {
        "name": "OWN",
        "value": "own"
      }
    ]
  },
  "scope_is_list": false
}