# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Schema Registry Descriptors API
  version: 1.0.0
extends: openapi/adobe-suite-descriptors-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/{CONTAINER_ID}/descriptors'].get
  update:
    x-apievangelist-phrasing:
      intent: List schema descriptors
      effect: read
      questions:
      - Which descriptors describe relationships and identities across our XDM schemas?
      - Can I page through descriptors in the tenant or global container?
      instructions:
      - text: List descriptors in container {CONTAINER_ID}.
        slots:
          CONTAINER_ID: path.CONTAINER_ID
      - text: Show {limit} descriptors from {CONTAINER_ID} ordered by {orderby}.
        slots:
          limit: query.limit
          CONTAINER_ID: path.CONTAINER_ID
          orderby: query.orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{CONTAINER_ID}/descriptors/{DESCRIPTOR_ID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one schema descriptor
      effect: read
      questions:
      - How do I view a single descriptor by its @id?
      - What does one specific identity or relationship descriptor contain?
      instructions:
      - text: Show descriptor {DESCRIPTOR_ID} in container {CONTAINER_ID}.
        slots:
          DESCRIPTOR_ID: path.DESCRIPTOR_ID
          CONTAINER_ID: path.CONTAINER_ID
      - text: Look up descriptor {DESCRIPTOR_ID} from the {CONTAINER_ID} container.
        slots:
          DESCRIPTOR_ID: path.DESCRIPTOR_ID
          CONTAINER_ID: path.CONTAINER_ID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenant/descriptors'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a schema descriptor
      effect: write
      questions:
      - How do I mark a schema field as a primary identity with a descriptor?
      - Can I define a relationship between two schemas by creating a descriptor?
      instructions:
      - text: Create a descriptor in sandbox {sandbox} from this definition.
        slots:
          sandbox: header.x-sandbox-name
      - text: 'Add a new tenant descriptor: {body}.'
        slots:
          body: body.body
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenant/descriptors/{DESCRIPTOR_ID}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rewrite an existing schema descriptor
      effect: write
      questions:
      - Can I change the field an existing descriptor points to?
      - Does updating a descriptor require resending all its required fields?
      instructions:
      - text: Rewrite descriptor {DESCRIPTOR_ID} with the full definition I provide.
        slots:
          DESCRIPTOR_ID: path.DESCRIPTOR_ID
      - text: Replace descriptor {DESCRIPTOR_ID} in sandbox {sandbox}.
        slots:
          DESCRIPTOR_ID: path.DESCRIPTOR_ID
          sandbox: header.x-sandbox-name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenant/descriptors/{DESCRIPTOR_ID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a schema descriptor
      effect: destructive
      questions:
      - How do I remove a descriptor I added to a schema?
      - Can I delete a descriptor from one sandbox only?
      instructions:
      - text: Delete descriptor {DESCRIPTOR_ID}.
        slots:
          DESCRIPTOR_ID: path.DESCRIPTOR_ID
      - text: Remove descriptor {DESCRIPTOR_ID} from sandbox {sandbox}.
        slots:
          DESCRIPTOR_ID: path.DESCRIPTOR_ID
          sandbox: header.x-sandbox-name
      method: generated
      generated: '2026-09-26'