# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Booking Custom Attributes API
  version: 1.0.0
extends: openapi/square-bookingcustomattributes-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: 11
- target: $.paths['/v2/bookings/custom-attribute-definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List booking custom field definitions
      effect: read
      questions:
      - What custom fields have been defined for bookings?
      - Can I page through all booking custom attribute definitions?
      instructions:
      - text: List all booking custom attribute definitions.
      - text: Show up to {limit} booking custom field definitions.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/custom-attribute-definitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Define a new custom field for bookings
      effect: write
      questions:
      - How do I add a custom field, like a pet's name, to appointments?
      - Can I define my own data field that applies to every booking?
      instructions:
      - text: Create booking custom attribute definition {custom_attribute_definition}.
        slots:
          custom_attribute_definition: requestBody.custom_attribute_definition
      - text: 'Define a new custom field for appointments: {custom_attribute_definition}.'
        slots:
          custom_attribute_definition: requestBody.custom_attribute_definition
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/custom-attribute-definitions/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a booking custom field definition
      effect: read
      questions:
      - What is the schema of one booking custom attribute definition?
      - Can I read a specific version of a booking custom field definition?
      instructions:
      - text: Get the booking custom attribute definition {key}.
        slots:
          key: path.key
      - text: Show version {version} of booking custom field definition {key}.
        slots:
          version: query.version
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/custom-attribute-definitions/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a booking custom field definition
      effect: write
      questions:
      - How do I rename or change the description of a booking custom field?
      - Can I change the visibility of an existing booking custom attribute definition?
      instructions:
      - text: Update booking custom attribute definition {key} with {custom_attribute_definition}.
        slots:
          key: path.key
          custom_attribute_definition: requestBody.custom_attribute_definition
      - text: Change the definition of booking custom field {key}.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/custom-attribute-definitions/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a booking custom field definition
      effect: destructive
      questions:
      - How do I remove a custom field definition from bookings entirely?
      - What happens to booking values when I delete their custom attribute definition?
      instructions:
      - text: Delete booking custom attribute definition {key}.
        slots:
          key: path.key
      - text: Remove the booking custom field {key} from my account.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/custom-attributes/bulk-delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete custom field values on many bookings
      effect: destructive
      questions:
      - Can I clear a custom field value from many bookings at once?
      - Is there a bulk way to delete booking custom attributes?
      instructions:
      - text: 'Bulk delete these booking custom attributes: {values}.'
        slots:
          values: requestBody.values
      - text: 'Remove custom field values from multiple bookings: {values}.'
        slots:
          values: requestBody.values
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/custom-attributes/bulk-upsert'].post
  update:
    x-apievangelist-phrasing:
      intent: Set custom field values on many bookings
      effect: write
      questions:
      - How do I set a custom field value on lots of appointments in one call?
      - Can I bulk create or update booking custom attributes?
      instructions:
      - text: Bulk upsert booking custom attributes {values}.
        slots:
          values: requestBody.values
      - text: 'Set these custom field values across several bookings: {values}.'
        slots:
          values: requestBody.values
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/{booking_id}/custom-attributes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a booking's custom field values
      effect: read
      questions:
      - What custom field values are stored on a specific appointment?
      - Can I get a booking's custom attributes together with their definitions?
      instructions:
      - text: List custom attributes on booking {booking_id}.
        slots:
          booking_id: path.booking_id
      - text: 'Show custom field values for booking {booking_id} with definitions: {with_definitions}.'
        slots:
          booking_id: path.booking_id
          with_definitions: query.with_definitions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/{booking_id}/custom-attributes/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one custom field value on a booking
      effect: read
      questions:
      - How do I read a single custom field value from an appointment?
      - Can I fetch one booking custom attribute along with its definition?
      instructions:
      - text: Get custom attribute {key} on booking {booking_id}.
        slots:
          key: path.key
          booking_id: path.booking_id
      - text: Read the {key} field value of appointment {booking_id}.
        slots:
          key: path.key
          booking_id: path.booking_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/{booking_id}/custom-attributes/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a custom field value on a booking
      effect: write
      questions:
      - How do I save a custom field value on one appointment?
      - Can I update an existing custom attribute on a single booking?
      instructions:
      - text: Set custom attribute {key} on booking {booking_id} to {custom_attribute}.
        slots:
          key: path.key
          booking_id: path.booking_id
          custom_attribute: requestBody.custom_attribute
      - text: Upsert the {key} field on appointment {booking_id}.
        slots:
          key: path.key
          booking_id: path.booking_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bookings/{booking_id}/custom-attributes/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom field value from a booking
      effect: destructive
      questions:
      - How do I clear one custom field value from a single appointment?
      - Can I remove a custom attribute from one booking without touching its definition?
      instructions:
      - text: Delete custom attribute {key} from booking {booking_id}.
        slots:
          key: path.key
          booking_id: path.booking_id
      - text: Clear the {key} field on appointment {booking_id}.
        slots:
          key: path.key
          booking_id: path.booking_id
      method: generated
      generated: '2026-09-26'