# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Identity.DirectoryManagement Directory Roles.directory Role…
  version: 1.0.0
extends: openapi/azure-ad-directoryroles-directoryrole-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/directoryRoles'].get
  update:
    x-apievangelist-phrasing:
      intent: List activated directory roles in the tenant
      effect: read
      questions:
      - Which admin roles are currently activated in my Entra tenant?
      - Why don't all built-in roles show up when I list directory roles?
      instructions:
      - text: List all activated directory roles in the tenant.
      - text: List activated directory roles matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directoryRoles'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate a directory role from a template
      effect: write
      questions:
      - How do I activate a built-in admin role so I can assign members to it?
      - Do I need to activate a directory role before reading or updating its members?
      instructions:
      - text: Activate the directory role for template {roleTemplateId}.
        slots:
          roleTemplateId: requestBody.roleTemplateId
      - text: Turn on role template {roleTemplateId} in the tenant with display name {name}.
        slots:
          roleTemplateId: requestBody.roleTemplateId
          name: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directoryRoles/{directoryRole-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a directory role by object ID
      effect: read
      questions:
      - What are the properties of an activated directory role, looked up by its object ID?
      - Can I read a directory role's description using its ID?
      instructions:
      - text: Get directory role {role} by object ID.
        slots:
          role: path.directoryRole-id
      - text: Show directory role {role} with its members expanded via {expand}.
        slots:
          role: path.directoryRole-id
          expand: query.$expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directoryRoles/{directoryRole-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a directory role by object ID
      effect: destructive
      questions:
      - Can I remove an activated directory role using its object ID?
      - Is deleting a directory role by ID allowed?
      instructions:
      - text: Delete directory role {role} by object ID.
        slots:
          role: path.directoryRole-id
      - text: Remove activated role {role} if its ETag matches {etag}.
        slots:
          role: path.directoryRole-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directoryRoles/{directoryRole-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a directory role by object ID
      effect: write
      questions:
      - Can I change an activated directory role's display name or description using its object ID?
      - Is it possible to patch a directory role addressed by ID?
      instructions:
      - text: Update the description of directory role {role} to {description}.
        slots:
          role: path.directoryRole-id
          description: requestBody.description
      - text: Rename directory role with object ID {role} to {name}.
        slots:
          role: path.directoryRole-id
          name: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directoryRoles(roleTemplateId=\'{roleTemplateId}\')'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a directory role by its role template ID
      effect: read
      questions:
      - Can I look up an activated role using the well-known role template ID instead of the object ID?
      - What does the Global Administrator role look like when fetched by template ID?
      instructions:
      - text: Get the directory role with role template ID {roleTemplateId}.
        slots:
          roleTemplateId: path.roleTemplateId
      - text: Fetch the activated role for template {roleTemplateId}, selecting {select}.
        slots:
          roleTemplateId: path.roleTemplateId
          select: query.$select
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directoryRoles(roleTemplateId=\'{roleTemplateId}\')'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a directory role by its role template ID
      effect: destructive
      questions:
      - Can I delete an activated role by referencing its role template ID?
      - Is there a way to remove a directory role without knowing its object ID?
      instructions:
      - text: Delete the directory role with role template ID {roleTemplateId}.
        slots:
          roleTemplateId: path.roleTemplateId
      - text: Remove the activated role for template {roleTemplateId} if its ETag matches {etag}.
        slots:
          roleTemplateId: path.roleTemplateId
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directoryRoles(roleTemplateId=\'{roleTemplateId}\')'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a directory role by its role template ID
      effect: write
      questions:
      - How do I patch an activated role when I only know its role template ID?
      - Can I update a role's description by template ID rather than object ID?
      instructions:
      - text: Update the directory role with role template ID {roleTemplateId} to description {description}.
        slots:
          roleTemplateId: path.roleTemplateId
          description: requestBody.description
      - text: Rename the activated role for template {roleTemplateId} to {name}.
        slots:
          roleTemplateId: path.roleTemplateId
          name: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directoryRoles/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count activated directory roles
      effect: read
      questions:
      - How many directory roles are activated in my tenant?
      - Can I get only the number of activated roles matching a filter?
      instructions:
      - text: Count the activated directory roles in the tenant.
      - text: Count activated directory roles matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'