openapi: 3.1.0
info:
  title: Yo Shabdakosh Static API
  version: "1.0.0"
  summary: Static JSON API for the Yo Shabdakosh Nepali dictionary dataset.
  description: |
    Yo Shabdakosh is served as static JSON files. There is no backend search
    server. Clients should fetch `letters.json`, then the relevant
    `words-by-letter/{letter}.json`, then the referenced chunk file.
  license:
    name: MIT for project code; dictionary data rights require review
    url: ./DATA-LICENSE-NOTICE.md
servers:
  - url: https://shubhamnpk.github.io/yoshabdakosh/api/v1
    description: Published GitHub Pages API
  - url: ./api/v1
    description: Relative GitHub Pages or local static server path
  - url: http://localhost:8000/api/v1
    description: Local development
paths:
  /metadata.json:
    get:
      summary: API metadata and dataset stats
      operationId: getMetadata
      responses:
        "200":
          description: Metadata response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Metadata"
  /manifest.json:
    get:
      summary: Chunk manifest
      operationId: getManifest
      responses:
        "200":
          description: List of chunk files
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Manifest"
  /letters.json:
    get:
      summary: First-letter index
      operationId: getLetters
      responses:
        "200":
          description: Letter index with paths to per-letter word indexes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LettersResponse"
  /words-by-letter/{letter}.json:
    get:
      summary: Word index for a starting letter
      operationId: getWordsByLetter
      parameters:
        - name: letter
          in: path
          required: true
          description: UTF-8 encoded Nepali starting letter, for example `अ`.
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Word-to-chunk lookup list for the letter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WordsByLetterResponse"
        "404":
          description: No generated file exists for this letter
  /chunks/{chunk}.json:
    get:
      summary: Dictionary entries chunk
      operationId: getChunk
      parameters:
        - name: chunk
          in: path
          required: true
          description: Zero-padded chunk id, for example `0000`.
          schema:
            type: string
            pattern: "^[0-9]{4}$"
      responses:
        "200":
          description: Chunk of dictionary entries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChunkResponse"
        "404":
          description: No generated chunk exists for this id
  /sample.json:
    get:
      summary: Sample dictionary entry
      operationId: getSample
      responses:
        "200":
          description: Sample entry response
          content:
            application/json:
              schema:
                type: object
                required: [apiVersion, generatedAt, entry]
                properties:
                  apiVersion:
                    type: string
                  generatedAt:
                    type: string
                    format: date-time
                  entry:
                    $ref: "#/components/schemas/Entry"
components:
  schemas:
    Metadata:
      type: object
      required: [apiVersion, name, description, generatedAt, endpoints, stats]
      properties:
        apiVersion:
          type: string
        name:
          type: string
        description:
          type: string
        generatedAt:
          type: string
          format: date-time
        license:
          type: string
        sourceDataset:
          type: string
        endpoints:
          type: object
          additionalProperties:
            type: string
        stats:
          $ref: "#/components/schemas/Stats"
        notes:
          type: array
          items:
            type: string
    Stats:
      type: object
      required: [entries, definitionBlocks, senses, etymologies]
      properties:
        entries:
          type: integer
          example: 123371
        definitionBlocks:
          type: integer
          example: 128343
        senses:
          type: integer
          example: 179142
        etymologies:
          type: integer
          example: 78313
        missingGrammarLabels:
          type: integer
          example: 429
        blankGrammarLabels:
          type: integer
          example: 0
    Manifest:
      type: object
      required: [apiVersion, generatedAt, chunkSize, chunkCount, chunks]
      properties:
        apiVersion:
          type: string
        generatedAt:
          type: string
          format: date-time
        chunkSize:
          type: integer
          example: 1000
        chunkCount:
          type: integer
          example: 124
        chunks:
          type: array
          items:
            $ref: "#/components/schemas/ChunkInfo"
    ChunkInfo:
      type: object
      required: [chunk, path, count, start, end, firstWord, lastWord]
      properties:
        chunk:
          type: integer
        path:
          type: string
        count:
          type: integer
        start:
          type: integer
        end:
          type: integer
        firstWord:
          type: string
        lastWord:
          type: string
    LettersResponse:
      type: object
      required: [apiVersion, generatedAt, count, letters]
      properties:
        apiVersion:
          type: string
        generatedAt:
          type: string
          format: date-time
        count:
          type: integer
        letters:
          type: array
          items:
            $ref: "#/components/schemas/LetterInfo"
    LetterInfo:
      type: object
      required: [letter, path, count, startIndex, endIndex, startChunk, endChunk, firstWord, lastWord]
      properties:
        letter:
          type: string
          example: अ
        path:
          type: string
          example: words-by-letter/अ.json
        count:
          type: integer
        startIndex:
          type: integer
        endIndex:
          type: integer
        startChunk:
          type: integer
        endChunk:
          type: integer
        firstWord:
          type: string
        lastWord:
          type: string
    WordsByLetterResponse:
      type: object
      required: [apiVersion, generatedAt, letter, count, firstWord, lastWord, words]
      properties:
        apiVersion:
          type: string
        generatedAt:
          type: string
          format: date-time
        letter:
          type: string
        count:
          type: integer
        firstWord:
          type: string
        lastWord:
          type: string
        words:
          type: array
          items:
            $ref: "#/components/schemas/WordIndexItem"
    WordIndexItem:
      type: object
      required: [word, index, chunk, path]
      properties:
        word:
          type: string
          example: अ
        index:
          type: integer
          example: 0
        chunk:
          type: integer
          example: 0
        path:
          type: string
          example: chunks/0000.json
    ChunkResponse:
      type: object
      required: [apiVersion, chunk, count, firstWord, lastWord, entries]
      properties:
        apiVersion:
          type: string
        chunk:
          type: integer
        count:
          type: integer
        firstWord:
          type: string
        lastWord:
          type: string
        entries:
          type: array
          items:
            $ref: "#/components/schemas/Entry"
    Entry:
      type: object
      required: [word, definitions]
      properties:
        word:
          type: string
          example: अ
        definitions:
          type: array
          items:
            $ref: "#/components/schemas/Definition"
    Definition:
      type: object
      required: [senses]
      properties:
        grammar:
          type: string
          example: ना.
        etymology:
          type: string
          example: "[सं.]"
        senses:
          type: array
          items:
            type: string