{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Haybarn Function Guide — function document, version 1",
  "description": "Catalog facts, editorial guidance and observed availability for one function in one captured build. Additive fields may be introduced within schema version 1. Null is unknown or unrecorded.",
  "type": "object",
  "required": [
    "$schema",
    "schemaVersion",
    "name",
    "schema",
    "slug",
    "description",
    "category",
    "kinds",
    "aliasOf",
    "snapshot",
    "links",
    "interpretation",
    "overloads",
    "editorial",
    "examples",
    "availability"
  ],
  "properties": {
    "$schema": {
      "const": "/products/haybarn/functions/api/v1/function.schema.json"
    },
    "schemaVersion": {
      "const": 1
    },
    "name": {
      "type": "string"
    },
    "schema": {
      "const": "main"
    },
    "slug": {
      "type": "string",
      "pattern": "^[a-z0-9_-]+$"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "category": {
      "type": "string"
    },
    "kinds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "aliasOf": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "snapshot": {
      "type": "object",
      "required": [
        "id",
        "engine",
        "label",
        "engineVersion",
        "sourceId",
        "source",
        "binarySha256",
        "capturedAt",
        "requestedExtensions",
        "loadedExtensions",
        "scope"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "engine": {
          "enum": [
            "haybarn",
            "duckdb"
          ]
        },
        "label": {
          "type": "string"
        },
        "engineVersion": {
          "type": "string"
        },
        "sourceId": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "binarySha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "capturedAt": {
          "type": "string"
        },
        "requestedExtensions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "scope": {
          "type": "string"
        },
        "loadedExtensions": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "extension_name",
              "extension_version",
              "installed_from"
            ],
            "properties": {
              "extension_name": {
                "type": "string"
              },
              "extension_version": {
                "type": "string"
              },
              "installed_from": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "links": {
      "type": "object",
      "required": [
        "html",
        "markdown",
        "json"
      ],
      "properties": {
        "html": {
          "type": "string"
        },
        "markdown": {
          "type": "string"
        },
        "json": {
          "type": "string"
        }
      }
    },
    "interpretation": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "overloads": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "id",
          "url",
          "signature",
          "parameterOrder",
          "catalog"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^overload-[a-f0-9]{16}$"
          },
          "url": {
            "type": "string"
          },
          "signature": {
            "type": "string"
          },
          "parameterOrder": {
            "enum": [
              "catalog-order",
              "alphabetical-not-call-order"
            ]
          },
          "catalog": {
            "type": "object",
            "required": [
              "schema_name",
              "function_name",
              "function_type",
              "description",
              "return_type",
              "parameters",
              "parameter_types",
              "varargs",
              "examples",
              "stability",
              "has_side_effects",
              "alias_of"
            ],
            "properties": {
              "schema_name": {
                "const": "main"
              },
              "function_name": {
                "type": "string"
              },
              "function_type": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "comment": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "return_type": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "parameters": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "parameter_types": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "varargs": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "macro_definition": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "has_side_effects": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "internal": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "examples": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "stability": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "categories": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "alias_of": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "callingConvention": {
            "type": "object",
            "required": [
              "source",
              "parameters",
              "positional",
              "named",
              "variadic",
              "evidence"
            ],
            "properties": {
              "source": {
                "enum": [
                  "engine-binder",
                  null
                ]
              },
              "parameters": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/argument"
                }
              },
              "positional": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "$ref": "#/$defs/argument"
                }
              },
              "named": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "$ref": "#/$defs/argument"
                }
              },
              "variadic": {
                "anyOf": [
                  {
                    "type": "null"
                  },
                  {
                    "type": "object",
                    "required": [
                      "type",
                      "minimumCount",
                      "maximumCount",
                      "namedArgumentMode"
                    ],
                    "properties": {
                      "type": {
                        "type": "string"
                      },
                      "minimumCount": {
                        "type": "null"
                      },
                      "maximumCount": {
                        "type": "null"
                      },
                      "namedArgumentMode": {
                        "type": "null"
                      }
                    }
                  }
                ]
              },
              "evidence": {
                "anyOf": [
                  {
                    "type": "null"
                  },
                  {
                    "type": "object",
                    "required": [
                      "query",
                      "diagnostic"
                    ],
                    "properties": {
                      "query": {
                        "type": "string"
                      },
                      "diagnostic": {
                        "type": "string"
                      }
                    }
                  }
                ]
              }
            }
          },
          "syntax": {
            "type": "object",
            "required": [
              "kind",
              "operator"
            ],
            "properties": {
              "kind": {
                "enum": [
                  "operator",
                  "function"
                ]
              },
              "operator": {
                "anyOf": [
                  {
                    "type": "null"
                  },
                  {
                    "type": "object",
                    "required": [
                      "symbol",
                      "form",
                      "operands",
                      "expression"
                    ],
                    "properties": {
                      "symbol": {
                        "type": "string"
                      },
                      "form": {
                        "enum": [
                          "infix",
                          "prefix",
                          "postfix"
                        ]
                      },
                      "operands": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "expression": {
                        "type": "string"
                      }
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "editorial": {
      "type": "object",
      "required": [
        "argumentNotes",
        "recipes"
      ],
      "properties": {
        "argumentNotes": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "name",
              "note",
              "overloadIds"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "note": {
                "type": "string"
              },
              "overloadIds": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },
        "recipes": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "title",
              "description",
              "sql",
              "source",
              "verification",
              "intendedRuntime"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "sql": {
                "type": "string"
              },
              "source": {
                "const": "guide-recipe"
              },
              "verification": {
                "type": "null"
              },
              "intendedRuntime": {
                "type": "object",
                "required": [
                  "engine",
                  "packageVersion"
                ],
                "properties": {
                  "engine": {
                    "const": "haybarn-wasm"
                  },
                  "packageVersion": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "examples": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "original",
          "sql",
          "overloadIds",
          "source",
          "verification"
        ],
        "properties": {
          "original": {
            "type": "string"
          },
          "sql": {
            "type": "string"
          },
          "overloadIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "const": "engine-catalog"
          },
          "verification": {
            "type": "null"
          }
        }
      }
    },
    "translations": {
      "type": "array",
      "description": "Scoped SQLGlot translation examples, separate from engine catalog facts.",
      "items": {
        "type": "object",
        "required": [
          "function",
          "scope",
          "source",
          "target",
          "formatTokens",
          "provenance"
        ],
        "properties": {
          "function": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "relation": {
            "enum": [
              "direct",
              "rewrite"
            ]
          },
          "source": {
            "type": "object",
            "required": [
              "engine",
              "dialect",
              "name",
              "sql"
            ],
            "properties": {
              "engine": {
                "type": "string"
              },
              "dialect": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "names": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "sql": {
                "type": "string"
              }
            }
          },
          "target": {
            "type": "object",
            "required": [
              "dialect",
              "name",
              "sql"
            ],
            "properties": {
              "dialect": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "sql": {
                "type": "string"
              }
            }
          },
          "formatTokens": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "source",
                "target"
              ],
              "properties": {
                "source": {
                  "type": "string"
                },
                "target": {
                  "type": "string"
                }
              }
            }
          },
          "executionVerified": {
            "type": "boolean"
          },
          "provenance": {
            "type": "object",
            "required": [
              "name",
              "commit",
              "url"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "commit": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "additionalDocumentation": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title",
          "url"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        }
      }
    },
    "runnableExamples": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "function",
          "original",
          "sql",
          "source",
          "verification"
        ],
        "properties": {
          "function": {
            "type": "string"
          },
          "original": {
            "type": [
              "string",
              "null"
            ]
          },
          "sql": {
            "type": "string"
          },
          "source": {
            "enum": [
              "engine-catalog",
              "catalog-with-sample-data",
              "guide-example"
            ]
          },
          "verification": {
            "type": "object",
            "required": [
              "engine",
              "packageVersion",
              "sourceId",
              "binarySha256",
              "rowCount"
            ],
            "properties": {
              "engine": {
                "const": "haybarn-wasm"
              },
              "packageVersion": {
                "type": "string"
              },
              "sourceId": {
                "type": "string"
              },
              "binarySha256": {
                "type": "string"
              },
              "rowCount": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        }
      }
    },
    "availability": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "snapshot",
          "observed",
          "overloadCount",
          "matchingOverloadIds",
          "json"
        ],
        "properties": {
          "snapshot": {
            "type": "string"
          },
          "observed": {
            "type": "boolean"
          },
          "overloadCount": {
            "type": "integer",
            "minimum": 0
          },
          "matchingOverloadIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "json": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  },
  "$defs": {
    "argument": {
      "type": "object",
      "required": [
        "name",
        "type",
        "mode",
        "position"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "type": {
          "type": [
            "string",
            "null"
          ]
        },
        "mode": {
          "enum": [
            "positional",
            "named",
            null
          ]
        },
        "position": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        }
      }
    }
  }
}