Validate Schema

post/v1/graphs/schema/validate

Part of Graphs.

Validates a custom schema definition before deployment — checks structure, types, constraints, and relationship references. Returns errors and warnings without applying changes. Supports JSON, YAML, and dict formats.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Request body

Required, application/json.

Field Type Description

Field	Type	Description
`schema_definition`required	object \| string	Schema definition as JSON dict or JSON/YAML string
`format`optional	string	Schema format: json, yaml, or dict Default: `json`
`check_compatibility`optional	string[]	List of existing schema extensions to check compatibility with

schema_definitionrequired

object | string

Schema definition as JSON dict or JSON/YAML string

formatoptional

string

Schema format: json, yaml, or dict

Default: json

check_compatibilityoptional

string[]

List of existing schema extensions to check compatibility with

Example request

curl · Valid Schema with Relationships

curl -X POST "https://api.robosystems.ai/v1/graphs/schema/validate" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_definition": {
    "name": "financial_analysis",
    "version": "1.0.0",
    "description": "Schema for SEC financial data",
    "nodes": [
      {
        "name": "Company",
        "properties": [
          {
            "name": "cik",
            "type": "STRING",
            "is_primary_key": true
          },
          {
            "name": "name",
            "type": "STRING",
            "nullable": false
          },
          {
            "name": "ticker",
            "type": "STRING"
          }
        ]
      },
      {
        "name": "Filing",
        "properties": [
          {
            "name": "accession_number",
            "type": "STRING",
            "is_primary_key": true
          },
          {
            "name": "form_type",
            "type": "STRING"
          }
        ]
      }
    ],
    "relationships": [
      {
        "name": "FILED",
        "from_node": "Company",
        "to_node": "Filing"
      }
    ]
  },
  "format": "json"
}'

curl · Schema with Warnings

curl -X POST "https://api.robosystems.ai/v1/graphs/schema/validate" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_definition": {
    "name": "warehouse_schema",
    "version": "1.0.0",
    "nodes": [
      {
        "name": "Product",
        "properties": [
          {
            "name": "sku",
            "type": "STRING",
            "is_primary_key": true
          }
        ]
      },
      {
        "name": "Location",
        "properties": [
          {
            "name": "id",
            "type": "STRING",
            "is_primary_key": true
          }
        ]
      }
    ],
    "relationships": []
  },
  "format": "json"
}'

curl · Invalid Schema

curl -X POST "https://api.robosystems.ai/v1/graphs/schema/validate" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_definition": {
    "name": "invalid_example",
    "version": "1.0.0",
    "nodes": [
      {
        "name": "Company",
        "properties": [
          {
            "name": "name",
            "type": "INVALID_TYPE"
          }
        ]
      }
    ],
    "relationships": [
      {
        "name": "RELATES_TO",
        "from_node": "Company",
        "to_node": "NonExistentNode"
      }
    ]
  },
  "format": "json"
}'

curl · YAML Format Schema

curl -X POST "https://api.robosystems.ai/v1/graphs/schema/validate" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_definition": "name: inventory_schema\nversion: '\''1.0.0'\''\nnodes:\n  - name: Product\n    properties:\n      - name: sku\n        type: STRING\n        is_primary_key: true\n      - name: name\n        type: STRING\nrelationships:\n  - name: IN_CATEGORY\n    from_node: Product\n    to_node: Category",
  "format": "yaml"
}'

curl · Compatibility Check

curl -X POST "https://api.robosystems.ai/v1/graphs/schema/validate" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_definition": {
    "name": "custom_extension",
    "version": "1.0.0",
    "nodes": [
      {
        "name": "Transaction",
        "properties": [
          {
            "name": "id",
            "type": "STRING",
            "is_primary_key": true
          },
          {
            "name": "amount",
            "type": "DOUBLE"
          }
        ]
      }
    ]
  },
  "format": "json",
  "check_compatibility": [
    "roboledger"
  ]
}'

Responses

200 Successful Response

Field	Type	Description
`valid`required	boolean	Whether the schema is valid
`message`required	string	Validation message
`errors`optional	string[]	List of validation errors (only present when valid=false)
`warnings`optional	string[]	List of validation warnings (schema is still valid but has potential issues)
`stats`optional	object	Schema statistics (only present when valid=true)
`compatibility`optional	object	Compatibility check results (only when check_compatibility specified)

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
422	Schema fails validation rules
429	Rate limit exceeded
500	Internal server error
504	Validation timed out