#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
#  SPDX-License-Identifier: Apache-2.0
$schema: "http://json-schema.org/draft-07/schema#"
$id: "mas-lab/dataset/v1"
title: "mas-lab Dataset manifest (v1)"
description: >
  Dataset items use the Run Input Envelope (inputs + expectations).
  See run-input.schema.yaml for item shape. Loaders still accept
  pre-envelope items (prompt/query, top-level ground_truth, a bare YAML
  list) and emit a deprecation warning; those shapes are marked
  deprecated below. Migration:
  https://ioc-project.github.io/mas-lab/manifests/dataset-migration/

type: object
required: [apiVersion, kind, metadata, spec]
additionalProperties: false

properties:
  apiVersion:
    type: string
    const: "lab/v1"

  kind:
    type: string
    const: "Dataset"

  metadata:
    type: object
    required: [name]
    additionalProperties: false
    properties:
      name:
        type: string
        minLength: 1
      display_name:
        type: string
      version:
        type: string
        default: "1.0"
      description:
        type: string
      tags:
        type: array
        items:
          type: string

  spec:
    type: object
    additionalProperties: false
    anyOf:
      - required: [items]
      - required: [path]
      - required: [source]
    properties:
      app:
        description: >
          App this dataset is bound to (omit for general-purpose datasets).
          Package-dependency form: `[library:]name` (any version) or
          `[library:]name@<tag-or-range>` (`my-app@v1`, `my-app@>=v1,<v3`,
          `my-app@^v1`). Dataset versions are independent of the app;
          this field is the compatible app range.
        oneOf:
          - type: string
            minLength: 1
          - type: object
            additionalProperties: false
            required: [name]
            properties:
              name:
                type: string
                minLength: 1
              library:
                type: string
              version:
                type: string
                description: "Version tag or range (v1, >=v1,<v3, ^v1)."
      items:
        type: array
        minItems: 1
        items:
          type: object
          required: [id]
          additionalProperties: true
          description: >
            Canonical item is id + inputs (+ expectations). Legacy
            prompt/query fields still validate here so existing files
            check; they are deprecated and the loader warns.
          properties:
            id:
              oneOf:
                - type: string
                - type: integer
            inputs:
              $ref: "urn:mas-lab:run-input:v1#/properties/inputs"
            expectations:
              $ref: "urn:mas-lab:run-input:v1#/properties/expectations"
            prompt:
              deprecated: true
              description: >
                DEPRECATED. Use inputs.user (string). Loader warns.
                See https://ioc-project.github.io/mas-lab/manifests/dataset-migration/
            query:
              deprecated: true
              description: DEPRECATED. Use inputs.user.
            question:
              deprecated: true
              description: DEPRECATED. Use inputs.user.
            text:
              deprecated: true
              description: DEPRECATED. Use inputs.user.
            input:
              deprecated: true
              description: DEPRECATED. Use inputs.user.
            user:
              deprecated: true
              description: >
                DEPRECATED at item top-level. Use inputs.user.
            turns:
              deprecated: true
              description: >
                DEPRECATED. Split into inputs.user / inputs.hitl strings.
            expected_answer:
              deprecated: true
              description: DEPRECATED. Use expectations.ground_truth.
            ground_truth:
              deprecated: true
              description: >
                DEPRECATED at item top-level. Use expectations.ground_truth.
            correct_action:
              deprecated: true
              description: >
                DEPRECATED at item top-level. Use expectations.details.correct_action.
            category:
              type: string
            group:
              type: string
            type:
              type: string
            tags:
              type: array
              items:
                type: string
            metadata:
              type: object
              additionalProperties: true

      path:
        type: string
        description: >
          Sidecar items file relative to this Dataset YAML (YAML, JSONL,
          or CSV). Loaded when spec.items and spec.source are empty.
          JSON Dataset files are not supported.
      source:
        description: >
          External corpus pointer (MMLU-Pro, jsonl, pickle). The Dataset YAML
          is the mapping; rows are not copied into spec.items. Loader
          materializes source into envelope items at Dataset.from_yaml.
        type: object
        additionalProperties: false
        required: [kind]
        properties:
          kind:
            type: string
            enum: [huggingface, jsonl, csv, glob, pickle]
          id:
            type: string
            description: HuggingFace dataset id (e.g. TIGER-Lab/MMLU-Pro).
          split:
            type: string
          path:
            type: string
            description: Local file or glob, relative to the dataset folder.
          map:
            type: object
            additionalProperties: true
            description: >
              Map source columns onto envelope fields
              (id, inputs.user, expectations.ground_truth, ...).
              A string is a column name or a ``{column}`` template.
              ``{options_text}`` is synthesized from an ``options`` list.
          config:
            type: string
            description: HuggingFace subset / config name.
          name:
            type: string
            description: Alias for config.
          limit:
            type: integer
            minimum: 1
            description: Cap materialized items (smoke / CI).
      format:
        type: string
        enum: [yaml, jsonl, csv]
        default: yaml
      schemas:
        type: object
        description: >
          Optional JSON Schemas for the free-form parts of each resolved item,
          keyed by dotted envelope path (same vocabulary as source.map):
          expectations.details[.key...] or inputs.tool_fixtures.by_tool.<tool|*>[.key...].
          A tool key checks the payload that tool receives (by_tool[tool], else by_tool["*"]).
          Value: inline schema, a path, or {ref: path} (catalog refs allowed).
          Parts without a schema are not checked.
        propertyNames:
          pattern: '^(expectations\.details|inputs\.tool_fixtures\.by_tool\.[^.]+)(\.[^.]+)*$'
        additionalProperties:
          anyOf:
            - type: string
            - type: object
      groups:
        type: array
        items:
          type: object
          required: [id]
          additionalProperties: false
          properties:
            id:
              type: string
            description:
              type: string
            count:
              type: integer