CreateGraphRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/robosystems-ai/json-schema/robosystems-ai-create-graph-request-schema.json",
  "title": "CreateGraphRequest",
  "description": "Request model for creating a new graph.\n\nUse this to create either:\n- **Entity graphs**: Standard graphs with entity schema. Requires `initial_entity`.\n- **Custom graphs**: Generic graphs with a fully custom schema. Requires `custom_schema`; `initial_entity` is not used.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/robosystems-ai-openapi.json#/components/schemas/CreateGraphRequest",
  "properties": {
    "metadata": {
      "$ref": "#/$defs/GraphMetadata",
      "description": "Graph metadata including name, description, and schema extensions"
    },
    "instance_tier": {
      "type": "string",
      "pattern": "^(ladybug-standard|ladybug-large|ladybug-xlarge)$",
      "title": "Instance Tier",
      "description": "Instance tier: ladybug-standard, ladybug-large, ladybug-xlarge",
      "default": "ladybug-standard"
    },
    "custom_schema": {
      "anyOf": [
        {
          "$ref": "#/$defs/CustomSchemaDefinition"
        },
        {
          "type": "null"
        }
      ],
      "description": "Custom schema definition to apply. If provided, creates a generic custom graph. If omitted, creates an entity graph using schema_extensions."
    },
    "initial_entity": {
      "anyOf": [
        {
          "$ref": "#/$defs/InitialEntityData"
        },
        {
          "type": "null"
        }
      ],
      "description": "Initial entity for the graph. Required for entity graphs (when custom_schema is omitted). Omit only when providing custom_schema for a generic graph."
    },
    "create_entity": {
      "type": "boolean",
      "title": "Create Entity",
      "description": "Whether to create the entity node and upload initial data. Only applies when initial_entity is provided. Set to False to create graph without populating entity data (useful for file-based ingestion workflows).",
      "default": true
    },
    "tags": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "maxItems": 10,
      "title": "Tags",
      "description": "Optional tags for organization"
    }
  },
  "type": "object",
  "required": [
    "metadata"
  ],
  "$defs": {
    "CustomSchemaDefinition": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Schema name"
        },
        "version": {
          "type": "string",
          "title": "Version",
          "description": "Schema version",
          "default": "1.0.0"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description",
          "description": "Schema description"
        },
        "extends": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Extends",
          "description": "Base schema to extend (e.g., 'base' for common utilities)"
        },
        "nodes": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array",
          "title": "Nodes",
          "description": "List of node definitions with properties"
        },
        "relationships": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array",
          "title": "Relationships",
          "description": "List of relationship definitions"
        },
        "metadata": {
          "additionalProperties": true,
          "type": "object",
          "title": "Metadata",
          "description": "Additional schema metadata"
        }
      },
      "type": "object",
      "required": [
        "name"
      ],
      "title": "CustomSchemaDefinition",
      "description": "Custom node and relationship types for a generic graph.\n\nFor graphs that don't fit the entity-based schema — inventory, org charts,\nproject management. `extends` names a base schema to build on, or is\nomitted for a bare database."
    },
    "GraphMetadata": {
      "properties": {
        "graph_name": {
          "type": "string",
          "title": "Graph Name",
          "description": "Display name for the graph"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description",
          "description": "Optional description"
        },
        "schema_extensions": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Schema Extensions",
          "description": "Schema extensions to enable"
        },
        "tags": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Tags",
          "description": "Tags for organizing graphs"
        }
      },
      "type": "object",
      "required": [
        "graph_name"
      ],
      "title": "GraphMetadata",
      "description": "Metadata for graph creation."
    },
    "InitialEntityData": {
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 255,
          "minLength": 1,
          "title": "Name",
          "description": "Entity name"
        },
        "uri": {
          "type": "string",
          "minLength": 1,
          "title": "Uri",
          "description": "Entity website or URI"
        },
        "ticker": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 10,
              "minLength": 1
            },
            {
              "type": "null"
            }
          ],
          "title": "Ticker",
          "description": "Entity symbol/ticker (e.g., 'HARB', 'NVDA'). Auto-generated from name if not provided."
        },
        "cik": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Cik",
          "description": "CIK number for SEC filings"
        },
        "sic": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sic",
          "description": "SIC code"
        },
        "sic_description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sic Description",
          "description": "SIC description"
        },
        "category": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Category",
          "description": "Business category"
        },
        "state_of_incorporation": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "State Of Incorporation",
          "description": "State of incorporation"
        },
        "fiscal_year_end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fiscal Year End",
          "description": "Fiscal year end (MMDD)"
        },
        "ein": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Ein",
          "description": "Employer Identification Number"
        },
        "entity_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Entity Type",
          "description": "Entity legal form (e.g. 'corporation', 'llc' / 'limited_liability_company', 'partnership', 'sole_proprietorship', 'non_profit'). Drives the graph's default Reporting Style at creation — partnership and llc get dedicated equity-form Styles; everything else defaults to corporate. Blank falls back to corporate."
        },
        "reporting_style_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Reporting Style Id",
          "description": "Optional explicit Reporting Style Structure id to pin on the entity, overriding the entity_type-derived default. Leave blank to derive from entity_type. Change later via the change-reporting-style operation."
        }
      },
      "type": "object",
      "required": [
        "name",
        "uri"
      ],
      "title": "InitialEntityData",
      "description": "Initial entity data for entity-focused graph creation.\n\nWhen creating an entity graph with an initial entity node, this model defines\nthe entity's identifying information and metadata."
    }
  }
}