API Evangelist conversational phrasing for Confluent Cloud Subjects (v1) API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Confluent Cloud Subjects (v1) API
  version: 1.0.0
extends: openapi/confluent-the-data-streaming-platform-subjects-v1-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: 10
- target: $.paths['/subjects/{subject}/versions/{version}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a schema by subject and version
      effect: read
      questions:
      - How do I fetch a specific version of a schema from Schema Registry?
      - Can I retrieve a soft-deleted schema version too?
      instructions:
      - text: Get version {version} of the schema under subject {subject}.
        slots:
          version: path.version
          subject: path.subject
      - text: Fetch schema version {version} of {subject} even if it was soft-deleted.
        slots:
          subject: path.subject
          version: path.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions/{version}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a schema version from a subject
      effect: destructive
      questions:
      - Can I remove one version of a schema without deleting the whole subject?
      - What's the difference between a soft delete and a permanent delete of a schema version?
      instructions:
      - text: Delete version {version} of subject {subject}.
        slots:
          version: path.version
          subject: path.subject
      - text: Permanently delete schema version {version} under {subject}.
        slots:
          version: path.version
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions/{version}/referencedby'].get
  update:
    x-apievangelist-phrasing:
      intent: List schemas that reference a schema
      effect: read
      questions:
      - Which other schemas depend on this schema version through references?
      - Is anything still referencing a schema version before I delete it?
      instructions:
      - text: List the schema IDs that reference version {version} of {subject}.
        slots:
          version: path.version
          subject: path.subject
      - text: Show which schemas point at {subject} version {version}.
        slots:
          version: path.version
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions/{version}/schema'].get
  update:
    x-apievangelist-phrasing:
      intent: Get only the raw schema string for a version
      effect: read
      questions:
      - Can I get just the unescaped schema text for a version, without the wrapper fields?
      - Where do I download the plain schema definition for one subject version?
      instructions:
      - text: Get the raw schema string for version {version} of {subject}.
        slots:
          version: path.version
          subject: path.subject
      - text: Print only the schema body of {subject} version {version}.
        slots:
          version: path.version
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions registered under a subject
      effect: read
      questions:
      - How many schema versions have been registered for a subject?
      - Can I list only the soft-deleted versions of a subject?
      instructions:
      - text: List the versions registered under subject {subject}.
        slots:
          subject: path.subject
      - text: Show only the deleted versions of {subject}.
        slots:
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new schema version under a subject
      effect: write
      questions:
      - How do I register a new schema with Confluent Schema Registry?
      - Can I register a Protobuf or JSON Schema instead of Avro?
      - Will registering an identical schema again give me back the same ID?
      instructions:
      - text: 'Register this schema under subject {subject}: {schema}.'
        slots:
          subject: path.subject
          schema: requestBody.schema
      - text: Register a {schemaType} schema {schema} for {subject} and normalize it first.
        slots:
          schemaType: requestBody.schemaType
          schema: requestBody.schema
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}'].post
  update:
    x-apievangelist-phrasing:
      intent: Check whether a schema is already registered
      effect: read
      questions:
      - Has this exact schema already been registered under a subject?
      - Can I find out a schema's global ID and version without registering it?
      instructions:
      - text: Check if schema {schema} already exists under subject {subject}.
        slots:
          schema: requestBody.schema
          subject: path.subject
      - text: Look up the version and ID of schema {schema} in {subject}, including deleted ones.
        slots:
          schema: requestBody.schema
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a subject and all its versions
      effect: destructive
      questions:
      - Can I delete an entire subject along with its compatibility level?
      - Does a hard delete of a subject require a soft delete first?
      instructions:
      - text: Delete subject {subject}.
        slots:
          subject: path.subject
      - text: Permanently delete subject {subject} and every version under it.
        slots:
          subject: path.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects'].get
  update:
    x-apievangelist-phrasing:
      intent: List registered subjects
      effect: read
      questions:
      - What subjects are registered in my Schema Registry?
      - Can I list only the subjects whose names start with a certain prefix?
      instructions:
      - text: List all subjects in the schema registry.
      - text: List subjects that start with {prefix}.
        slots:
          prefix: query.subjectPrefix
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subjects/{subject}/metadata'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the latest schema version matching metadata
      effect: read
      questions:
      - Can I find the newest schema version tagged with a particular metadata key and value?
      - Which schema version under a subject carries a given metadata property?
      instructions:
      - text: Get the latest version of {subject} whose metadata {key} equals {value}.
        slots:
          subject: path.subject
          key: query.key
          value: query.value
      - text: Find the most recent {subject} schema tagged with metadata {key}.
        slots:
          subject: path.subject
          key: query.key
      method: generated
      generated: '2026-09-26'