# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Lytics Schema API
  version: 1.0.0
extends: openapi/lytics-schema-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 28
- target: $.paths['/schema'].get
  update:
    x-apievangelist-phrasing:
      intent: List tables with their schemas
      effect: read
      questions:
      - Which data tables does my account have a schema for?
      - Can I list every table along with its schema?
      instructions:
      - text: List all my schema tables.
      - text: Show the tables and schemas on account {account_id}.
        slots:
          account_id: query.account_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/bulk'].put
  update:
    x-apievangelist-phrasing:
      intent: Bulk upsert schema objects (PUT)
      effect: write
      questions:
      - Can I create or update many schema fields and mappings in one PUT request?
      - Does the PUT bulk schema upsert leave existing objects in place?
      instructions:
      - text: PUT a bulk upsert of fields {fields} and mappings {mappings} into table {table}.
        slots:
          fields: requestBody.fields
          mappings: requestBody.mappings
          table: requestBody.table
      - text: Use the PUT bulk endpoint to upsert schema for {table} as a patch {is_patch}.
        slots:
          table: requestBody.table
          is_patch: requestBody.is_patch
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk upsert schema objects (POST)
      effect: write
      questions:
      - Is there a POST version of the bulk schema upsert?
      - How do I post a batch of schema fields and ranks without deleting anything?
      instructions:
      - text: POST bulk schema changes with fields {fields} and ranks {ranks} for table {table}.
        slots:
          fields: requestBody.fields
          ranks: requestBody.ranks
          table: requestBody.table
      - text: Send a POST bulk schema upsert for {table} with retention settings {retention_settings}.
        slots:
          table: requestBody.table
          retention_settings: requestBody.retention_settings
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/expression/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a mapping expression on one event
      effect: read
      questions:
      - What would a mapping expression produce for a sample event?
      - Can I try out an ad hoc mapping expression before saving it?
      instructions:
      - text: Evaluate expression {expression} against event {data}.
        slots:
          expression: requestBody.expression
          data: requestBody.data
      - text: Test mapping expression {expression} on a single event.
        slots:
          expression: requestBody.expression
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/lql'].post
  update:
    x-apievangelist-phrasing:
      intent: Update the schema from an LQL query
      effect: write
      questions:
      - Can I upload an LQL query to add fields and mappings to my schema?
      - Is there a way to migrate legacy LQL into the schema?
      instructions:
      - text: Upload this LQL query to update my schema fields and mappings.
      - text: Apply an LQL file to the schema of account {account_id}.
        slots:
          account_id: query.account_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a table's schema
      effect: read
      questions:
      - What fields, mappings and ranks make up the user table schema?
      - Can I read the schema of a table at a specific draft version?
      instructions:
      - text: Show the current schema for table {table}.
        slots:
          table: path.table
      - text: Get the schema of {table} at version {version_id}.
        slots:
          table: path.table
          version_id: query.version_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/compare'].get
  update:
    x-apievangelist-phrasing:
      intent: Diff two schema versions
      effect: read
      questions:
      - What changed between two versions of my schema?
      - Can I see a diff of my draft schema against another version?
      instructions:
      - text: Compare schema version {version_id} with {compare_id} on table {table}.
        slots:
          version_id: query.version_id
          compare_id: query.compare_id
          table: path.table
      - text: Diff the {table} schema versions.
        slots:
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Evaluate a schema against test events
      effect: read
      questions:
      - Will my published schema map test events the way I expect?
      - Can I run sample events through a table's schema?
      instructions:
      - text: Evaluate the {table} schema against test events.
        slots:
          table: path.table
      - text: Run test events through schema version {version_id} of {table}.
        slots:
          version_id: query.version_id
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/field'].get
  update:
    x-apievangelist-phrasing:
      intent: List the fields in a table schema
      effect: read
      questions:
      - Which fields are defined on my user table?
      - Can I filter the list of schema fields?
      instructions:
      - text: List the fields of table {table}.
        slots:
          table: path.table
      - text: List fields in {table} matching {filter}.
        slots:
          table: path.table
          filter: query.filter
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/field'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or update a field in the draft schema
      effect: write
      questions:
      - How do I add a new field to my draft schema?
      - Can I mark a schema field as PII or as an identifier?
      instructions:
      - text: Add field {id} of type {type} to the {table} draft schema.
        slots:
          id: requestBody.id
          type: requestBody.type
          table: path.table
      - text: Upsert field {id} in {table} with PII set to {is_pii} and identifier {is_identifier}.
        slots:
          id: requestBody.id
          table: path.table
          is_pii: requestBody.is_pii
          is_identifier: requestBody.is_identifier
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/field/{field_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one schema field
      effect: read
      questions:
      - What type and merge behaviour does a particular field have?
      - Can I look up one schema field by its id?
      instructions:
      - text: Show field {field_id} in table {table}.
        slots:
          field_id: path.field_id
          table: path.table
      - text: Get the definition of {table} field {field_id} at version {version_id}.
        slots:
          table: path.table
          field_id: path.field_id
          version_id: query.version_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/field/{field_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a field from the draft schema
      effect: destructive
      questions:
      - Can I remove a field from my draft schema?
      - Is a deleted schema field soft-deleted or gone for good?
      instructions:
      - text: Delete field {field_id} from the {table} draft schema.
        slots:
          field_id: path.field_id
          table: path.table
      - text: Drop schema field {field_id} on {table}.
        slots:
          field_id: path.field_id
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/idconfig'].get
  update:
    x-apievangelist-phrasing:
      intent: List identity merge settings for all fields
      effect: read
      questions:
      - How are graph compaction and many-to-one merging set up across my identity fields?
      - Can I see the identity config of every identifier at once?
      instructions:
      - text: List identity config for all fields in {table}.
        slots:
          table: path.table
      - text: Show graph compaction settings across {table} identity fields.
        slots:
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/idconfig'].post
  update:
    x-apievangelist-phrasing:
      intent: Set identity merge config for a field
      effect: write
      questions:
      - Can I change how one identity field is compacted or merged?
      - How do I configure many-to-one merging for an identifier?
      instructions:
      - text: Create or update identity merge config for a field in {table}.
        slots:
          table: path.table
      - text: Save many-to-one merging settings for an identifier on {table}.
        slots:
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/idconfig/{field_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get identity merge config for one field
      effect: read
      questions:
      - What merge settings apply to one particular identity field?
      - Is graph compaction turned on for a given identifier?
      instructions:
      - text: Show identity config for field {field_id} in {table}.
        slots:
          field_id: path.field_id
          table: path.table
      - text: Get the merging settings of identifier {field_id} on {table}.
        slots:
          field_id: path.field_id
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/idconfig/{field_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove identity merge config from a field
      effect: destructive
      questions:
      - Can I clear the compaction and merge settings on one identifier?
      - How do I delete the ID settings from a schema field?
      instructions:
      - text: Delete the identity config of field {field_id} in {table}.
        slots:
          field_id: path.field_id
          table: path.table
      - text: Clear ID settings on {table} field {field_id}.
        slots:
          table: path.table
          field_id: path.field_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/mapping'].get
  update:
    x-apievangelist-phrasing:
      intent: List the mappings in a table schema
      effect: read
      questions:
      - Which data mappings feed my user table?
      - Can I see every mapping in the schema at a given version?
      instructions:
      - text: List the mappings of table {table}.
        slots:
          table: path.table
      - text: Show {table} mappings at version {version_id}.
        slots:
          table: path.table
          version_id: query.version_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/mapping'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or update a mapping in the draft schema
      effect: write
      questions:
      - How do I map an incoming stream field into a schema field?
      - Can a mapping have a guard expression so it only applies sometimes?
      instructions:
      - text: Map stream {stream} into field {field} of {table} using {expr}.
        slots:
          stream: requestBody.stream
          field: requestBody.field
          table: path.table
          expr: requestBody.expr
      - text: Upsert a mapping for field {field} on {table} guarded by {guard_expr}.
        slots:
          field: requestBody.field
          table: path.table
          guard_expr: requestBody.guard_expr
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/mapping/{mapping_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one schema mapping
      effect: read
      questions:
      - What expression does a particular mapping use?
      - Can I look up one mapping by its id?
      instructions:
      - text: Show mapping {mapping_id} in table {table}.
        slots:
          mapping_id: path.mapping_id
          table: path.table
      - text: Get the definition of {table} mapping {mapping_id}.
        slots:
          table: path.table
          mapping_id: path.mapping_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/mapping/{mapping_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a mapping from the draft schema
      effect: destructive
      questions:
      - Can I remove a data mapping I added by mistake?
      - Is a deleted mapping soft-deleted from the draft?
      instructions:
      - text: Delete mapping {mapping_id} from the {table} draft schema.
        slots:
          mapping_id: path.mapping_id
          table: path.table
      - text: Drop data mapping {mapping_id} on {table}.
        slots:
          mapping_id: path.mapping_id
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish draft schema changes
      effect: write
      questions:
      - How do I make my draft schema changes go live?
      - Can I tag a schema version when publishing it?
      instructions:
      - text: Publish the draft schema for {table}.
        slots:
          table: path.table
      - text: Publish {table} schema changes with tag {tag} and note {description}.
        slots:
          table: path.table
          tag: requestBody.tag
          description: requestBody.description
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/rank'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the identifier rank list
      effect: read
      questions:
      - In what order are identifiers ranked when resolving profiles?
      - Which identity field ranks highest in my schema?
      instructions:
      - text: Show the identifier rank list for {table}.
        slots:
          table: path.table
      - text: Get {table} identifier ranks at version {version_id}.
        slots:
          table: path.table
          version_id: query.version_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/rank'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the identifier rank list
      effect: write
      questions:
      - Can I reorder which identifiers take priority?
      - How do I change the identifier ranking in my draft schema?
      instructions:
      - text: Set the identifier rank order of {table} to {fields}.
        slots:
          table: path.table
          fields: requestBody.fields
      - text: Apply rank changes {changes} to {table}.
        slots:
          changes: requestBody.changes
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/retentionsettings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get data retention settings
      effect: read
      questions:
      - How long is profile data kept for my table?
      - What retention capacity is set on a schema?
      instructions:
      - text: Show retention settings for {table}.
        slots:
          table: path.table
      - text: Get {table} retention at version {version_id}.
        slots:
          table: path.table
          version_id: query.version_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/retentionsettings'].post
  update:
    x-apievangelist-phrasing:
      intent: Change data retention settings
      effect: write
      questions:
      - Can I shorten how many days of data a table keeps?
      - How do I set a retention capacity on my schema?
      instructions:
      - text: Keep {keep_days} days of data in {table}.
        slots:
          keep_days: requestBody.keep_days
          table: path.table
      - text: Set retention capacity of {table} to {capacity}.
        slots:
          table: path.table
          capacity: requestBody.capacity
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/revert'].post
  update:
    x-apievangelist-phrasing:
      intent: Revert a draft schema to the live version
      effect: destructive
      questions:
      - Can I throw away my draft schema edits and go back to what is live?
      - How do I undo every unpublished change to a schema?
      instructions:
      - text: Revert the {table} draft schema to the live schema.
        slots:
          table: path.table
      - text: Discard changes in schema version {version_id} of {table}.
        slots:
          version_id: query.version_id
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/validate'].get
  update:
    x-apievangelist-phrasing:
      intent: Validate a schema
      effect: read
      questions:
      - Is my draft schema valid before I publish it?
      - What validation errors does a schema version have?
      instructions:
      - text: Validate the schema of {table}.
        slots:
          table: path.table
      - text: Check schema version {version_id} of {table} for errors.
        slots:
          version_id: query.version_id
          table: path.table
      method: generated
      generated: '2026-10-02'
- target: $.paths['/schema/{table}/version'].get
  update:
    x-apievangelist-phrasing:
      intent: List a schema's version history
      effect: read
      questions:
      - Who published which schema versions, and when?
      - Can I see the full history of a table's schema?
      instructions:
      - text: List every schema version of {table}.
        slots:
          table: path.table
      - text: Show the publish history for the {table} schema.
        slots:
          table: path.table
      method: generated
      generated: '2026-10-02'