Gaur Docs

The canonical JSON Schemas that validate contract definitions and contract queries.

Gaur ships two JSON Schemas (Draft-07). They are the canonical, machine- readable definition of what a contract and a query may contain.

The contract schema validates a contract definition.
The query schema validates a request sent to a contract.

JSON Schema checks syntax: required fields, types, allowed values, patterns. It does not check semantics: rules like single-fact, fan-out, and chasm are enforced by Gaur when a contract is created or queried. See Rules and limitations.

For a field-by-field walkthrough, see the API reference Contract schema and Query schema.

Contract schema

Validates a contract definition. Source of truth: schemas/v1/contract.json.

contract.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://schema.gaur.dev/v1/contract.schema.json",
  "title": "Gaur Analytical Contract",
  "description": "Strict runtime schema for Gaur semantic models. Syntax validated by JSON Schema, semantics by Backend API.",
  "type": "object",
  "required": ["name", "sources", "dimensions", "measures"],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z_][a-z0-9_]*$"
    },
    "description": {
      "type": ["string", "null"]
    },
    "sources": {
      "type": "array",
      "minItems": 1,
      "items": [
        {
          "type": "object",
          "required": ["source_type", "name", "alias"],
          "properties": {
            "source_type": { "type": "string", "enum": ["table", "model"] },
            "name": { "type": "string" },
            "alias": { "type": "string" },
            "join_type": { "not": {} },
            "cardinality": { "not": {} },
            "on": { "not": {} }
          },
          "additionalProperties": false
        }
      ],
      "additionalItems": {
        "type": "object",
        "required": ["source_type", "name", "alias", "join_type", "cardinality", "on"],
        "properties": {
          "source_type": { "type": "string", "enum": ["table", "model"] },
          "name": { "type": "string" },
          "alias": { "type": "string" },
          "join_type": { "type": "string", "enum": ["left", "inner", "right", "full"] },
          "cardinality": { "type": "string", "enum": ["one_to_one", "one_to_many", "many_to_one"] },
          "on": { "type": "string" }
        },
        "additionalProperties": false
      }
    },
    "dimensions": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": false,
      "patternProperties": {
        "^[a-z_][a-z0-9_]*$": {
          "type": "object",
          "required": ["sql", "type"],
          "additionalProperties": false,
          "properties": {
            "sql": { "type": "string" },
            "type": { "type": "string", "enum": ["string", "number", "boolean", "timestamp", "date"] },
            "description": { "type": ["string", "null"] },
            "semantic_type": {
              "type": "string",
              "enum": ["time"]
            },
            "time_grains": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": ["hour", "day", "week", "month", "quarter", "year"]
              }
            }
          }
        }
      }
    },
    "measures": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": false,
      "patternProperties": {
        "^[a-z_][a-z0-9_]*$": {
          "oneOf": [
            {
              "type": "object",
              "required": ["sql", "type"],
              "additionalProperties": false,
              "properties": {
                "sql": { "type": "string" },
                "type": { "type": "string", "enum": ["number", "boolean", "timestamp", "date"] },
                "behavior": { "type": "string", "enum": ["standard"] },
                "description": { "type": ["string", "null"] },
                "additivity": {
                  "type": "string",
                  "enum": ["additive", "non_additive", "semi_additive"]
                },
                "semi_additive_grain": {
                  "type": "string",
                  "pattern": "^[a-z_][a-z0-9_]*$"
                }
              }
            },
            {
              "type": "object",
              "required": ["behavior", "type", "base_measure", "window", "order_by"],
              "additionalProperties": false,
              "properties": {
                "behavior": { "type": "string", "enum": ["rolling"] },
                "type": { "type": "string", "enum": ["number"] },
                "description": { "type": ["string", "null"] },
                "base_measure": { "type": "string" },
                "window": {
                  "type": "string",
                  "pattern": "^[0-9]+(d|w|m)$"
                },
                "order_by": {
                  "type": "string",
                  "pattern": "^([a-z_][a-z0-9_]*|[a-z_][a-z0-9_]*\\.[a-z_][a-z0-9_]*)$"
                }
              }
            },
            {
              "type": "object",
              "required": ["behavior", "numerator", "denominator"],
              "additionalProperties": false,
              "properties": {
                "behavior": { "type": "string", "enum": ["derived"] },
                "type": { "type": "string", "enum": ["number"] },
                "description": { "type": ["string", "null"] },
                "numerator": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
                "denominator": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" }
              }
            }
          ]
        }
      }
    },
    "filters": {
      "type": ["array", "null"],
      "items": { "type": "string" }
    },
    "rls": {
      "type": ["object", "null"],
      "required": ["sql", "parameters"],
      "additionalProperties": false,
      "properties": {
        "sql": { "type": "string" },
        "parameters": {
          "type": "object",
          "patternProperties": {
            "^[a-zA-Z0-9_]+$": { "type": "string" }
          }
        }
      }
    }
  }
}

Query schema

Validates a request sent to a contract through the query endpoint. Source of truth: schemas/v1/query.json.

query.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://schema.gaur.dev/v1/query.schema.json",
  "title": "Gaur Contract Query",
  "description": "Strict runtime schema for production analytical consumption.",
  "type": "object",
  "required": ["contract_name", "query"],
  "additionalProperties": false,
  "properties": {
    "contract_name": {
      "type": "string",
      "pattern": "^[a-z0-9_]+$",
      "description": "The stable identifier for the analytical contract."
    },
    "context": {
      "type": "object",
      "additionalProperties": true,
      "description": "Securely injected parameters for RLS (e.g., seller_id)."
    },
    "query": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "dimensions": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["name"],
            "additionalProperties": false,
            "properties": {
              "name": { "type": "string", "pattern": "^[a-z0-9_]+$" },
              "time_grain": {
                "type": "string",
                "enum": ["hour", "day", "week", "month", "quarter", "year"]
              }
            }
          }
        },
        "measures": {
          "type": "array",
          "items": { "type": "string", "pattern": "^[a-z0-9_]+$" }
        },
        "filters": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["field", "operator", "value"],
            "additionalProperties": false,
            "properties": {
              "field": { "type": "string", "pattern": "^[a-z0-9_]+$" },
              "operator": {
                "type": "string",
                "enum": ["eq", "not_eq", "lt", "lte", "gt", "gte", "in", "not_in", "like", "is_null", "is_not_null"]
              },
              "value": {}
            }
          }
        },
        "sorts": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["field", "direction"],
            "additionalProperties": false,
            "properties": {
              "field": { "type": "string", "pattern": "^[a-z0-9_]+$" },
              "direction": { "type": "string", "enum": ["asc", "desc"] }
            }
          }
        },
        "limit": { "type": "integer", "minimum": 1 },
        "offset": { "type": "integer", "minimum": 0 }
      }
    }
  }
}

Anatomy of a contract

A field-by-field walkthrough of the contract document.

Rules & limitations

The semantic rules JSON Schema cannot express.

JSON schema

Contract schema

Query schema

Next

Anatomy of a contract

Rules & limitations

On this page