{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://graphersal.dev/schema/v1",
"title": "GraphersalGraphSchema",
"description": "A Graphersal graph schema: an envelope (mode, meta, labels, connections) around a strict subset of JSON Schema 2020-12 for each label's properties. Unknown keys are errors everywhere.",
"type": "object",
"additionalProperties": false,
"properties": {
"$schema": { "const": "https://graphersal.dev/schema/v1" },
"meta": {
"description": "Free-form data the library stores, round-trips and never interprets.",
"type": "object"
},
"mode": { "enum": ["none", "open", "closed"], "default": "none" },
"vertices": {
"type": "object",
"propertyNames": { "minLength": 1 },
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": { "$ref": "#/$defs/label_schema" }
}
}
},
"edges": {
"type": "object",
"propertyNames": { "minLength": 1 },
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"connections": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["from", "to"],
"properties": {
"from": { "type": "string", "minLength": 1 },
"to": { "type": "string", "minLength": 1 }
}
}
},
"schema": { "$ref": "#/$defs/label_schema" }
}
}
}
},
"$defs": {
"label_schema": {
"description": "The JSON Schema of a label's property map: an object node, optionally with $defs for local $ref.",
"type": "object",
"required": ["type"],
"properties": {
"type": { "const": "object" },
"$schema": { "type": "string" },
"$id": { "type": "string" },
"$defs": { "type": "object", "additionalProperties": { "$ref": "#/$defs/node" } },
"properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/node" } },
"required": { "$ref": "#/$defs/key_list" },
"additionalProperties": { "type": "boolean" },
"title": { "type": "string" },
"description": { "type": "string" },
"$comment": { "type": "string" },
"examples": { "type": "array" },
"deprecated": { "type": "boolean" },
"default": true,
"$ref": { "$ref": "#/$defs/local_ref" }
},
"additionalProperties": false
},
"type_name": { "enum": ["null", "boolean", "integer", "number", "string", "array", "object"] },
"key_list": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
"local_ref": { "type": "string", "pattern": "^#/\\$defs/" },
"count": { "type": "integer", "minimum": 0 },
"node": {
"description": "One property schema node. integer = int64, number = float64, string + format uuid = uuid, string + format date-time / date / local-date-time / time / duration = datetime / date / localdatetime / time / duration (time and local-date-time have no UTC offset). formatMinimum, formatMaximum, formatExclusiveMinimum and formatExclusiveMaximum (text of the format's type) need one of these temporal formats. array + format vector = a vector (an embedding) with element (f32, f16, i8, bit; default f32), dimension (optional) and metric (an annotation) and, on a top-level property, embedder (the model identity of the embedder that produced the vectors); items is not allowed next to it.",
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"anyOf": [
{ "$ref": "#/$defs/type_name" },
{ "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/type_name" } }
]
},
"format": { "enum": ["uuid", "date-time", "date", "local-date-time", "time", "duration", "vector"] },
"element": { "enum": ["f32", "f16", "i8", "bit"], "description": "With format vector: the element kind of the stored vectors (default f32)." },
"dimension": { "type": "integer", "minimum": 1, "maximum": 65536, "description": "With format vector: the number of components." },
"metric": { "enum": ["cosine", "dot", "l2", "hamming"], "description": "With format vector: an annotation, the metric the vectors are compared with." },
"embedder": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._/:@?=-]+$", "description": "With format vector, on a label's top-level property only: the model identity of the embedder that produced the vectors (hash-ngram/1). embed_property records and checks it; a text query of nearest() or similarity() embeds its text with the registered embedder of that model." },
"items": { "$ref": "#/$defs/node" },
"properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/node" } },
"required": { "$ref": "#/$defs/key_list" },
"additionalProperties": { "type": "boolean" },
"anyOf": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/node" } },
"enum": { "type": "array", "minItems": 1 },
"const": true,
"minimum": { "type": "number" },
"maximum": { "type": "number" },
"exclusiveMinimum": { "type": "number" },
"exclusiveMaximum": { "type": "number" },
"formatMinimum": { "type": "string" },
"formatMaximum": { "type": "string" },
"formatExclusiveMinimum": { "type": "string" },
"formatExclusiveMaximum": { "type": "string" },
"minLength": { "$ref": "#/$defs/count" },
"maxLength": { "$ref": "#/$defs/count" },
"pattern": { "type": "string", "format": "regex" },
"minItems": { "$ref": "#/$defs/count" },
"maxItems": { "$ref": "#/$defs/count" },
"title": { "type": "string" },
"description": { "type": "string" },
"$comment": { "type": "string" },
"examples": { "type": "array" },
"deprecated": { "type": "boolean" },
"default": { "description": "On a label's top-level property, in mode open or closed: stored when a vertex or edge is created without the property (null is never stored); never applied on read or to existing data. Elsewhere an annotation." },
"defaultFunction": { "enum": ["uuidv4", "uuidv7", "now", "today"], "description": "On a label's top-level property only: a value computed for every vertex or edge created without the property, in mode open or closed (now and today: the unit's start, one value per unit). Not together with default." },
"$ref": { "$ref": "#/$defs/local_ref" }
}
}
}
}