Issue

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/grepr/json-schema/grepr-issue-schema.json",
  "title": "Issue",
  "description": "One durable problem or task on the organization's issue board.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/grepr-openapi.json#/components/schemas/Issue",
  "properties": {
    "closedAt": {
      "description": "When it closed, or null while open.",
      "format": "date-time",
      "type": "string"
    },
    "confidence": {
      "description": "How sure the reporter is that the problem is real.",
      "enum": [
        "CONFIRMED",
        "LIKELY",
        "UNVERIFIED"
      ],
      "type": "string"
    },
    "createdAt": {
      "description": "When it was filed.",
      "format": "date-time",
      "type": "string"
    },
    "description": {
      "description": "The current understanding, in markdown, kept current rather than appended to.",
      "type": "string"
    },
    "duplicateOf": {
      "description": "The surviving issue, set exactly when resolved as `DUPLICATE`; null in a response when the reader can't see the survivor.",
      "type": "string"
    },
    "duplicateOfHidden": {
      "description": "True in a response whose reader can't see the surviving issue.",
      "type": "boolean"
    },
    "entities": {
      "additionalProperties": {
        "description": "The `entity:*` tags it concerns, the same vocabulary as memory tags, keys in lower case, sorted by key.",
        "type": "string"
      },
      "description": "The `entity:*` tags it concerns, the same vocabulary as memory tags, keys in lower case, sorted by key.",
      "type": "object"
    },
    "evidence": {
      "description": "Things a person can open to check the claim.",
      "items": {
        "$ref": "#/$defs/IssueEvidence"
      },
      "type": "array"
    },
    "expiresAt": {
      "description": "When the issue stops applying and closes as `EXPIRED`, or null.",
      "format": "date-time",
      "type": "string"
    },
    "fingerprint": {
      "description": "An optional free-form key for exact-match search, or null.",
      "type": "string"
    },
    "firstSeenAt": {
      "description": "The first sighting, or null before any.",
      "format": "date-time",
      "type": "string"
    },
    "id": {
      "description": "The issue id.",
      "type": "string"
    },
    "labels": {
      "description": "Categories, such as `cost`, sorted.",
      "items": {
        "description": "Categories, such as `cost`, sorted.",
        "type": "string"
      },
      "type": "array"
    },
    "lastSeenAt": {
      "description": "The latest sighting, or when it was filed.",
      "format": "date-time",
      "type": "string"
    },
    "links": {
      "description": "Related pipelines, investigations, memories, suggestions and external tickets.",
      "items": {
        "$ref": "#/$defs/IssueLink"
      },
      "type": "array"
    },
    "locks": {
      "$ref": "#/$defs/IssueLocks"
    },
    "nextStep": {
      "description": "The concrete next action and who it waits on, or null.",
      "type": "string"
    },
    "number": {
      "description": "The short per-organization handle, shown as `#142`.",
      "format": "int32",
      "type": "integer"
    },
    "occurrenceCount": {
      "description": "How many investigations sighted it.",
      "format": "int32",
      "type": "integer"
    },
    "priority": {
      "description": "How soon someone should act.",
      "enum": [
        "P0",
        "P1",
        "P2",
        "P3"
      ],
      "type": "string"
    },
    "regressed": {
      "description": "Whether it reopened on a new sighting after being fixed; cleared on its next close.",
      "type": "boolean"
    },
    "reporter": {
      "$ref": "#/$defs/IssueActor"
    },
    "resolution": {
      "description": "Why it closed; set exactly when `state` is `CLOSED`.",
      "enum": [
        "FIXED",
        "DUPLICATE",
        "NOT_A_PROBLEM",
        "IGNORED",
        "OBSOLETE",
        "EXPIRED"
      ],
      "type": "string"
    },
    "revisitAt": {
      "description": "When someone should check back, or null. Then a Monitoring issue's watcher is started on it, or, with no watcher, it goes back to `READY`.",
      "format": "date-time",
      "type": "string"
    },
    "state": {
      "description": "Where the issue is in its lifecycle.",
      "enum": [
        "TRIAGE",
        "READY",
        "IN_PROGRESS",
        "WAITING",
        "MONITORING",
        "CLOSED"
      ],
      "type": "string"
    },
    "stateChangedAt": {
      "description": "When the state last changed.",
      "format": "date-time",
      "type": "string"
    },
    "teamIds": {
      "description": "The teams that may see the issue, sorted.",
      "items": {
        "description": "The teams that may see the issue, sorted.",
        "type": "string"
      },
      "type": "array"
    },
    "title": {
      "description": "One line naming the problem.",
      "type": "string"
    },
    "updatedAt": {
      "description": "When it last changed.",
      "format": "date-time",
      "type": "string"
    },
    "version": {
      "description": "Bumped by every change to a field, the state, an assignment, a lock or the teams.",
      "format": "int32",
      "type": "integer"
    },
    "watchedBy": {
      "description": "The agent watching it in `MONITORING`: the one that moved it there, started on it again when a sighting comes in or its revisit time passes. Null outside Monitoring.",
      "type": "string"
    }
  },
  "type": "object",
  "$defs": {
    "IssueActor": {
      "description": "Who made a change to an issue. An agent is named by its own id and the investigation it acted in, never by the service account it authenticated as, since several agents may share one.",
      "properties": {
        "agentId": {
          "description": "The agent, for an agent actor; null otherwise.",
          "type": "string"
        },
        "id": {
          "description": "The person's user id, the agent's execution principal (its service account's token subject), or `system` for the server.",
          "type": "string"
        },
        "investigationId": {
          "description": "The investigation the agent acted in, for an agent actor; null otherwise.",
          "type": "string"
        },
        "kind": {
          "description": "A person, an agent, or the server.",
          "enum": [
            "PERSON",
            "AGENT",
            "SYSTEM"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "IssueEvidence": {
      "description": "Something a person can open to check an issue's claim.",
      "properties": {
        "from": {
          "description": "Start of a log query's time range, or null.",
          "format": "date-time",
          "type": "string"
        },
        "kind": {
          "description": "What the evidence points at.",
          "enum": [
            "LOG_QUERY",
            "EVENT",
            "URL"
          ],
          "type": "string"
        },
        "label": {
          "description": "A short description of what it shows, or null.",
          "maxLength": 200,
          "minLength": 0,
          "type": "string"
        },
        "target": {
          "description": "The Grepr log query for LOG_QUERY, the event id for EVENT, or an http(s) URL for URL.",
          "maxLength": 4096,
          "minLength": 0,
          "type": "string"
        },
        "to": {
          "description": "End of a log query's time range, or null.",
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "kind",
        "target"
      ],
      "type": "object"
    },
    "IssueFieldLock": {
      "description": "Who locked a field and when, so the UI can say \"set by Jad on Oct 3; agents can't change this\".",
      "properties": {
        "setAt": {
          "description": "When it was locked.",
          "format": "date-time",
          "type": "string"
        },
        "setBy": {
          "description": "The user id of the person whose write locked it.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "IssueLabelLock": {
      "description": "A person's lock on one label: agents may not remove a label a person added, or add back one a person removed.",
      "properties": {
        "setAt": {
          "description": "When it was locked.",
          "format": "date-time",
          "type": "string"
        },
        "setBy": {
          "description": "The user id of the person whose write locked it.",
          "type": "string"
        },
        "state": {
          "description": "Whether the person added or removed the label.",
          "enum": [
            "PRESENT",
            "ABSENT"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "IssueLink": {
      "description": "A typed reference from an issue to something related. A link grants nothing: the linked page applies its own access checks. A link to an issue the reader can't see comes back with only its kind and `hidden`, so an issue reveals nothing about another team's.",
      "properties": {
        "hidden": {
          "description": "True for a link to an issue the reader can't see. Set only in responses.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "kind": {
          "description": "What the link points at.",
          "enum": [
            "PIPELINE",
            "INVESTIGATION",
            "MEMORY",
            "AGENT_SUGGESTION",
            "EXTERNAL",
            "ISSUE"
          ],
          "type": "string"
        },
        "label": {
          "description": "A short description, or null.",
          "maxLength": 200,
          "minLength": 0,
          "type": "string"
        },
        "target": {
          "description": "Null only for a hidden issue link in a response.",
          "maxLength": 4096,
          "minLength": 0,
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "kind"
      ],
      "type": "object"
    },
    "IssueLocks": {
      "description": "The fields and labels people have locked against agent changes. `state` never locks.",
      "properties": {
        "fields": {
          "additionalProperties": {
            "$ref": "#/$defs/IssueFieldLock"
          },
          "description": "The locked fields, each with who locked it and when.",
          "type": "object"
        },
        "labels": {
          "additionalProperties": {
            "$ref": "#/$defs/IssueLabelLock"
          },
          "description": "The locked labels, keyed by label.",
          "type": "object"
        }
      },
      "type": "object"
    }
  }
}