{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://vinculum.run/standard/entry.schema.json",
  "title": "Vinculum Standard v0.2 — Entry",
  "description": "The portable, canonical shape of a Vinculum entry — the universal concept of a structured decision, spec, finding, or work unit. This schema describes entries as they move across systems, not Vinculum-specific implementation details.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Universally unique identifier for this entry. This is the canonical cross-system reference (never expose the implementation-specific numeric id)."
    },
    "type": {
      "type": "string",
      "enum": [
        "decision",
        "spec",
        "note",
        "question",
        "implementation",
        "blocker",
        "checkpoint",
        "handoff",
        "review_request",
        "review",
        "thought",
        "recon",
        "metric"
      ],
      "description": "Entry classification. Indicates the entry's role in the workflow: strategic decisions, specifications, findings, questions awaiting answers, work done, blockers, progress markers, handoffs between workers, review requests, reviewer verdicts, internal reasoning captures, reconnaissance/investigation, or metrics/measurements."
    },
    "content": {
      "type": "string",
      "description": "The entry's body — markdown or plain text. This is the primary content that communicates the decision, spec, finding, or question."
    },
    "author": {
      "type": "string",
      "description": "Author identifier — person, role, or system name that authored this entry."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp when this entry was created in UTC."
    },
    "links": {
      "type": "array",
      "description": "Relationships to other entries (optional but SHOULD be populated when relevant). Each link captures a directional relationship.",
      "items": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the target entry."
          },
          "relation": {
            "type": "string",
            "enum": [
              "supersedes",
              "references",
              "blocks",
              "implements",
              "contradicts"
            ],
            "description": "Type of relationship to the target entry. supersedes = this entry replaces another; references = cites for context; blocks = prevents progress on; implements = fulfills or carries out; contradicts = disagrees with or invalidates."
          }
        },
        "required": ["to", "relation"],
        "additionalProperties": false
      }
    },
    "metadata": {
      "type": "object",
      "description": "Freeform metadata object for application-specific extensions and attributes. Common keys may include target (for routing/ownership), replies_to (for threaded replies), and entry-type-specific fields.",
      "additionalProperties": true
    },
    "tags": {
      "type": "array",
      "description": "Optional semantic tags for classification and discovery. Implementation-specific extension field.",
      "items": {
        "type": "string"
      }
    },
    "branch": {
      "type": "string",
      "description": "Optional branch/area identifier for organizational grouping. Implementation-specific extension field."
    },
    "thread_slug": {
      "type": "string",
      "description": "Optional thread identifier for grouping related entries. Implementation-specific extension field."
    }
  },
  "required": ["id", "type", "content", "author", "created_at"],
  "additionalProperties": false
}