@x12i/graphenix-core 2.0.0

package/schema/graphenix-format-2.0.0.schema.json

@@ -0,0 +1,348 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://graphenix.dev/schema/graphenix-format-2.0.0.json",
+  "title": "Graphenix Format 2.0.0",
+  "description": "JSON Schema for the Graphenix graph description format (version 2.0.0). Execution semantics are out of scope.",
+  "type": "object",
+  "required": ["formatVersion", "id", "graph"],
+  "additionalProperties": false,
+  "properties": {
+    "formatVersion": {
+      "type": "string",
+      "const": "2.0.0",
+      "description": "Graphenix format version. Must be `2.0.0`."
+    },
+    "id": {
+      "type": "string",
+      "description": "Globally unique identifier for this graph within the system."
+    },
+    "revision": {
+      "type": "string",
+      "description": "Version/revision of this specific graph document. Not the Graphenix format version."
+    },
+    "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."
+    },
+    "metadata": {
+      "$ref": "#/$defs/DocumentMetadata"
+    }
+  },
+  "$defs": {
+    "GraphenixExtensions": {
+      "type": "object",
+      "description": "Namespaced extension object. Keys are extension namespace identifiers (e.g. `x12i.execution/v1`). Graphenix core does not interpret extension namespaces.",
+      "additionalProperties": true
+    },
+    "GraphenixMetadata": {
+      "type": "object",
+      "description": "Arbitrary metadata with optional namespaced extensions under `extensions`.",
+      "additionalProperties": true,
+      "properties": {
+        "extensions": {
+          "$ref": "#/$defs/GraphenixExtensions"
+        }
+      }
+    },
+    "DocumentMetadata": {
+      "allOf": [
+        { "$ref": "#/$defs/GraphenixMetadata" },
+        {
+          "type": "object",
+          "description": "Document-level metadata including graph-level summary contracts.",
+          "properties": {
+            "graphEntry": { "$ref": "#/$defs/GraphEntryContract" },
+            "graphResponse": { "$ref": "#/$defs/GraphResponseContract" },
+            "catalogRequests": { "$ref": "#/$defs/WoroxCatalogRequests" }
+          }
+        }
+      ]
+    },
+    "NodeMetadata": {
+      "allOf": [
+        { "$ref": "#/$defs/GraphenixMetadata" },
+        {
+          "type": "object",
+          "properties": {
+            "catalogBinding": { "$ref": "#/$defs/WoroxCatalogBinding" },
+            "catalogRequest": { "$ref": "#/$defs/WoroxCatalogRequest" }
+          }
+        }
+      ]
+    },
+    "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": {
+          "$ref": "#/$defs/GraphenixMetadata"
+        }
+      }
+    },
+    "Node": {
+      "type": "object",
+      "required": ["id", "kind"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "kind": { "type": "string" },
+        "inputs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/PortDefinition" },
+          "default": []
+        },
+        "outputs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/PortDefinition" },
+          "default": []
+        },
+        "parameters": {
+          "type": "object",
+          "additionalProperties": true,
+          "default": {}
+        },
+        "metadata": { "$ref": "#/$defs/NodeMetadata" }
+      }
+    },
+    "PortDefinition": {
+      "type": "object",
+      "required": ["id", "direction", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "direction": { "type": "string", "enum": ["input", "output"] },
+        "type": { "type": "string" },
+        "required": { "type": "boolean", "default": false },
+        "default": {
+          "type": ["string", "number", "boolean", "array", "object", "null"]
+        }
+      }
+    },
+    "EdgeEndpoint": {
+      "type": "object",
+      "required": ["nodeId", "portId"],
+      "additionalProperties": false,
+      "properties": {
+        "nodeId": { "type": "string" },
+        "portId": { "type": "string" }
+      }
+    },
+    "Edge": {
+      "type": "object",
+      "required": ["id", "from", "to"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "from": { "$ref": "#/$defs/EdgeEndpoint" },
+        "to": { "$ref": "#/$defs/EdgeEndpoint" },
+        "metadata": { "$ref": "#/$defs/GraphenixMetadata" }
+      }
+    },
+    "GraphInput": {
+      "type": "object",
+      "required": ["id", "type", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "target": { "$ref": "#/$defs/EdgeEndpoint" },
+        "contract": { "$ref": "#/$defs/GraphInputContract" },
+        "metadata": { "$ref": "#/$defs/GraphenixMetadata" }
+      }
+    },
+    "GraphInputContract": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "semanticKind": { "type": "string" },
+        "required": { "type": "boolean", "default": false },
+        "schema": { "type": "object", "additionalProperties": true },
+        "resolver": { "$ref": "#/$defs/GraphInputResolver" }
+      }
+    },
+    "GraphInputResolver": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "kind": { "type": "string" },
+        "graphId": { "type": "string" },
+        "metadataFilter": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "GraphOutput": {
+      "type": "object",
+      "required": ["id", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "source": { "$ref": "#/$defs/EdgeEndpoint" },
+        "contract": { "$ref": "#/$defs/GraphOutputContract" },
+        "metadata": { "$ref": "#/$defs/GraphenixMetadata" }
+      }
+    },
+    "GraphOutputContract": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "semanticKind": { "type": "string" },
+        "required": { "type": "boolean", "default": false },
+        "schema": { "type": "object", "additionalProperties": true },
+        "description": { "type": "string" }
+      }
+    },
+    "TypeField": {
+      "type": "object",
+      "required": ["name", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "required": { "type": "boolean", "default": false }
+      }
+    },
+    "TypeObject": {
+      "type": "object",
+      "required": ["id", "kind", "fields"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "const": "object" },
+        "description": { "type": "string" },
+        "fields": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/TypeField" }
+        },
+        "metadata": { "$ref": "#/$defs/GraphenixMetadata" }
+      }
+    },
+    "TypeUnion": {
+      "type": "object",
+      "required": ["id", "kind", "options"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "const": "union" },
+        "description": { "type": "string" },
+        "options": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "metadata": { "$ref": "#/$defs/GraphenixMetadata" }
+      }
+    },
+    "TypeAlias": {
+      "type": "object",
+      "required": ["id", "kind", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "const": "alias" },
+        "description": { "type": "string" },
+        "target": { "type": "string" },
+        "metadata": { "$ref": "#/$defs/GraphenixMetadata" }
+      }
+    },
+    "TypeDefinition": {
+      "oneOf": [
+        { "$ref": "#/$defs/TypeObject" },
+        { "$ref": "#/$defs/TypeUnion" },
+        { "$ref": "#/$defs/TypeAlias" }
+      ]
+    },
+    "SubgraphDefinition": {
+      "type": "object",
+      "required": ["id", "graph"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "graph": { "$ref": "#/$defs/Graph" },
+        "metadata": { "$ref": "#/$defs/GraphenixMetadata" }
+      }
+    },
+    "GraphEntryContract": {
+      "type": "object",
+      "description": "Graph-level summary contract for graph invocation.",
+      "additionalProperties": true,
+      "properties": {
+        "summary": { "type": "string" },
+        "requiredExecutionPaths": { "type": "array", "items": {} },
+        "executionSchema": { "type": "object", "additionalProperties": true },
+        "notableExecutionPaths": { "type": "array", "items": {} }
+      }
+    },
+    "GraphResponseContract": {
+      "type": "object",
+      "description": "Graph-level summary contract for the final graph result.",
+      "additionalProperties": true,
+      "properties": {
+        "summary": { "type": "string" },
+        "finalOutputSchema": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "WoroxCatalogRequest": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "WoroxCatalogBinding": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "WoroxCatalogRequests": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": { "$ref": "#/$defs/WoroxCatalogRequest" }
+        },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/WoroxCatalogRequest" }
+        }
+      ]
+    }
+  }
+}