{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://graphenix.dev/schema/graphenix-format-1.0.0.json",
  "title": "Graphenix Format 1.0.0",
  "description": "JSON Schema for the Graphenix graph description format (version 1.0.0). Execution semantics are out of scope.",
  "type": "object",
  "required": ["formatVersion", "id", "graph"],
  "additionalProperties": false,
  "properties": {
    "formatVersion": {
      "type": "string",
      "description": "Semantic version of the graphenix-format used by this document (e.g. 1.0.0)."
    },
    "id": {
      "type": "string",
      "description": "Globally unique identifier for this graph within the system."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name for the graph."
    },
    "description": {
      "type": "string",
      "description": "Free-form description of the graph."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tags for classification, search, and filtering."
    },
    "graph": {
      "$ref": "#/$defs/Graph"
    },
    "types": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TypeDefinition"
      },
      "description": "Custom logical types referenced by nodes and ports."
    },
    "subgraphs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SubgraphDefinition"
      },
      "description": "Inlined reusable graphs."
    },
    "extensions": {
      "type": "object",
      "description": "Namespaced extension object. Engines that do not recognize an extension namespace must ignore it.",
      "additionalProperties": true
    },
    "metadata": {
      "type": "object",
      "description": "Optional document metadata. `graphEntry` and `graphResponse` align with worox-graph graph JSON contracts (I/O layers 01 and 08). Optional `catalogRequests` is planning-only (worox-graph). Other keys are allowed for tooling.",
      "additionalProperties": true,
      "properties": {
        "graphEntry": {
          "$ref": "#/$defs/GraphEntryContract"
        },
        "graphResponse": {
          "$ref": "#/$defs/GraphResponseContract"
        },
        "catalogRequests": {
          "$ref": "#/$defs/WoroxCatalogRequests"
        }
      }
    }
  },
  "$defs": {
    "Graph": {
      "type": "object",
      "required": ["nodes", "edges", "inputs", "outputs"],
      "additionalProperties": false,
      "properties": {
        "nodes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Node"
          }
        },
        "edges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Edge"
          }
        },
        "inputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/GraphInput"
          }
        },
        "outputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/GraphOutput"
          }
        },
        "metadata": {
          "type": "object",
          "description": "Arbitrary metadata not affecting execution semantics.",
          "additionalProperties": true
        }
      }
    },
    "Node": {
      "type": "object",
      "required": ["id", "kind"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier within the containing graph."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name for UIs and logs."
        },
        "kind": {
          "type": "string",
          "description": "Logical type of node determining how the executor interprets it (e.g. builtin:map, task:http-request, subgraph:graph:user-validation)."
        },
        "inputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PortDefinition"
          },
          "default": []
        },
        "outputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PortDefinition"
          },
          "default": []
        },
        "parameters": {
          "type": "object",
          "description": "Static configuration for the node. Interpretation is executor-specific based on kind.",
          "additionalProperties": true,
          "default": {}
        },
        "metadata": {
          "type": "object",
          "description": "Arbitrary metadata not affecting execution semantics (e.g. UI position). Worox-graph task nodes may use planning-only `catalogBinding` / `catalogRequest` (execution unchanged).",
          "additionalProperties": true,
          "properties": {
            "catalogBinding": {
              "$ref": "#/$defs/WoroxCatalogBinding"
            },
            "catalogRequest": {
              "$ref": "#/$defs/WoroxCatalogRequest"
            }
          }
        },
        "extensions": {
          "type": "object",
          "description": "Namespaced extension data.",
          "additionalProperties": true
        }
      }
    },
    "PortDefinition": {
      "type": "object",
      "required": ["id", "direction", "type"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier within the node."
        },
        "name": {
          "type": "string",
          "description": "Human-readable label."
        },
        "direction": {
          "type": "string",
          "enum": ["input", "output"],
          "description": "Direction of data flow."
        },
        "type": {
          "type": "string",
          "description": "Type identifier (built-in type or custom type id)."
        },
        "required": {
          "type": "boolean",
          "description": "Indicates if a value must be present for the node to execute.",
          "default": false
        },
        "default": {
          "description": "Default value when no incoming edge provides one. Must be compatible with the declared type.",
          "type": ["string", "number", "boolean", "array", "object", "null"]
        }
      }
    },
    "EdgeEndpoint": {
      "type": "object",
      "required": ["nodeId", "portId"],
      "additionalProperties": false,
      "properties": {
        "nodeId": {
          "type": "string",
          "description": "ID of the node."
        },
        "portId": {
          "type": "string",
          "description": "ID of the port on the referenced node."
        }
      }
    },
    "Edge": {
      "type": "object",
      "required": ["id", "from", "to"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier within the graph."
        },
        "from": {
          "$ref": "#/$defs/EdgeEndpoint",
          "description": "Source of the edge; must reference an existing node/output port."
        },
        "to": {
          "$ref": "#/$defs/EdgeEndpoint",
          "description": "Target of the edge; must reference an existing node/input port."
        },
        "metadata": {
          "type": "object",
          "description": "Metadata not affecting execution (e.g. edge label in UI).",
          "additionalProperties": true
        },
        "extensions": {
          "type": "object",
          "description": "Namespaced extension data.",
          "additionalProperties": true
        }
      }
    },
    "GraphInput": {
      "type": "object",
      "required": ["id", "type", "target"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier within the graph."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "type": {
          "type": "string",
          "description": "Logical type identifier for the external input."
        },
        "target": {
          "$ref": "#/$defs/EdgeEndpoint",
          "description": "Node and input port that consume this graph input."
        },
        "metadata": {
          "type": "object",
          "description": "Metadata not affecting execution.",
          "additionalProperties": true
        },
        "extensions": {
          "type": "object",
          "description": "Namespaced extension data.",
          "additionalProperties": true
        }
      }
    },
    "GraphOutput": {
      "type": "object",
      "required": ["id", "type", "source"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier within the graph."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "type": {
          "type": "string",
          "description": "Logical type identifier for the external output."
        },
        "source": {
          "$ref": "#/$defs/EdgeEndpoint",
          "description": "Node and output port that provide this graph output."
        },
        "metadata": {
          "type": "object",
          "description": "Metadata not affecting execution.",
          "additionalProperties": true
        },
        "extensions": {
          "type": "object",
          "description": "Namespaced extension data.",
          "additionalProperties": true
        }
      }
    },
    "TypeField": {
      "type": "object",
      "required": ["name", "type"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Field name."
        },
        "type": {
          "type": "string",
          "description": "Type identifier for the field (built-in or custom)."
        },
        "required": {
          "type": "boolean",
          "description": "Whether this field must be present.",
          "default": false
        }
      }
    },
    "TypeObject": {
      "type": "object",
      "required": ["id", "kind", "fields"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique type identifier (e.g. type:User)."
        },
        "kind": {
          "const": "object"
        },
        "description": {
          "type": "string"
        },
        "fields": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/TypeField"
          }
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        },
        "extensions": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "TypeUnion": {
      "type": "object",
      "required": ["id", "kind", "options"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique type identifier."
        },
        "kind": {
          "const": "union"
        },
        "description": {
          "type": "string"
        },
        "options": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Array of type IDs or built-in types."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        },
        "extensions": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "TypeAlias": {
      "type": "object",
      "required": ["id", "kind", "target"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique type identifier."
        },
        "kind": {
          "const": "alias"
        },
        "description": {
          "type": "string"
        },
        "target": {
          "type": "string",
          "description": "Type ID (or built-in) this type refers to."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        },
        "extensions": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "TypeDefinition": {
      "oneOf": [
        {
          "$ref": "#/$defs/TypeObject"
        },
        {
          "$ref": "#/$defs/TypeUnion"
        },
        {
          "$ref": "#/$defs/TypeAlias"
        }
      ]
    },
    "SubgraphDefinition": {
      "type": "object",
      "required": ["id", "graph"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the subgraph within the document."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name for the subgraph."
        },
        "graph": {
          "$ref": "#/$defs/Graph"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        },
        "extensions": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "GraphEntryContract": {
      "type": "object",
      "description": "Worox-graph entry contract: execution inputs and paths (layer 01). Additional properties may be added by worox-graph.",
      "additionalProperties": true,
      "properties": {
        "summary": {
          "type": "string",
          "description": "Human-readable summary of entry expectations."
        },
        "requiredExecutionPaths": {
          "type": "array",
          "description": "Descriptors for execution paths that must be satisfied (engine-specific item shape).",
          "items": {}
        },
        "executionSchema": {
          "type": "object",
          "description": "JSON Schema for the merged execution object (tooling validates at runtime when enabled)."
        },
        "notableExecutionPaths": {
          "type": "array",
          "description": "Notable optional or diagnostic execution paths.",
          "items": {}
        }
      }
    },
    "GraphResponseContract": {
      "type": "object",
      "description": "Worox-graph response contract: final output shape (layer 08). Additional properties may be added by worox-graph.",
      "additionalProperties": true,
      "properties": {
        "summary": {
          "type": "string",
          "description": "Human-readable summary of the response / final output."
        },
        "finalOutputSchema": {
          "type": "object",
          "description": "JSON Schema for the final output value (tooling validates at runtime when enabled)."
        }
      }
    },
    "WoroxCatalogRequest": {
      "type": "object",
      "description": "Planning-only catalog request on a worox-graph task node (`node.metadata.catalogRequest`). Execution is unchanged. Canonical field set: `@woroces/worox-graph` `refs.ts`.",
      "additionalProperties": true
    },
    "WoroxCatalogBinding": {
      "type": "object",
      "description": "Planning-only catalog binding on a worox-graph task node (`node.metadata.catalogBinding`). Execution is unchanged. Canonical field set: `@woroces/worox-graph` `refs.ts`.",
      "additionalProperties": true
    },
    "WoroxCatalogRequests": {
      "description": "Planning-only document-level catalog requests (`metadata.catalogRequests` on worox graph JSON). Execution is unchanged. Shape may be a list or a map; see `@woroces/worox-graph` `refs.ts`.",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/WoroxCatalogRequest"
          }
        },
        {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/WoroxCatalogRequest"
          }
        }
      ]
    }
  }
}