{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/nirvanahq-com/json-schema/nirvanahq-com-mcp-search-result-response-schema.json",
  "title": "McpSearchResultResponse",
  "description": "The MCP search result (SEARCH_QUERY_GRAMMAR.md §12.8), returned with profile=mcp: groups nest their tasks. A project or reference-list group's `header` is that container, a person group's is the person, and any other group's is null.\n",
  "x-generated": "2026-11-19",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nirvanahq-com-openapi.yaml#/components/schemas/McpSearchResultResponse",
  "type": "object",
  "required": [
    "ok",
    "grammar_version",
    "ordering",
    "groups"
  ],
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "grammar_version": {
      "type": "integer"
    },
    "query": {
      "type": "string"
    },
    "canonical_query": {
      "type": [
        "string",
        "null"
      ],
      "description": "Null when the query uses reserved syntax (unsupported_syntax hint)."
    },
    "view": {
      "type": [
        "string",
        "null"
      ],
      "description": "The view requested by name; null for a q request."
    },
    "filters": {
      "type": "string",
      "description": "The structured filters as terms, echoed apart from the query. Present only when some were passed."
    },
    "today": {
      "type": "string",
      "format": "date"
    },
    "timezone": {
      "type": "string"
    },
    "scope": {
      "$ref": "#/$defs/McpScope"
    },
    "total": {
      "type": "integer"
    },
    "returned": {
      "type": "integer"
    },
    "has_more": {
      "type": "boolean"
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Null on the last page."
    },
    "ordering": {
      "type": "string"
    },
    "hints": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchHint"
      }
    },
    "groups": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "continued": {
            "type": "boolean",
            "description": "The group began on an earlier page."
          },
          "continues": {
            "type": "boolean",
            "description": "The group goes on past this page."
          },
          "header": {
            "oneOf": [
              {
                "$ref": "#/$defs/McpTask"
              },
              {
                "$ref": "#/$defs/McpPersonHeader"
              },
              {
                "type": "null"
              }
            ]
          },
          "tasks": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/McpTask"
            }
          }
        }
      }
    }
  },
  "$defs": {
    "McpPersonHeader": {
      "type": "object",
      "description": "The header of a person group (Waiting by person).",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "person"
          ]
        },
        "name": {
          "type": "string"
        }
      }
    },
    "McpScope": {
      "type": "object",
      "properties": {
        "area": {
          "type": "string"
        },
        "areamode": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "inclusive",
            "exclusive",
            null
          ]
        }
      }
    },
    "McpTask": {
      "type": "object",
      "description": "One task in the MCP profile (§12.8): GTD words, ISO dates, effective tags. A project or reference list used as a group `header` has the same fields, plus `status` and `sequencing` for a project.\n",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "task",
            "project",
            "reference_list",
            "reference_item"
          ]
        },
        "name": {
          "type": "string"
        },
        "list": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "inbox",
            "next",
            "waiting",
            "scheduled",
            "someday",
            "later",
            "recurring",
            "reference",
            "done",
            "trash",
            null
          ],
          "description": "Effective list; null for a project row (its place is `status`)."
        },
        "status": {
          "type": "string",
          "description": "Projects only."
        },
        "sequencing": {
          "type": "string",
          "enum": [
            "sequential",
            "parallel"
          ],
          "description": "Projects only."
        },
        "done": {
          "type": "boolean"
        },
        "cancelled": {
          "type": "boolean"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "cancelled_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "updated": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Last activity, an instant in the user's zone."
        },
        "age_days": {
          "type": [
            "integer",
            "null"
          ]
        },
        "reminder": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "A reminder still ahead; null otherwise."
        },
        "has_attachments": {
          "type": "boolean"
        },
        "due": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "start": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "The pending start date; null once it has arrived."
        },
        "overdue": {
          "type": "boolean"
        },
        "in_focus": {
          "type": "boolean"
        },
        "focus_reason": {
          "type": [
            "string",
            "null"
          ]
        },
        "actionable": {
          "type": "boolean",
          "description": "Tasks only. Whether it is a next step (§5.5)."
        },
        "areas": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "contexts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "people": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "inherited": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Tags that come from the parent project."
        },
        "waiting_for": {
          "type": [
            "string",
            "null"
          ]
        },
        "project": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "status": {
              "type": "string"
            }
          }
        },
        "spawned_from": {
          "type": "object",
          "description": "Occurrences of a repeating task only. `name` is null when the template is no longer loaded.",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "occurrence_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "Occurrences only."
        },
        "repeat": {
          "type": "object",
          "description": "Repeating templates only.",
          "properties": {
            "summary": {
              "type": [
                "string",
                "null"
              ],
              "description": "The rule in words, e.g. \"Every 2 weeks on Monday\"; null when it cannot be read."
            },
            "next": {
              "type": [
                "string",
                "null"
              ],
              "format": "date"
            }
          }
        },
        "energy": {
          "type": [
            "string",
            "null"
          ]
        },
        "time_minutes": {
          "type": [
            "integer",
            "null"
          ]
        },
        "note": {
          "type": "object",
          "properties": {
            "present": {
              "type": "boolean"
            },
            "length": {
              "type": "integer"
            },
            "text": {
              "type": "string",
              "description": "Only with include_notes=true."
            }
          }
        },
        "positions": {
          "type": "object",
          "description": "Only with include_positions=true.",
          "properties": {
            "group": {
              "type": "string"
            },
            "group_index": {
              "type": "integer"
            },
            "seq": {
              "type": "integer"
            },
            "seqp": {
              "type": "integer"
            },
            "focus_position": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Null outside Focus."
            },
            "parentid": {
              "type": "string"
            },
            "parent_type": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Null for a task with no parent."
            },
            "parent_seq": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Null for a task with no parent."
            },
            "effective_state": {
              "type": "integer"
            }
          }
        }
      }
    },
    "SearchHint": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "hidden_inactive",
            "unknown_value",
            "unsupported_syntax",
            "layout_ignored",
            "version_newer",
            "truncated",
            "done_window"
          ]
        },
        "count": {
          "type": "integer"
        },
        "text": {
          "type": "string"
        }
      }
    }
  }
}