Improve crate documentation (#111)

- Document QueryResults
- Delete snippets folder
- Document Value

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

src/builtins/objects.rs

@@ -23,6 +23,12 @@ pub fn register(m: &mut HashMap<&'static str, builtins::BuiltinFcn>) {
     m.insert("object.subset", (subset, 2));
     m.insert("object.union", (object_union, 2));
     m.insert("object.union_n", (object_union_n, 1));
+
+    #[cfg(feature = "jsonschema")]
+    {
+        m.insert("json.match_schema", (json_match_schema, 2));
+        m.insert("json.verify_schema", (json_verify_schema, 1));
+    }
 }
 
 fn json_filter_impl(v: &Value, filter: &Value) -> Value {
@@ -382,3 +388,72 @@ fn object_union_n(
 
     Ok(u)
 }
+
+#[cfg(feature = "jsonschema")]
+fn compile_json_schema(param: &Ref<Expr>, arg: &Value) -> Result<jsonschema::JSONSchema> {
+    let schema_str = match arg {
+        Value::String(schema_str) => schema_str.as_ref().to_string(),
+        _ => arg.to_json_str()?,
+    };
+
+    if let Ok(schema) = serde_json::from_str(&schema_str) {
+        match jsonschema::JSONSchema::compile(&schema) {
+            Ok(schema) => return Ok(schema),
+            Err(e) => bail!(e.to_string()),
+        }
+    }
+    bail!(param.span().error("not a valid json schema"))
+}
+
+#[cfg(feature = "jsonschema")]
+fn json_verify_schema(
+    span: &Span,
+    params: &[Ref<Expr>],
+    args: &[Value],
+    strict: bool,
+) -> Result<Value> {
+    let name = "json.verify_schema";
+    ensure_args_count(span, name, params, args, 1)?;
+
+    Ok(Value::from_array(
+        match compile_json_schema(&params[0], &args[0]) {
+            Ok(_) => [Value::Bool(true), Value::Null],
+            Err(e) if strict => bail!(params[0]
+                .span()
+                .error(format!("invalid schema: {e}").as_str())),
+            Err(e) => [Value::Bool(false), Value::String(e.to_string().into())],
+        }
+        .to_vec(),
+    ))
+}
+
+#[cfg(feature = "jsonschema")]
+fn json_match_schema(
+    span: &Span,
+    params: &[Ref<Expr>],
+    args: &[Value],
+    strict: bool,
+) -> Result<Value> {
+    let name = "json.match_schema";
+    ensure_args_count(span, name, params, args, 2)?;
+
+    // The following is expected to succeed.
+    let document: serde_json::Value = serde_json::from_str(&args[0].to_json_str()?)?;
+
+    Ok(Value::from_array(
+        match compile_json_schema(&params[1], &args[1]) {
+            Ok(schema) => match schema.validate(&document) {
+                Ok(_) => [Value::Bool(true), Value::Null],
+                Err(e) => [
+                    Value::Bool(false),
+                    Value::from_array(e.map(|e| Value::String(e.to_string().into())).collect()),
+                ],
+            },
+            Err(e) if strict => bail!(params[1]
+                .span()
+                .error(format!("invalid schema: {e}").as_str())),
+            Err(e) => [Value::Bool(false), Value::String(e.to_string().into())],
+        }
+        .to_vec(),
+    ))
+}