# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Web of Science™ Journals Categories API
  version: 1.0.0
extends: openapi/clarivate-categories-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: Search JCR subject categories
      effect: read
      questions:
      - How do I browse the Journal Citation Reports subject categories?
      - Can I filter JCR categories by edition and year?
      instructions:
      - text: List the JCR subject categories.
      - text: Search JCR categories for {q}.
        slots:
          q: query.q
      - text: List categories in edition {edition} for JCR year {jcrYear}.
        slots:
          edition: query.edition
          jcrYear: query.jcrYear
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a JCR subject category profile
      effect: read
      questions:
      - What does the profile of a JCR subject category include?
      - Where can I find links to a category's yearly reports?
      instructions:
      - text: Get JCR category {id}.
        slots:
          id: path.id
      - text: Show the profile and yearly report links for category {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{id}/reports/year/{year}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category's metrics for a JCR year
      effect: read
      questions:
      - What was the median and aggregate impact factor of a subject category in a given year?
      - How many journals and articles did a JCR category have in a year?
      instructions:
      - text: Get metrics for category {id} in {year}.
        slots:
          id: path.id
          year: path.year
      - text: Show the {year} aggregate impact factor and total cites for category {id}.
        slots:
          year: path.year
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{id}/cited/year/{year}'].get
  update:
    x-apievangelist-phrasing:
      intent: List journals citing a category in a year
      effect: read
      questions:
      - Which journals cite the journals in a subject category the most?
      - Can I page through the journals that cite a category for a JCR year?
      instructions:
      - text: List journals that cite category {id} in {year}.
        slots:
          id: path.id
          year: path.year
      - text: Show page {page} of journals citing category {id} during {year}.
        slots:
          page: query.page
          id: path.id
          year: path.year
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{id}/citing/year/{year}'].get
  update:
    x-apievangelist-phrasing:
      intent: List journals a category cites in a year
      effect: read
      questions:
      - Which journals do the journals in a category cite most often?
      - What journals were cited by a subject category in a given JCR year?
      instructions:
      - text: List journals cited by category {id} in {year}.
        slots:
          id: path.id
          year: path.year
      - text: Show the top {limit} journals that category {id} cited in {year}.
        slots:
          limit: query.limit
          id: path.id
          year: path.year
      method: generated
      generated: '2026-10-01'