/api/valueset:
  get:
    tags: [ValueSets]
    summary: List lib value sets
    description: List all library/system value sets from JSON files with item counts. Returns an object where keys are value set names and values are item counts.
    security:
      - bearerAuth: []
    parameters:
      - name: search
        in: query
        schema:
          type: string
        description: Optional search term to filter value set names
    responses:
      '200':
        description: List of lib value sets with item counts
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  example: success
                data:
                  type: object
                  additionalProperties:
                    type: integer
                    description: Number of items in each value set
                  example:
                    sex: 3
                    marital_status: 6
                    order_status: 6

/api/valueset/{key}:
  get:
    tags: [ValueSets]
    summary: Get lib value set by key
    description: |
      Get a specific library/system value set from JSON files.

      **Available value set keys:**
      - `activity_result` - Activity Result
      - `additive` - Additive
      - `adt_event` - ADT Event
      - `area_class` - Area Class
      - `body_site` - Body Site
      - `collection_method` - Collection Method
      - `container_cap_color` - Container Cap Color
      - `container_class` - Container Class
      - `container_size` - Container Size
      - `country` - Country
      - `death_indicator` - Death Indicator
      - `did_type` - DID Type
      - `enable_disable` - Enable/Disable
      - `entity_type` - Entity Type
      - `ethnic` - Ethnic
      - `fasting_status` - Fasting Status
      - `formula_language` - Formula Language
      - `generate_by` - Generate By
      - `identifier_type` - Identifier Type
      - `location_type` - Location Type
      - `marital_status` - Marital Status
      - `math_sign` - Math Sign
      - `numeric_ref_type` - Numeric Reference Type
      - `operation` - Operation (CRUD)
      - `order_priority` - Order Priority
      - `order_status` - Order Status
      - `race` - Race (Ethnicity)
      - `range_type` - Range Type
      - `reference_type` - Reference Type
      - `religion` - Religion
      - `requested_entity` - Requested Entity
      - `result_type` - Result Type
      - `result_unit` - Result Unit
      - `sex` - Sex
      - `site_class` - Site Class
      - `site_type` - Site Type
      - `specimen_activity` - Specimen Activity
      - `specimen_condition` - Specimen Condition
      - `specimen_role` - Specimen Role
      - `specimen_status` - Specimen Status
      - `specimen_type` - Specimen Type
      - `test_activity` - Test Activity
      - `test_type` - Test Type
      - `text_ref_type` - Text Reference Type
      - `unit` - Unit
      - `v_category` - VCategory
      - `ws_type` - Workstation Type
    security:
      - bearerAuth: []
    parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
          enum: [activity_result, additive, adt_event, area_class, body_site, collection_method, container_cap_color, container_class, container_size, country, death_indicator, did_type, enable_disable, entity_type, ethnic, fasting_status, formula_language, generate_by, identifier_type, location_type, marital_status, math_sign, numeric_ref_type, operation, order_priority, order_status, race, range_type, reference_type, religion, requested_entity, result_type, result_unit, sex, site_class, site_type, specimen_activity, specimen_condition, specimen_role, specimen_status, specimen_type, test_activity, test_type, text_ref_type, unit, v_category, ws_type]
        description: Value set key name
    responses:
      '200':
        description: Lib value set details
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                data:
                  type: array
                  items:
                    $ref: '../components/schemas/valuesets.yaml#/ValueSetLibItem'

/api/valueset/refresh:
  post:
    tags: [ValueSets]
    summary: Refresh lib ValueSet cache
    description: Clear and reload the library/system ValueSet cache from JSON files. Call this after modifying JSON files in app/Libraries/Data/.
    security:
      - bearerAuth: []
    responses:
      '200':
        description: Lib ValueSet cache refreshed
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  example: success
                message:
                  type: string
                  example: Cache cleared

/api/valueset/user/items:
  get:
    tags: [ValueSets]
    summary: List user value set items
    description: List value set items from database (user-defined)
    security:
      - bearerAuth: []
    parameters:
      - name: VSetID
        in: query
        schema:
          type: integer
        description: Filter by ValueSet ID
      - name: search
        in: query
        schema:
          type: string
        description: Search term to filter by VValue, VDesc, or VSName
      - name: param
        in: query
        schema:
          type: string
        description: Alternative search parameter (alias for search)
    responses:
      '200':
        description: List of user value set items
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                data:
                  type: array
                  items:
                    $ref: '../components/schemas/valuesets.yaml#/ValueSetItem'

  post:
    tags: [ValueSets]
    summary: Create user value set item
    description: Create value set item in database (user-defined)
    security:
      - bearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - VSetID
            properties:
              SiteID:
                type: integer
                description: Site reference (default 1)
              VSetID:
                type: integer
                description: Reference to value set definition (required)
              VOrder:
                type: integer
                description: Display order (default 0)
              VValue:
                type: string
                description: The value code
              VDesc:
                type: string
                description: The display description/label
    responses:
      '201':
        description: User value set item created
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                message:
                  type: string
                data:
                  $ref: '../components/schemas/valuesets.yaml#/ValueSetItem'

/api/valueset/user/items/{id}:
  get:
    tags: [ValueSets]
    summary: Get user value set item by ID
    description: Get value set item from database (user-defined)
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      '200':
        description: User value set item details
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                data:
                  $ref: '../components/schemas/valuesets.yaml#/ValueSetItem'

  put:
    tags: [ValueSets]
    summary: Update user value set item
    description: Update value set item in database (user-defined)
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              SiteID:
                type: integer
                description: Site reference
              VSetID:
                type: integer
                description: Reference to value set definition
              VOrder:
                type: integer
                description: Display order
              VValue:
                type: string
                description: The value code
              VDesc:
                type: string
                description: The display description/label
    responses:
      '200':
        description: User value set item updated
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                message:
                  type: string
                data:
                  $ref: '../components/schemas/valuesets.yaml#/ValueSetItem'

  delete:
    tags: [ValueSets]
    summary: Delete user value set item
    description: Delete value set item from database (user-defined)
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      '200':
        description: User value set item deleted
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                message:
                  type: string

/api/valueset/user/def:
  get:
    tags: [ValueSets]
    summary: List user value set definitions
    description: List value set definitions from database (user-defined)
    security:
      - bearerAuth: []
    parameters:
      - name: search
        in: query
        schema:
          type: string
        description: Optional search term to filter definitions
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number for pagination
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
        description: Number of items per page
    responses:
      '200':
        description: List of user value set definitions
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                data:
                  type: array
                  items:
                    $ref: '../components/schemas/valuesets.yaml#/ValueSetDef'
                meta:
                  type: object
                  properties:
                    total:
                      type: integer
                    page:
                      type: integer
                    limit:
                      type: integer

  post:
    tags: [ValueSets]
    summary: Create user value set definition
    description: Create value set definition in database (user-defined)
    security:
      - bearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              SiteID:
                type: integer
                description: Site reference (default 1)
              VSName:
                type: string
                description: Value set name
              VSDesc:
                type: string
                description: Value set description
    responses:
      '201':
        description: User value set definition created
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                message:
                  type: string
                data:
                  $ref: '../components/schemas/valuesets.yaml#/ValueSetDef'

/api/valueset/user/def/{id}:
  get:
    tags: [ValueSets]
    summary: Get user value set definition by ID
    description: Get value set definition from database (user-defined)
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      '200':
        description: User value set definition details
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                data:
                  $ref: '../components/schemas/valuesets.yaml#/ValueSetDef'

  put:
    tags: [ValueSets]
    summary: Update user value set definition
    description: Update value set definition in database (user-defined)
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              SiteID:
                type: integer
                description: Site reference
              VSName:
                type: string
                description: Value set name
              VSDesc:
                type: string
                description: Value set description
    responses:
      '200':
        description: User value set definition updated
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                message:
                  type: string
                data:
                  $ref: '../components/schemas/valuesets.yaml#/ValueSetDef'

  delete:
    tags: [ValueSets]
    summary: Delete user value set definition
    description: Delete value set definition from database (user-defined)
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      '200':
        description: User value set definition deleted
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                message:
                  type: string