synor/sdk/shared/schemas/database.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://synor.io/schemas/database.json",
  "title": "Synor Database SDK",
  "description": "Key-value, document, vector, and time-series database operations",

  "$defs": {
    "DatabaseConfig": {
      "type": "object",
      "allOf": [{ "$ref": "common.json#/$defs/SynorConfig" }],
      "properties": {
        "namespace": {
          "type": "string",
          "description": "Database namespace for isolation"
        }
      }
    },

    "Value": {
      "oneOf": [
        { "type": "string" },
        { "type": "number" },
        { "type": "boolean" },
        { "type": "object" },
        { "type": "array" },
        { "type": "null" }
      ]
    },

    "KeyValue": {
      "type": "object",
      "properties": {
        "key": { "type": "string" },
        "value": { "$ref": "#/$defs/Value" },
        "ttl": { "$ref": "common.json#/$defs/Duration" },
        "createdAt": { "$ref": "common.json#/$defs/Timestamp" },
        "updatedAt": { "$ref": "common.json#/$defs/Timestamp" }
      },
      "required": ["key", "value"]
    },

    "KvGetRequest": {
      "type": "object",
      "properties": {
        "key": { "type": "string" }
      },
      "required": ["key"]
    },

    "KvSetRequest": {
      "type": "object",
      "properties": {
        "key": { "type": "string" },
        "value": { "$ref": "#/$defs/Value" },
        "ttl": { "$ref": "common.json#/$defs/Duration" },
        "nx": { "type": "boolean", "description": "Only set if key does not exist" },
        "xx": { "type": "boolean", "description": "Only set if key exists" }
      },
      "required": ["key", "value"]
    },

    "KvListRequest": {
      "type": "object",
      "properties": {
        "prefix": { "type": "string" },
        "cursor": { "type": "string" },
        "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }
      },
      "required": ["prefix"]
    },

    "Document": {
      "type": "object",
      "properties": {
        "_id": { "type": "string" },
        "_rev": { "type": "string" },
        "_createdAt": { "$ref": "common.json#/$defs/Timestamp" },
        "_updatedAt": { "$ref": "common.json#/$defs/Timestamp" }
      },
      "additionalProperties": true,
      "required": ["_id"]
    },

    "DocumentQuery": {
      "type": "object",
      "properties": {
        "filter": { "type": "object" },
        "sort": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "field": { "type": "string" },
              "order": { "type": "string", "enum": ["asc", "desc"] }
            }
          }
        },
        "projection": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "allOf": [{ "$ref": "common.json#/$defs/PaginationParams" }]
    },

    "DocCreateRequest": {
      "type": "object",
      "properties": {
        "collection": { "type": "string" },
        "document": { "type": "object" }
      },
      "required": ["collection", "document"]
    },

    "DocGetRequest": {
      "type": "object",
      "properties": {
        "collection": { "type": "string" },
        "id": { "type": "string" }
      },
      "required": ["collection", "id"]
    },

    "DocUpdateRequest": {
      "type": "object",
      "properties": {
        "collection": { "type": "string" },
        "id": { "type": "string" },
        "update": { "type": "object" },
        "upsert": { "type": "boolean", "default": false }
      },
      "required": ["collection", "id", "update"]
    },

    "DocQueryRequest": {
      "type": "object",
      "properties": {
        "collection": { "type": "string" },
        "query": { "$ref": "#/$defs/DocumentQuery" }
      },
      "required": ["collection", "query"]
    },

    "VectorEntry": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "vector": {
          "type": "array",
          "items": { "type": "number" }
        },
        "metadata": { "type": "object" }
      },
      "required": ["id", "vector"]
    },

    "VectorUpsertRequest": {
      "type": "object",
      "properties": {
        "collection": { "type": "string" },
        "vectors": {
          "type": "array",
          "items": { "$ref": "#/$defs/VectorEntry" }
        }
      },
      "required": ["collection", "vectors"]
    },

    "VectorSearchRequest": {
      "type": "object",
      "properties": {
        "collection": { "type": "string" },
        "vector": {
          "type": "array",
          "items": { "type": "number" }
        },
        "k": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 },
        "filter": { "type": "object" },
        "includeMetadata": { "type": "boolean", "default": true },
        "includeVectors": { "type": "boolean", "default": false }
      },
      "required": ["collection", "vector"]
    },

    "VectorSearchResult": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "score": { "type": "number" },
        "vector": {
          "type": "array",
          "items": { "type": "number" }
        },
        "metadata": { "type": "object" }
      },
      "required": ["id", "score"]
    },

    "DataPoint": {
      "type": "object",
      "properties": {
        "timestamp": { "$ref": "common.json#/$defs/Timestamp" },
        "value": { "type": "number" },
        "tags": {
          "type": "object",
          "additionalProperties": { "type": "string" }
        }
      },
      "required": ["timestamp", "value"]
    },

    "TimeRange": {
      "type": "object",
      "properties": {
        "start": { "$ref": "common.json#/$defs/Timestamp" },
        "end": { "$ref": "common.json#/$defs/Timestamp" }
      },
      "required": ["start", "end"]
    },

    "Aggregation": {
      "type": "object",
      "properties": {
        "function": {
          "type": "string",
          "enum": ["avg", "sum", "min", "max", "count", "first", "last", "stddev"]
        },
        "interval": { "$ref": "common.json#/$defs/Duration" },
        "groupBy": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "required": ["function"]
    },

    "TsWriteRequest": {
      "type": "object",
      "properties": {
        "series": { "type": "string" },
        "points": {
          "type": "array",
          "items": { "$ref": "#/$defs/DataPoint" }
        }
      },
      "required": ["series", "points"]
    },

    "TsQueryRequest": {
      "type": "object",
      "properties": {
        "series": { "type": "string" },
        "range": { "$ref": "#/$defs/TimeRange" },
        "aggregation": { "$ref": "#/$defs/Aggregation" },
        "filter": {
          "type": "object",
          "additionalProperties": { "type": "string" }
        }
      },
      "required": ["series", "range"]
    },

    "TsQueryResponse": {
      "type": "object",
      "properties": {
        "series": { "type": "string" },
        "points": {
          "type": "array",
          "items": { "$ref": "#/$defs/DataPoint" }
        }
      },
      "required": ["series", "points"]
    }
  }
}