ata-validator 1.19.0 → 1.21.0

package/index.js

@@ -1461,9 +1461,18 @@ class Validator {
       });
       this._engine = 'interpreter';
       if (!preprocess) this._fastVerdict = (d) => interp.isValid(d);
-      const run = preprocess
-        ? (data) => { preprocess(data); return interp.validate(data); }
-        : (data) => interp.validate(data);
+      // abortEarly is a documented contract, not a property of whichever engine
+      // answered: it promises the frozen ATA9000 stub instead of a detailed
+      // error, so code that branches on it has to behave the same with and
+      // without code generation. Taking the verdict path here also skips
+      // building the errors the caller said it did not want.
+      const run = options.abortEarly
+        ? (preprocess
+            ? (data) => { preprocess(data); return interp.isValid(data) ? VALID_RESULT : ABORT_EARLY_RESULT; }
+            : (data) => (interp.isValid(data) ? VALID_RESULT : ABORT_EARLY_RESULT))
+        : (preprocess
+            ? (data) => { preprocess(data); return interp.validate(data); }
+            : (data) => interp.validate(data));
       this.validate = run;
       this.isValidObject = this._fastVerdict
         ? this._fastVerdict
@@ -2039,6 +2048,9 @@ function compile(schema, opts) {
 const { toTypeScript } = require("./lib/ts-gen");
 const { renderPretty } = require("./lib/render-pretty");
 const { renderCompact } = require("./lib/render-compact");
+const { toOutput } = require("./lib/output-format");
+const { toRetryMessage } = require("./lib/retry-message");
+const { describeSchema } = require("./lib/describe-schema");
 const { renderJSON } = require("./lib/render-json");
 const { suggestFor } = require("./lib/suggestions");
 const { reprValue } = require("./lib/enrich-error");
@@ -2212,7 +2224,12 @@ _defineLazyMethod('isValidObject', (self) => (data) => {
       return r;
     };
   } else {
-    self._ensureCodegen();
+    // `new Function` is a property of the realm, not of the schema: under a
+    // strict CSP or `--disallow-code-generation-from-strings` this throws
+    // rather than declining, and the EvalError reached the caller of a verdict
+    // method. The full compile can answer without code generation, so fall
+    // through to it. The tier-0 branch above already guarded its own call.
+    try { self._ensureCodegen(); } catch { /* no codegen in this realm */ }
     // Codegen can bail on shapes it cannot represent; the full compile
     // binds the native path or the unsupported thrower instead of
     // leaving this stub to re-dispatch to itself.
@@ -2263,6 +2280,9 @@ module.exports = {
   defineSchema,
   renderPretty,
   renderCompact,
+  toOutput,
+  toRetryMessage,
+  describeSchema,
   renderJSON,
   attachSuggestions, // internal: used by the renderers; not public API
 };

package/lib/aot-impl.js

@@ -54,13 +54,26 @@ function safeRePrelude(...fns) {
   return fns.some((f) => f && f._usesSafeRe) ? getSafeRegexEmbed() + '\n' : '';
 }
 
+// A validator can enforce more than its schema says. `withKeywords` from
+// @ata-project/keywords wraps an instance's entry points, and a wrapper
+// declares that by setting `_externalChecks`. The emitters below build their
+// module from the compiled schema alone, so a wrapped instance would emit a
+// module that accepts documents the validator itself rejects. Refuse instead.
+// Declining to compile is recoverable. A module that wrongly accepts is not.
+function assertEmittable(validator, fnName) {
+  if (validator._usesKeywords) {
+    throw new Error(fnName + ': a schema that uses custom keywords cannot be compiled into a standalone module (option "keywords")');
+  }
+  if (validator._externalChecks) {
+    throw new Error(fnName + ': this validator enforces checks that are not in its schema, so a standalone module would be weaker than the validator it came from. Those checks come from a wrapper such as withKeywords() from @ata-project/keywords, and JSON Schema has no spelling for them. Compile the unwrapped validator if the extra checks are not needed.');
+  }
+}
+
 // --- Standalone pre-compilation ---
 // Generate a JS module string that can be written to a file.
 // On next startup, load with Validator.fromStandalone() -- zero compile time.
 function toStandalone(validator) {
-  if (validator._usesKeywords) {
-    throw new Error('toStandalone: a schema that uses custom keywords cannot be compiled into a standalone module (option "keywords")');
-  }
+  assertEmittable(validator, 'toStandalone');
   validator._ensureCompiled();
   const jsFn = validator._jsFn;
   if (!jsFn || !jsFn._source) return null;
@@ -233,9 +246,7 @@ function emitClone(node, access, depth) {
 }
 
 function toStandaloneModule(validator, opts) {
-  if (validator._usesKeywords) {
-    throw new Error('toStandaloneModule: a schema that uses custom keywords cannot be compiled into a standalone module (option "keywords")');
-  }
+  assertEmittable(validator, 'toStandaloneModule');
   validator._ensureCompiled();
   const jsFn = validator._jsFn;
   if (!jsFn || !jsFn._source) return null;
@@ -299,10 +310,39 @@ function toStandaloneModule(validator, opts) {
     if (lines.length) closureDecls = lines.join('\n') + '\n';
   }
 
+  // A few helpers are self-contained and named the same wherever they appear,
+  // the email check being the big one at about 2.7 KB. The boolean function
+  // and the error function each hoisted their own copy, so every module that
+  // used a format carried it twice. They are declared once at module scope
+  // here and removed from both bodies. Everything else in the preamble stays
+  // where it is: emitConstant and the generated branch checks name things per
+  // compilation, and two of them at module scope would collide.
+  const sharedDecls = [];
+  {
+    const seen = new Set();
+    for (const fn of [jsFn, jsErrFn]) {
+      if (!fn || !fn._sharedHelpers) continue;
+      for (const h of fn._sharedHelpers) if (!seen.has(h)) { seen.add(h); sharedDecls.push(h); }
+    }
+    if (sharedDecls.length && errCore) {
+      for (const h of sharedDecls) errCore = errCore.split(h).join('');
+    }
+  }
+  const sharedBlock = sharedDecls.length ? sharedDecls.join('\n') + '\n' : '';
+
   // Hoisted oneOf/anyOf branch checks live in the boolean fn's preamble (the
   // runtime emits them before the function). The standalone module must declare
   // them at module scope too, or _fn references undefined names (e.g. _af1_b0).
-  const preambleDecls = jsFn._preambleSource ? jsFn._preambleSource + '\n' : '';
+  const sharedSet = new Set(sharedDecls);
+  const preambleParts = jsFn._preambleParts
+    ? jsFn._preambleParts.filter((part) => !sharedSet.has(part))
+    : null;
+  const preambleBody = preambleParts !== null
+    ? (preambleParts.length ? preambleParts.join('\n  ') + '\n  ' : '')
+    : (jsFn._preambleSource || '');
+  const preambleDecls = preambleBody || (jsFn._preambleGuard || '')
+    ? (jsFn._preambleParts ? (jsFn._preambleGuard || '') + preambleBody : preambleBody) + '\n'
+    : '';
 
   // User-supplied format functions are referenced as _uf_<name> by both the
   // boolean (_fn) and error (errFn) bodies. Embed them via Function#toString
@@ -353,7 +393,7 @@ const ABORT = Object.freeze({
     path: '',
   })]),
 });
-${closureDecls}${preambleDecls}${formatDecls}const _fn = function(d) {
+${closureDecls}${sharedBlock}${preambleDecls}${formatDecls}const _fn = function(d) {
   ${src}
 };
 ${errCore}function isValid(data) { return _fn(data); }
@@ -404,11 +444,14 @@ function bundleStandalone(Validator, schemas, opts) {
   const R = 'Object.freeze({valid:true,errors:Object.freeze([])})';
   let bundleUsesSafeRe = false;
   let bundleInjects = false;
-  const fns = schemas.map((schema) => {
+  // Pass one compiles; pass two emits. The helpers that several schemas hoist
+  // are the same text declaring the same name, so the bundle keeps one copy at
+  // module scope, and pass two needs to know the set before it writes anything.
+  const compiledEntries = schemas.map((schema) => {
     const v = new Validator(schema, bundleOpts);
     v._ensureCompiled();
     const jsFn = v._jsFn;
-    if (!jsFn || !jsFn._hybridSource) return 'null';
+    if (!jsFn || !jsFn._hybridSource) return null;
     // The schema the validator compiled, not the one the caller passed. They
     // differ whenever anything prepared the schema: draft-07 normalization,
     // `format` removed under assertFormat: false, keywords outside the
@@ -420,10 +463,30 @@ function bundleStandalone(Validator, schemas, opts) {
       v._userFormats,
     );
     if (jsFn._usesSafeRe || (jsErrFn && jsErrFn._usesSafeRe)) bundleUsesSafeRe = true;
-    const errBody =
+    return { v, jsFn, jsErrFn };
+  });
+
+  const sharedDecls = [];
+  {
+    const seen = new Set();
+    for (const e of compiledEntries) {
+      if (!e) continue;
+      for (const fn of [e.jsFn, e.jsErrFn]) {
+        if (!fn || !fn._sharedHelpers) continue;
+        for (const h of fn._sharedHelpers) if (!seen.has(h)) { seen.add(h); sharedDecls.push(h); }
+      }
+    }
+  }
+  const sharedSet = new Set(sharedDecls);
+
+  const fns = compiledEntries.map((e) => {
+    if (!e) return 'null';
+    const { v, jsFn, jsErrFn } = e;
+    let errBody =
       jsErrFn && jsErrFn._errSource
         ? jsErrFn._errSource
         : "return{valid:false,errors:[{code:'error',path:'',message:'validation failed'}]}";
+    for (const h of sharedDecls) errBody = errBody.split(h).join('');
     // Custom format closures: embedded, or bound to the bundle-level
     // registry when opts.formats is 'inject'.
     let preamble = '';
@@ -433,11 +496,14 @@ function bundleStandalone(Validator, schemas, opts) {
       if (f.exportsSetFormats) bundleInjects = true;
     }
     // Include hoisted anyOf/oneOf branch helpers (e.g. `_af1_b0`) so the
-    // bundle output is self-contained. `toStandalone` emits this same source
-    // for single-schema standalone output.
-    if (jsFn._preambleSource) {
-      preamble = preamble ? `${preamble}\n${jsFn._preambleSource}` : jsFn._preambleSource;
-    }
+    // bundle output is self-contained, minus anything lifted to module scope.
+    const kept = jsFn._preambleParts
+      ? jsFn._preambleParts.filter((part) => !sharedSet.has(part))
+      : null;
+    const preambleSrc = kept !== null
+      ? (jsFn._preambleGuard || '') + (kept.length ? kept.join('\n  ') + '\n  ' : '')
+      : (jsFn._preambleSource || '');
+    if (preambleSrc) preamble = preamble ? `${preamble}\n${preambleSrc}` : preambleSrc;
     if (opts && opts.verbose) {
       // Embed the schema and a small resolver so errors carry parentSchema.
       const schemaLit = JSON.stringify(v._schemaObj);
@@ -446,7 +512,8 @@ function bundleStandalone(Validator, schemas, opts) {
     return `(function(R){${preamble}var E=function(d){var _all=true;${errBody}};return function(d){${jsFn._hybridSource}}})(R)`;
   });
   const arr = `[${fns.join(',')}]`;
-  const safeEmbed = bundleUsesSafeRe ? getSafeRegexEmbed() + '\n' : '';
+  const safeEmbed = (bundleUsesSafeRe ? getSafeRegexEmbed() + '\n' : '') +
+    (sharedDecls.length ? sharedDecls.join('\n') + '\n' : '');
   const registry = bundleInjects
     ? `var __formats=Object.create(null);\nfunction setFormats(map){for(var k in map)__formats[k]=map[k]}\n`
     : '';
@@ -489,16 +556,43 @@ function bundleCompact(Validator, schemas, opts) {
     // Hoisted anyOf/oneOf branch helpers (e.g. `_af1_b0`) must travel with the
     // hybrid body or it references undefined names. Prepending keeps dedup honest:
     // schemas with different branch sets no longer collide on body alone.
-    const hybrid = jsFn._preambleSource
-      ? `${jsFn._preambleSource}\n${jsFn._hybridSource}`
-      : jsFn._hybridSource;
     return {
-      hybrid,
+      guard: jsFn._preambleGuard || '',
+      parts: jsFn._preambleParts || null,
+      preamble: jsFn._preambleSource || '',
+      hybridBody: jsFn._hybridSource,
       err: jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : null,
       fmt: jsFn._formatClosures || null,
+      shared: [
+        ...(jsFn._sharedHelpers || []),
+        ...((jsErrFn && jsErrFn._sharedHelpers) || []),
+      ],
     };
   });
 
+  // A helper hoisted by several schemas is the same text declaring the same
+  // name, so the bundle holds one copy at module scope rather than one per
+  // schema. The rest of each preamble stays with its schema: those names are
+  // per compilation and would collide.
+  const sharedDecls = [];
+  {
+    const seen = new Set();
+    for (const e of entries) {
+      if (!e) continue;
+      for (const h of e.shared) if (!seen.has(h)) { seen.add(h); sharedDecls.push(h); }
+    }
+  }
+  const sharedSet = new Set(sharedDecls);
+  for (const e of entries) {
+    if (!e) continue;
+    const kept = e.parts ? e.parts.filter((part) => !sharedSet.has(part)) : null;
+    const preamble = kept !== null
+      ? e.guard + (kept.length ? kept.join('\n  ') + '\n  ' : '')
+      : e.preamble;
+    e.hybrid = preamble ? `${preamble}\n${e.hybridBody}` : e.hybridBody;
+    if (e.err) for (const h of sharedDecls) e.err = e.err.split(h).join('');
+  }
+
   // Deduplicate function bodies — many schemas produce identical or near-identical code
   const bodyMap = new Map(); // body → index
   const bodies = [];
@@ -531,6 +625,7 @@ function bundleCompact(Validator, schemas, opts) {
     ? '// Auto-generated by ata-validator — do not edit\n'
     : "'use strict';\n";
   if (bundleUsesSafeRe) out += getSafeRegexEmbed() + '\n';
+  if (sharedDecls.length) out += sharedDecls.join('\n') + '\n';
   const declKW = isEsm ? 'const' : 'var';
   out += `${declKW} R=Object.freeze({valid:true,errors:Object.freeze([])});\n`;
 

package/lib/branch-collapse.js

@@ -1,6 +1,23 @@
 'use strict';
 
-const SEVERITY = {
+// Branch collapse: when no branch of an anyOf or oneOf matches, listing every
+// branch's errors tells a reader that nothing fit without telling them which
+// branch they meant. This scores the branches, reports the one that came
+// closest, and keeps its errors under `branchErrors` for the pretty renderer.
+//
+// There is one implementation, and it is `__ataCollapse` below. A standalone
+// module imports nothing, so the generated code cannot require this file; it
+// carries a copy emitted by `embedSource()` from these very functions instead
+// of a second hand-written one. That is why the internals are written in the
+// positional form the generated code calls, and why `__ataCollapse` may close
+// over nothing but `__ataScore` and the severity table: whatever it reaches
+// has to be in the embed too.
+
+// How much a failing keyword says about intent. A branch that fails on `type`
+// was probably not the branch the author meant; one that fails on `minLength`
+// probably was, and is the better thing to show. The error count dominates, so
+// a branch with one complaint always beats a branch with three.
+const __ATA_SEVERITY = {
   type: 10,
   const: 8,
   enum: 8,
@@ -15,61 +32,69 @@ const SEVERITY = {
   unevaluatedProperties: 2,
   unevaluatedItems: 2,
 };
-const DEFAULT_SEVERITY = 4;
 
-function scoreBranch (errors) {
-  if (!errors || errors.length === 0) return 0;
-  let sum = 0;
-  for (const e of errors) sum += SEVERITY[e.keyword] || DEFAULT_SEVERITY;
-  return errors.length * 100 + sum; // primary: count, secondary: severity
+function __ataScore (errs) {
+  if (!errs || !errs.length) return 0;
+  let s = 0;
+  for (const e of errs) s += __ATA_SEVERITY[e.keyword] || 4;
+  return errs.length * 100 + s; // primary: count, secondary: severity
 }
 
-/**
- * Given an array of branch result objects ({ valid, errors }) for a oneOf
- * or anyOf, pick the best branch and emit a single user-facing error.
- *
- * @param keyword 'oneOf' | 'anyOf'
- * @param branchResults Array<{ valid, errors, title? }>
- * @param parentPath JSON pointer to the data location
- * @param parentSchemaPath JSON pointer to the keyword in the schema
- * @returns A ValidationError-shaped object, or null if branch passed (caller treats as success).
- */
-function collapseBranches ({ keyword, branchResults, parentPath, parentSchemaPath }) {
-  const passing = branchResults.filter(b => b.valid);
-  if (keyword === 'oneOf') {
-    if (passing.length === 1) return null;
-    if (passing.length > 1) {
+// `br` is one entry per branch in declaration order: {valid, errors, title}.
+// Returns the single error to report, or null when the keyword is satisfied.
+function __ataCollapse (kw, br, pp, sp, o) {
+  const pass = br.filter((b) => b.valid);
+  if (kw === 'oneOf') {
+    if (pass.length === 1) return null;
+    if (pass.length > 1) {
+      const passIdx = [];
+      for (let i = 0; i < br.length; i++) if (br[i].valid) passIdx.push(i);
       return {
-        code: 'ATA4002', keyword: 'oneOf', path: parentPath || '',
-        message: `value matched ${passing.length} of ${branchResults.length} oneOf variants, expected exactly one`,
-        schemaPath: parentSchemaPath,
-        params: { matched: passing.length, total: branchResults.length },
+        code: 'ATA4002',
+        keyword: 'oneOf',
+        instancePath: pp || '',
+        path: pp || '',
+        schemaPath: sp,
+        _o: o,
+        message: 'value matched ' + pass.length + ' of ' + br.length + ' oneOf variants, expected exactly one',
+        params: { passingSchemas: passIdx },
       };
     }
-    // 0 matched, find best
-    return buildBranchError('ATA4001', 'oneOf', branchResults, parentPath, parentSchemaPath);
+  } else if (pass.length >= 1) {
+    return null;
   }
-  // anyOf
-  if (passing.length >= 1) return null;
-  return buildBranchError('ATA4003', 'anyOf', branchResults, parentPath, parentSchemaPath);
-}
-
-function buildBranchError (code, keyword, branchResults, parentPath, parentSchemaPath) {
-  let bestIdx = 0;
-  let bestScore = Infinity;
-  for (let i = 0; i < branchResults.length; i++) {
-    const s = scoreBranch(branchResults[i].errors);
-    if (s < bestScore) { bestScore = s; bestIdx = i; }
+  let bi = 0;
+  let bs = Infinity;
+  for (let i = 0; i < br.length; i++) {
+    const s = __ataScore(br[i].errors);
+    if (s < bs) { bs = s; bi = i; }
   }
-  const best = branchResults[bestIdx];
-  const variantName = best.title || `variant ${bestIdx + 1}`;
+  const best = br[bi];
   return {
-    code, keyword, path: parentPath || '',
-    message: `value matched 0 of ${branchResults.length} ${keyword} variants`,
-    schemaPath: parentSchemaPath,
-    params: { variants: branchResults.length, closest: bestIdx, closestName: variantName },
-    branchErrors: best.errors, // surfaced in pretty render
+    code: kw === 'oneOf' ? 'ATA4001' : 'ATA4003',
+    keyword: kw,
+    instancePath: pp || '',
+    path: pp || '',
+    schemaPath: sp,
+    _o: o,
+    message: 'value matched 0 of ' + br.length + ' ' + kw + ' variants',
+    params: { variants: br.length, closest: bi, closestName: best.title || ('variant ' + (bi + 1)) },
+    branchErrors: best.errors,
   };
 }
 
-module.exports = { collapseBranches, scoreBranch, SEVERITY };
+// The named-argument form the interpreter and the tests call.
+function collapseBranches ({ keyword, branchResults, parentPath, parentSchemaPath, ordinal }) {
+  return __ataCollapse(keyword, branchResults, parentPath, parentSchemaPath, ordinal === undefined ? null : ordinal);
+}
+
+// The three declarations as source, for the generated code to carry. Derived
+// from the functions above rather than written out again, so a fix to one
+// cannot miss the other. `tests/test_branch_collapse.js` runs both.
+function embedSource () {
+  return 'const __ATA_SEVERITY=' + JSON.stringify(__ATA_SEVERITY) + ';' +
+    'const __ataScore=' + __ataScore.toString() + ';' +
+    'const __ataCollapse=' + __ataCollapse.toString() + ';';
+}
+
+module.exports = { collapseBranches, scoreBranch: __ataScore, SEVERITY: __ATA_SEVERITY, embedSource };

package/lib/describe-schema.js

@@ -0,0 +1,176 @@
+'use strict';
+
+// Schema -> the description to put in a model's prompt.
+//
+// Everyone hand-writes a prose description of the shape they want and keeps it
+// next to a schema that enforces something slightly different. The two drift,
+// quietly, because nothing checks one against the other. This derives the
+// first from the second.
+//
+// It is not a style preference. Measured on one model, first attempt only, 30
+// documents, no retry:
+//
+//   nothing but the task                    0 of 30 valid
+//   a field list written by hand            0 of 30
+//   a careful description written by hand   0 of 30
+//   this                                   23 of 30
+//
+// The careful hand-written one failed on exactly two fields, in all 30 cases:
+// the two whose values are an internal vocabulary. A person writes "the
+// settlement status, uppercase with underscores" because a person describes
+// fields. Those values cannot be described, only listed, and a generator lists
+// them.
+//
+// Scope follows lib/ts-gen.js, which walks the same shapes: properties and
+// required, arrays, enum and const, oneOf/anyOf/allOf, and $ref into local
+// $defs. Anything else is described as `any` rather than guessed at.
+
+const MAX_DEPTH = 12;
+
+function lit (v) {
+  try { return JSON.stringify(v); } catch (_) { return String(v); }
+}
+
+function resolveRef (schema, defs) {
+  const m = typeof schema.$ref === 'string' && schema.$ref.match(/^#\/(?:\$defs|definitions)\/(.+)$/);
+  if (m && defs && defs[m[1]]) return defs[m[1]];
+  return null;
+}
+
+// The constraints worth stating to a model, in the order a reader wants them:
+// what it is, then which values, then how big.
+function constraintsOf (s) {
+  const out = [];
+  if (Array.isArray(s.enum)) out.push('one of ' + s.enum.map(lit).join(', '));
+  else if (s.const !== undefined) out.push('exactly ' + lit(s.const));
+  else if (s.type) out.push(Array.isArray(s.type) ? s.type.join(' or ') : s.type);
+
+  if (typeof s.format === 'string') out.push(s.format + ' format');
+  if (typeof s.pattern === 'string') out.push('matching ' + s.pattern);
+
+  const range = (min, max, unit) => {
+    if (min !== undefined && max !== undefined) out.push(`${min} to ${max}${unit}`);
+    else if (min !== undefined) out.push(`at least ${min}${unit}`);
+    else if (max !== undefined) out.push(`at most ${max}${unit}`);
+  };
+  range(s.minLength, s.maxLength, ' characters');
+  range(s.minimum, s.maximum, '');
+  range(s.minItems, s.maxItems, ' items');
+  if (s.exclusiveMinimum !== undefined) out.push('greater than ' + s.exclusiveMinimum);
+  if (s.exclusiveMaximum !== undefined) out.push('less than ' + s.exclusiveMaximum);
+  if (typeof s.multipleOf === 'number') out.push(multipleOfPhrase(s.multipleOf));
+  if (s.uniqueItems === true) out.push('all items different');
+  if (typeof s.description === 'string' && s.description) out.push(s.description);
+  return out;
+}
+
+// `multipleOf: 0.01` is how a schema says "money". A model acts on "rounded to
+// 2 decimal places" and does not reliably act on "a multiple of 0.01": in the
+// measurement behind this file, that one phrase was most of the gap between
+// this output and a careful description written by a person.
+function multipleOfPhrase (m) {
+  if (m > 0 && m < 1) {
+    const places = Math.round(Math.log10(1 / m));
+    if (Math.abs(Math.pow(10, -places) - m) < Number.EPSILON * 8) {
+      return `rounded to ${places} decimal place${places === 1 ? '' : 's'}`;
+    }
+  }
+  return 'a multiple of ' + m;
+}
+
+function isObjectSchema (s) {
+  return s && typeof s === 'object' && s.properties && typeof s.properties === 'object';
+}
+
+function describeObjectBody (schema, depth, defs, lines) {
+  const pad = '  '.repeat(depth);
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  for (const [key, sub] of Object.entries(schema.properties)) {
+    describeNode(sub, key + (required.has(key) ? '' : ' (optional)'), depth, defs, lines);
+  }
+  for (const key of required) {
+    if (!(key in schema.properties)) lines.push(`${pad}${key}: required, any`);
+  }
+  if (schema.additionalProperties === false) lines.push(`${pad}no other fields`);
+}
+
+function describeNode (schema, label, depth, defs, lines) {
+  const pad = '  '.repeat(depth);
+  if (schema === true || schema === undefined) { lines.push(`${pad}${label}: any`); return; }
+  if (schema === false) { lines.push(`${pad}${label}: nothing is allowed here`); return; }
+  if (typeof schema !== 'object' || schema === null || depth > MAX_DEPTH) {
+    lines.push(`${pad}${label}: any`);
+    return;
+  }
+
+  const target = schema.$ref ? resolveRef(schema, defs) : null;
+  if (target) { describeNode(target, label, depth, defs, lines); return; }
+
+  // allOf is the intersection, so its parts describe the same value.
+  if (Array.isArray(schema.allOf) && schema.allOf.length) {
+    const merged = Object.assign({}, schema);
+    delete merged.allOf;
+    for (const part of schema.allOf) {
+      const resolved = part && part.$ref ? resolveRef(part, defs) || part : part;
+      if (resolved && typeof resolved === 'object') Object.assign(merged, resolved, {
+        properties: Object.assign({}, merged.properties, resolved.properties),
+        required: [].concat(merged.required || [], resolved.required || []),
+      });
+    }
+    if (!merged.properties) delete merged.properties;
+    if (!merged.required || !merged.required.length) delete merged.required;
+    describeNode(merged, label, depth, defs, lines);
+    return;
+  }
+
+  const alternatives = schema.oneOf || schema.anyOf;
+  if (Array.isArray(alternatives) && alternatives.length) {
+    lines.push(`${pad}${label}: one of the following shapes`);
+    alternatives.forEach((alt, i) => describeNode(alt, `option ${i + 1}`, depth + 1, defs, lines));
+    return;
+  }
+
+  if (isObjectSchema(schema)) {
+    const own = constraintsOf(schema).filter((c) => c !== 'object');
+    lines.push(`${pad}${label}: object${own.length ? ` (${own.join(', ')})` : ''}`);
+    describeObjectBody(schema, depth + 1, defs, lines);
+    return;
+  }
+
+  const rawItems = schema.items;
+  if (schema.type === 'array' && rawItems && typeof rawItems === 'object') {
+    const items = rawItems.$ref ? resolveRef(rawItems, defs) || rawItems : rawItems;
+    const own = constraintsOf(schema).filter((c) => c !== 'array');
+    const bounds = own.length ? ` (${own.join(', ')})` : '';
+    // An item that is itself an object gets its fields listed underneath. One
+    // that is a scalar reads better on the same line than as a nested entry
+    // called "item".
+    if (isObjectSchema(items)) {
+      lines.push(`${pad}${label}: array${bounds}, each item is an object:`);
+      describeObjectBody(items, depth + 1, defs, lines);
+      return;
+    }
+    if (items.oneOf || items.anyOf || items.allOf) {
+      lines.push(`${pad}${label}: array${bounds}, each item is:`);
+      describeNode(items, 'item', depth + 1, defs, lines);
+      return;
+    }
+    const inner = constraintsOf(items).join(', ') || 'any';
+    lines.push(`${pad}${label}: array${bounds} of ${inner}`);
+    return;
+  }
+
+  lines.push(`${pad}${label}: ${constraintsOf(schema).join(', ') || 'any'}`);
+}
+
+// describeSchema(schema, opts) -> string
+//   opts.name  what to call the top level (default 'output')
+function describeSchema (schema, opts) {
+  const name = (opts && opts.name) || 'output';
+  const defs = (schema && (schema.$defs || schema.definitions)) || null;
+  const lines = [];
+  describeNode(schema, name, 0, defs, lines);
+  return lines.join('\n');
+}
+
+module.exports = { describeSchema };