API Evangelist conversational phrasing for Soda Cloud API v4 Contracts API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Soda Cloud API v4 Contracts API
  version: 1.0.0
extends: openapi/soda-data-contracts-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['/api/v1/contracts'].get
  update:
    x-apievangelist-phrasing:
      intent: List data contracts
      effect: read
      questions:
      - Which datasets in my organization already have data contracts?
      - Can I find the contract for a dataset using its qualified name?
      - What contracts exist across my Soda Cloud account?
      instructions:
      - text: List all data contracts in my organization.
      - text: Find the contract attached to dataset {datasetId}.
        slots:
          datasetId: query.datasetId
      - text: Look up contracts for the dataset named {datasetQualifiedName}.
        slots:
          datasetQualifiedName: query.datasetQualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a contract on a dataset
      effect: write
      questions:
      - How do I start a new data contract for a dataset that has none?
      - Can I create a contract by referencing the dataset's qualified name instead of its ID?
      instructions:
      - text: Create a new contract on dataset {datasetId} with contents {contents}.
        slots:
          datasetId: requestBody.datasetId
          contents: requestBody.contents
      - text: 'Create a contract for {datasetQualifiedName} using this YAML: {contents}.'
        slots:
          datasetQualifiedName: requestBody.datasetQualifiedName
          contents: requestBody.contents
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/actions/createSkeleton'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a skeleton contract from schema
      effect: write
      questions:
      - Can Soda draft a basic contract from a dataset's schema for me?
      - What does a dataset need before a skeleton contract can be generated?
      instructions:
      - text: Generate a skeleton contract from the schema of dataset {datasetId}.
        slots:
          datasetId: requestBody.datasetId
      - text: Build a schema-based skeleton contract for {datasetQualifiedName}.
        slots:
          datasetQualifiedName: requestBody.datasetQualifiedName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/actions/createSkeleton/{operationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check skeleton contract generation status
      effect: read
      questions:
      - Is my skeleton contract generation finished yet?
      - Where do I find the result of a schema-based skeleton contract request?
      instructions:
      - text: Check the status of skeleton contract operation {operationId}.
        slots:
          operationId: path.operationId
      - text: Poll skeleton generation {operationId} until it completes.
        slots:
          operationId: path.operationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/actions/generate'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate contracts with AI
      effect: write
      questions:
      - Can Soda use AI to write contracts for several datasets at once?
      - Why would an AI contract generation request be rejected for my datasets?
      instructions:
      - text: Use AI to generate contracts for datasets {datasetIds}.
        slots:
          datasetIds: requestBody.datasetIds
      - text: Start AI contract generation for the datasets named {datasetQualifiedNames}.
        slots:
          datasetQualifiedNames: requestBody.datasetQualifiedNames
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/actions/generate/{operationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check AI contract generation status
      effect: read
      questions:
      - Has the AI finished generating contracts for my datasets?
      - What state is my batch AI contract generation in?
      instructions:
      - text: Get the status of AI contract generation {operationId}.
        slots:
          operationId: path.operationId
      - text: Poll AI contract generation operation {operationId}.
        slots:
          operationId: path.operationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/{contractId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contract and its YAML
      effect: read
      questions:
      - How do I read the current YAML of a specific data contract?
      - Can I see which checks one contract currently defines?
      instructions:
      - text: Show contract {contractId} including its YAML.
        slots:
          contractId: path.contractId
      - text: Fetch the contents of contract {contractId}.
        slots:
          contractId: path.contractId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/{contractId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish new YAML for a contract
      effect: write
      questions:
      - How do I publish an updated version of an existing contract's YAML?
      - What happens if the contract YAML I publish is malformed?
      instructions:
      - text: 'Publish this YAML to contract {contractId}: {contents}.'
        slots:
          contractId: path.contractId
          contents: requestBody.contents
      - text: Replace the published YAML of contract {contractId} with {contents}.
        slots:
          contractId: path.contractId
          contents: requestBody.contents
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/{contractId}/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a contract verification scan
      effect: write
      questions:
      - Can I trigger a verification scan to test a contract against live data?
      - Is it possible to verify only some of a contract's checks?
      - Which scan ID do I get back after starting a contract verification?
      instructions:
      - text: Verify contract {contractId} now.
        slots:
          contractId: path.contractId
      - text: Run verification on contract {contractId} for only the checks at {checkPaths}.
        slots:
          contractId: path.contractId
          checkPaths: requestBody.checkPaths
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/{contractId}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a contract's version history
      effect: read
      questions:
      - What earlier versions of this contract have been published?
      - Can I see contract versions created before a certain date?
      instructions:
      - text: List the versions of contract {contractId}.
        slots:
          contractId: path.contractId
      - text: Show versions of contract {contractId} created before {createdBefore}.
        slots:
          contractId: path.contractId
          createdBefore: query.createdBefore
      method: generated
      generated: '2026-09-26'