Skip to content
Kartograph v0.13.0

Mutation Operation Schema

Overview

Section titled “Overview”

All mutation operations follow a strict JSON schema. This ensures consistency and enables validation at both the Extraction and Graph boundaries.

Schema Location

Section titled “Schema Location”

The complete JSON Schema can be visualized using the Atlassian JSON Schema Viewer.

Operation Types

Section titled “Operation Types”

DEFINE

Section titled “DEFINE”
{
  "op": "DEFINE",
  "type": "node" | "edge",
  "label": "string",
  "description": "string",
  "example_file_path": "string",
  "example_in_file_path": "string",
  "required_properties": ["array", "of", "strings"]
}

CREATE

Section titled “CREATE”
{
  "op": "CREATE",
  "type": "node" | "edge",
  "id": "string",
  "label": "string",
  "set_properties": {
    "data_source_id": "required",
    "source_path": "required",
    "slug": "required" // Only required for `CREATE node` operations
    ...
  }
}

For edges, add:

{
  "start_id": "string",
  "end_id": "string"
}

UPDATE

Section titled “UPDATE”
{
  "op": "UPDATE",
  "type": "node" | "edge",
  "id": "string",
  "set_properties": {},
  "remove_properties": []
}

DELETE

Section titled “DELETE”
{
  "op": "DELETE",
  "type": "node" | "edge",
  "id": "string"
}

System Properties

Section titled “System Properties”

System properties are automatically managed by Kartograph and must be included in all CREATE operations.

Common Properties (All Entities)

Section titled “Common Properties (All Entities)”
  • data_source_id - Identifies which data source this entity came from (e.g., 'ds-123')
  • source_path - The file path within the data source where this entity was extracted from

Node-Specific Properties

Section titled “Node-Specific Properties”

All CREATE node operations must include the common properties plus these additional properties:

  • slug - Unique human-readable identifier for the node (e.g., 'alice-smith', 'kartograph')

Edge-Specific Properties

Section titled “Edge-Specific Properties”

All CREATE edge operations must include the common properties plus these additional properties:

None - edges only require common properties

Validation

Section titled “Validation”

You can live-edit JSON objects with schema validation using the Atlassian JSON Schema Viewer.

Next Steps

Section titled “Next Steps”