@yrest/cli 0.9.0 → 0.10.0

package/dist/cli/index.mjs

@@ -566,6 +566,36 @@ function normaliseRelationDef(key, value) {
   return null;
 }
 
+// src/storage/parseSchema.ts
+function parseSchema(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const result = {};
+  for (const [collection, fields] of Object.entries(raw)) {
+    if (!fields || typeof fields !== "object" || Array.isArray(fields)) continue;
+    result[collection] = {};
+    for (const [field, value] of Object.entries(fields)) {
+      const def = normaliseFieldDef(value);
+      if (def) result[collection][field] = def;
+    }
+  }
+  return result;
+}
+function normaliseFieldDef(value) {
+  if (value === "required") return { required: true };
+  if (value === "optional") return { required: false };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const v = value;
+  const def = {};
+  if (v["required"] === true || v["required"] === false) def.required = v["required"];
+  if (typeof v["type"] === "string" && ["string", "integer", "number", "boolean", "object", "array"].includes(v["type"]))
+    def.type = v["type"];
+  if (typeof v["format"] === "string") def.format = v["format"];
+  if (Array.isArray(v["enum"])) def.enum = v["enum"];
+  if (typeof v["description"] === "string") def.description = v["description"];
+  if (v["default"] !== void 0) def.default = v["default"];
+  return def;
+}
+
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
   return Object.fromEntries(
@@ -577,10 +607,12 @@ function deepCopyData(source) {
 function createYrestStorage(filePath) {
   const absPath = resolve2(filePath);
   const raw = parse(readFileSync(absPath, "utf8")) ?? {};
+  const RESERVED = /* @__PURE__ */ new Set(["_rel", "_routes", "_schema"]);
   const relations = parseRelations(raw["_rel"]);
   const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
+  const schema = parseSchema(raw["_schema"]);
   const data = Object.fromEntries(
-    Object.entries(raw).filter(([key]) => key !== "_rel" && key !== "_routes")
+    Object.entries(raw).filter(([key]) => !RESERVED.has(key))
   );
   let snapshot = {
     data: deepCopyData(data),
@@ -594,6 +626,9 @@ function createYrestStorage(filePath) {
     getRelations() {
       return relations;
     },
+    getSchema() {
+      return schema;
+    },
     getRoutes() {
       return routes;
     },
@@ -616,7 +651,7 @@ function createYrestStorage(filePath) {
       const fresh = parse(readFileSync(absPath, "utf8")) ?? {};
       const freshRelations = parseRelations(fresh["_rel"]);
       const freshData = Object.fromEntries(
-        Object.entries(fresh).filter(([key]) => key !== "_rel" && key !== "_routes")
+        Object.entries(fresh).filter(([key]) => !RESERVED.has(key))
       );
       for (const key of Object.keys(data)) delete data[key];
       Object.assign(data, freshData);
@@ -728,7 +763,7 @@ function endpointRow(method, path, desc) {
 }
 function resourceAccordion(name, base, isOpen) {
   const p = `${base}/${name}`;
-  const singular = name.endsWith("s") ? name.slice(0, -1) : name;
+  const singular2 = name.endsWith("s") ? name.slice(0, -1) : name;
   const rows = [
     endpointRow(
       "GET",
@@ -738,20 +773,20 @@ function resourceAccordion(name, base, isOpen) {
     endpointRow(
       "POST",
       p,
-      `Create a new ${singular}. Auto-assigns <code>id</code> if not provided.`
+      `Create a new ${singular2}. Auto-assigns <code>id</code> if not provided.`
     ),
-    endpointRow("GET", `${p}/:id`, `Get a single ${singular} by id.`),
+    endpointRow("GET", `${p}/:id`, `Get a single ${singular2} by id.`),
     endpointRow(
       "PUT",
       `${p}/:id`,
-      `Fully replace a ${singular}. Original <code>id</code> is always preserved.`
+      `Fully replace a ${singular2}. Original <code>id</code> is always preserved.`
     ),
     endpointRow(
       "PATCH",
       `${p}/:id`,
-      `Partially update a ${singular} \u2014 only provided fields change.`
+      `Partially update a ${singular2} \u2014 only provided fields change.`
     ),
-    endpointRow("DELETE", `${p}/:id`, `Delete a ${singular} and return it as confirmation.`)
+    endpointRow("DELETE", `${p}/:id`, `Delete a ${singular2} and return it as confirmation.`)
   ].join("");
   return `
   <details class="resource-card" ${isOpen ? "open" : ""}>
@@ -770,13 +805,13 @@ function nestedRoutesAccordion(relations, base) {
     for (const [key, def] of Object.entries(fields)) {
       const nestedBadge = def.nested ? ` ${badge("nested", "#facc15", "#facc1518")}` : "";
       if (def.type === "many2many") {
-        const singular = source.endsWith("s") ? source.slice(0, -1) : source;
+        const singular2 = source.endsWith("s") ? source.slice(0, -1) : source;
         const m2mBadge = badge("many2many", "#818cf8", "#818cf818");
         rows.push(
           endpointRow(
             "GET",
             `${base}/${source}/:id/${key}`,
-            `List ${def.target} linked to a ${singular} via ${def.through}. ${m2mBadge}${nestedBadge}`
+            `List ${def.target} linked to a ${singular2} via ${def.through}. ${m2mBadge}${nestedBadge}`
           )
         );
         const targetSingular = def.target.endsWith("s") ? def.target.slice(0, -1) : def.target;
@@ -902,7 +937,7 @@ function examplesBlock(collections, relations, base, host, options, firstCustomR
   const firstCol = collections[0];
   if (firstCol) {
     const p = `${host}${base}/${firstCol}`;
-    const singular = firstCol.endsWith("s") ? firstCol.slice(0, -1) : firstCol;
+    const singular2 = firstCol.endsWith("s") ? firstCol.slice(0, -1) : firstCol;
     examples.push(
       `# List all ${firstCol}
 curl ${p}`,
@@ -910,17 +945,17 @@ curl ${p}`,
 curl "${p}?name=value"`,
       `# Sort and paginate
 curl "${p}?_sort=id&_order=desc&_page=1&_limit=5"`,
-      `# Get single ${singular}
+      `# Get single ${singular2}
 curl ${p}/1`,
-      `# Create ${singular}
+      `# Create ${singular2}
 curl -X POST ${p} \\
   -H "Content-Type: application/json" \\
   -d '{"name":"example"}'`,
-      `# Partially update ${singular}
+      `# Partially update ${singular2}
 curl -X PATCH ${p}/1 \\
   -H "Content-Type: application/json" \\
   -d '{"name":"updated"}'`,
-      `# Delete ${singular}
+      `# Delete ${singular2}
 curl -X DELETE ${p}/1`
     );
   }
@@ -1656,7 +1691,7 @@ var CustomRouteCommand = class {
         url,
         handler: async (req, reply) => {
           if (route.delay && route.delay > 0) {
-            await new Promise((resolve5) => setTimeout(resolve5, route.delay));
+            await new Promise((resolve6) => setTimeout(resolve6, route.delay));
           }
           if (route.error) {
             const body2 = route.errorBody ?? { error: `Forced error ${route.error}` };
@@ -1844,6 +1879,371 @@ var NestedRouteCommand = class {
   }
 };
 
+// src/openapi/inferSchema.ts
+function buildCollectionSchema(items, fieldDefs = {}) {
+  const sample = items.slice(0, 10);
+  const inferredTypes = /* @__PURE__ */ new Map();
+  for (const item of sample) {
+    for (const [key, value] of Object.entries(item)) {
+      if (!inferredTypes.has(key)) {
+        inferredTypes.set(key, jsToOpenApiType(value));
+      }
+    }
+  }
+  const allFields = /* @__PURE__ */ new Set([...inferredTypes.keys(), ...Object.keys(fieldDefs)]);
+  const properties = {};
+  const required = [];
+  for (const field of allFields) {
+    const def = fieldDefs[field];
+    const inferred = inferredTypes.get(field) ?? "string";
+    const prop = {
+      type: def?.type ?? inferred
+    };
+    if (def?.format) prop.format = def.format;
+    if (def?.description) prop.description = def.description;
+    if (def?.enum) prop.enum = def.enum;
+    if (def?.default !== void 0) prop.default = def.default;
+    properties[field] = prop;
+    if (def?.required === true) required.push(field);
+  }
+  const schema = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+function jsToOpenApiType(value) {
+  if (value === null || value === void 0) return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return "string";
+}
+
+// src/openapi/buildPaths.ts
+var COLLECTION_QUERY_PARAMS = [
+  { name: "_page", in: "query", schema: { type: "integer" }, description: "Page number (1-based)" },
+  { name: "_limit", in: "query", schema: { type: "integer" }, description: "Items per page" },
+  { name: "_sort", in: "query", schema: { type: "string" }, description: "Field name to sort by" },
+  {
+    name: "_order",
+    in: "query",
+    schema: { type: "string", enum: ["asc", "desc"] },
+    description: "Sort direction"
+  },
+  {
+    name: "_q",
+    in: "query",
+    schema: { type: "string" },
+    description: "Full-text search across all scalar fields (case-insensitive)"
+  },
+  {
+    name: "_expand",
+    in: "query",
+    schema: { type: "string" },
+    description: "Embed related parent object inline (e.g. ?_expand=user)"
+  },
+  {
+    name: "_embed",
+    in: "query",
+    schema: { type: "string" },
+    description: "Embed child collection into each item (e.g. ?_embed=posts)"
+  },
+  {
+    name: "_fields",
+    in: "query",
+    schema: { type: "string" },
+    description: "Comma-separated field projection (e.g. ?_fields=id,name)"
+  }
+];
+var ID_PATH_PARAM = {
+  name: "id",
+  in: "path",
+  required: true,
+  schema: { type: "string" },
+  description: "Item id"
+};
+function toOpenApiPath(fastifyPath) {
+  return fastifyPath.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}");
+}
+function extractPathParams(fastifyPath) {
+  const matches = fastifyPath.match(/:([a-zA-Z_][a-zA-Z0-9_]*)/g) ?? [];
+  return matches.map((m) => ({
+    name: m.slice(1),
+    in: "path",
+    required: true,
+    schema: { type: "string" }
+  }));
+}
+function singular(name) {
+  return name.endsWith("s") ? name.slice(0, -1) : name;
+}
+function schemaRef(name) {
+  return { $ref: `#/components/schemas/${name}` };
+}
+function jsonContent(schema) {
+  return { "application/json": { schema } };
+}
+function ok(schema, description = "OK") {
+  return { description, content: jsonContent(schema) };
+}
+function buildCrudPaths(collection, base, schemaName) {
+  const ref = schemaRef(schemaName);
+  const tag = collection;
+  const sing = singular(collection);
+  const collPath = `${base}/${collection}`;
+  const itemPath = `${base}/${collection}/{id}`;
+  return {
+    [collPath]: {
+      get: {
+        summary: `List ${collection}`,
+        tags: [tag],
+        parameters: COLLECTION_QUERY_PARAMS,
+        responses: {
+          "200": {
+            description: "OK",
+            content: jsonContent({ type: "array", items: ref }),
+            headers: {
+              "X-Total-Count": {
+                description: "Total items (when using ?_page / ?_limit)",
+                schema: { type: "integer" }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        summary: `Create ${sing}`,
+        tags: [tag],
+        requestBody: { required: true, content: jsonContent(ref) },
+        responses: { "201": ok(ref, "Created") }
+      }
+    },
+    [itemPath]: {
+      get: {
+        summary: `Get ${sing}`,
+        tags: [tag],
+        parameters: [
+          ID_PATH_PARAM,
+          ...COLLECTION_QUERY_PARAMS.filter(
+            (p) => ["_expand", "_embed", "_fields"].includes(p.name)
+          )
+        ],
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      put: {
+        summary: `Replace ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        requestBody: { required: true, content: jsonContent(ref) },
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      patch: {
+        summary: `Update ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        requestBody: { required: false, content: jsonContent(ref) },
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      delete: {
+        summary: `Delete ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        responses: { "200": ok(ref, "Deleted item returned"), "404": { description: "Not found" } }
+      }
+    }
+  };
+}
+function buildRelationPaths(relations, base) {
+  const paths = {};
+  for (const [source, fields] of Object.entries(relations)) {
+    for (const [key, def] of Object.entries(fields)) {
+      if (def.type === "many2many") {
+        const forwardPath = `${base}/${source}/{id}/${key}`;
+        const inversePath = `${base}/${def.target}/{id}/${source}`;
+        paths[forwardPath] = {
+          get: {
+            summary: `List ${def.target} linked to ${singular(source)} via ${def.through}`,
+            tags: [source],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": {
+                description: "OK",
+                content: jsonContent({ type: "array", items: { type: "object" } })
+              },
+              "404": { description: `${singular(source)} not found` }
+            }
+          }
+        };
+        paths[inversePath] = {
+          get: {
+            summary: `List ${source} linked to ${singular(def.target)} via ${def.through} (inverse)`,
+            tags: [def.target],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": {
+                description: "OK",
+                content: jsonContent({ type: "array", items: { type: "object" } })
+              },
+              "404": { description: `${singular(def.target)} not found` }
+            }
+          }
+        };
+      } else {
+        const parentSing = singular(def.target);
+        const collPath = `${base}/${def.target}/{id}/${source}`;
+        const isOne2One = def.type === "one2one";
+        const responseSchema = isOne2One ? { type: "object" } : { type: "array", items: { type: "object" } };
+        paths[collPath] = {
+          get: {
+            summary: isOne2One ? `Get ${singular(source)} belonging to ${parentSing}` : `List ${source} belonging to ${parentSing}`,
+            tags: [def.target],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": { description: "OK", content: jsonContent(responseSchema) },
+              "404": { description: `${parentSing} not found` }
+            }
+          }
+        };
+        if (!isOne2One) {
+          const itemPath = `${base}/${def.target}/{id}/${source}/{childId}`;
+          paths[itemPath] = {
+            get: {
+              summary: `Get single ${singular(source)} scoped to ${parentSing}`,
+              tags: [def.target],
+              parameters: [
+                ID_PATH_PARAM,
+                { name: "childId", in: "path", required: true, schema: { type: "string" } }
+              ],
+              responses: {
+                "200": { description: "OK", content: jsonContent({ type: "object" }) },
+                "404": { description: "Not found" }
+              }
+            }
+          };
+        }
+      }
+    }
+  }
+  return paths;
+}
+function buildCustomRoutePaths(routes, base) {
+  const paths = {};
+  for (const route of routes) {
+    const openApiPath = toOpenApiPath(`${base}${route.path}`);
+    const method = route.method.toLowerCase();
+    const pathParams = extractPathParams(route.path);
+    const responses = {};
+    if (route.error) {
+      responses[String(route.error)] = { description: `Forced error ${route.error}` };
+    } else {
+      const statuses = /* @__PURE__ */ new Set();
+      for (const s of route.scenarios ?? []) statuses.add(s.response.status ?? 200);
+      if (route.otherwise) statuses.add(route.otherwise.status ?? 200);
+      if (route.response) statuses.add(route.response.status ?? 200);
+      if (statuses.size === 0) statuses.add(200);
+      for (const status of statuses) {
+        const bodySource = (route.scenarios ?? []).find((s) => (s.response.status ?? 200) === status)?.response.body ?? (route.otherwise?.status ?? 200) === status ? route.otherwise?.body : route.response?.body;
+        responses[String(status)] = {
+          description: status < 400 ? "OK" : "Error",
+          ...bodySource != null ? { content: jsonContent(inferResponseSchema(bodySource)) } : {}
+        };
+      }
+    }
+    const desc = route.handler ? `Handler: ${route.handler}()` : route.scenarios?.length ? `Conditional scenarios (${route.scenarios.length})` : "Custom static route";
+    const operation = {
+      summary: `${route.method.toUpperCase()} ${route.path}`,
+      description: desc,
+      tags: ["custom"],
+      ...pathParams.length > 0 ? { parameters: pathParams } : {},
+      responses
+    };
+    if (!paths[openApiPath]) paths[openApiPath] = {};
+    paths[openApiPath][method] = operation;
+  }
+  return paths;
+}
+function inferResponseSchema(body) {
+  if (body === null || body === void 0) return {};
+  if (typeof body !== "object" || Array.isArray(body)) return { type: "object" };
+  const properties = {};
+  for (const [key, value] of Object.entries(body)) {
+    properties[key] = { type: jsToOpenApiType2(value) };
+  }
+  return { type: "object", properties };
+}
+function jsToOpenApiType2(value) {
+  if (value === null || value === void 0) return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return "string";
+}
+
+// src/openapi/generateOpenApi.ts
+function generateOpenApi(storage, options, title = "yRest API") {
+  const collections = Object.keys(storage.getData());
+  const relations = storage.getRelations();
+  const schemaBlock = storage.getSchema();
+  const customRoutes = storage.getRoutes();
+  const base = options.base ?? "";
+  const schemas = {};
+  for (const collection of collections) {
+    const items = storage.getCollection(collection) ?? [];
+    const fieldDefs = schemaBlock[collection] ?? {};
+    const schemaName = toSchemaName(collection);
+    schemas[schemaName] = buildCollectionSchema(items, fieldDefs);
+  }
+  const paths = {};
+  for (const collection of collections) {
+    const schemaName = toSchemaName(collection);
+    Object.assign(paths, buildCrudPaths(collection, base, schemaName));
+  }
+  Object.assign(paths, buildRelationPaths(relations, base));
+  Object.assign(paths, buildCustomRoutePaths(customRoutes, base));
+  return {
+    openapi: "3.0.3",
+    info: {
+      title,
+      version: "1.0.0",
+      description: "Generated by yRest from db.yml"
+    },
+    servers: [
+      {
+        url: `http://${options.host}:${options.port}${base}`,
+        description: "yRest mock server"
+      }
+    ],
+    paths,
+    components: { schemas }
+  };
+}
+function toSchemaName(collection) {
+  const withoutS = collection.endsWith("s") ? collection.slice(0, -1) : collection;
+  return withoutS.charAt(0).toUpperCase() + withoutS.slice(1);
+}
+
+// src/router/routes/openapi.routes.ts
+import { stringify as stringify2 } from "yaml";
+var OpenApiRouteCommand = class {
+  constructor(storage, options) {
+    this.storage = storage;
+    this.options = options;
+  }
+  storage;
+  options;
+  register(server) {
+    server.get("/_openapi", (_req, reply) => {
+      const doc = generateOpenApi(this.storage, this.options);
+      reply.header("Content-Type", "text/yaml; charset=utf-8");
+      return reply.send(stringify2(doc, { lineWidth: 0, aliasDuplicateObjects: false }));
+    });
+    server.get("/_openapi.json", (_req, reply) => {
+      return reply.send(generateOpenApi(this.storage, this.options));
+    });
+  }
+};
+
 // src/router/routes/snapshot.routes.ts
 var SnapshotRouteCommand = class {
   constructor(storage) {
@@ -1924,6 +2324,7 @@ async function createServer(storage, options, handlers = /* @__PURE__ */ new Map
   }
   const commands = [
     new AboutRouteCommand(storage, options, handlers),
+    new OpenApiRouteCommand(storage, options),
     ...options.snapshot ? [new SnapshotRouteCommand(storage)] : [],
     new CustomRouteCommand(storage, options.base, handlers),
     ...buildResourceRouteCommands(storage, options)
@@ -2168,7 +2569,7 @@ function registerServe(program2) {
 // src/cli/commands/handler.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4, appendFileSync, writeFileSync as writeFileSync3 } from "fs";
 import { join as join3, resolve as resolve4, basename } from "path";
-import { parse as parse3, stringify as stringify2 } from "yaml";
+import { parse as parse3, stringify as stringify3 } from "yaml";
 var HANDLERS_FILE_HEADER = `// yrest handlers \u2014 loaded via "handlers:" in yrest.config.yml
 // Handler signature: (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>
 // See https://github.com/aggiovato/yaml-rest for full documentation
@@ -2230,7 +2631,7 @@ function registerHandler(program2) {
       const alreadyRegistered = routes.some((r) => r["handler"] === name);
       if (!alreadyRegistered) {
         routes.push({ method: flags.method.toUpperCase(), path: flags.path, handler: name });
-        writeFileSync3(dbPath, stringify2(raw), "utf8");
+        writeFileSync3(dbPath, stringify3(raw), "utf8");
         console.log(`  Added _routes entry to ${basename(dbPath)}`);
       } else {
         console.log(`  Handler "${name}" already in _routes \u2014 skipped`);
@@ -2253,6 +2654,33 @@ function registerHandler(program2) {
   });
 }
 
+// src/cli/commands/openapi.ts
+import { writeFileSync as writeFileSync4 } from "fs";
+import { resolve as resolve5 } from "path";
+import { stringify as stringify4 } from "yaml";
+function registerOpenApi(program2) {
+  program2.command("openapi <file>").description("Generate an OpenAPI 3.0 spec from a db.yml file").option("-o, --output <file>", "Output file (default: openapi.yaml / openapi.json)").option("--format <fmt>", "Output format: yaml (default) or json", "yaml").option("--stdout", "Print to stdout instead of writing a file").option("--base <base>", "Base path prefix applied to all routes", "").option("--port <port>", "Server port shown in the servers block", "3070").option("--host <host>", "Server host shown in the servers block", "localhost").option("--title <title>", "API title for the info block", "yRest API").action((file, opts) => {
+    const storage = createYrestStorage(resolve5(file));
+    const options = yrestOptionsSchema.parse({
+      file,
+      base: opts["base"] || void 0,
+      port: Number(opts["port"]) || 3070,
+      host: opts["host"] || "localhost"
+    });
+    const doc = generateOpenApi(storage, options, opts["title"]);
+    const isJson = opts["format"] === "json";
+    const output = isJson ? JSON.stringify(doc, null, 2) : stringify4(doc, { lineWidth: 0, aliasDuplicateObjects: false });
+    if (opts["stdout"]) {
+      process.stdout.write(output);
+      return;
+    }
+    const defaultFile = isJson ? "openapi.json" : "openapi.yaml";
+    const outFile = resolve5(opts["output"] ?? defaultFile);
+    writeFileSync4(outFile, output, "utf8");
+    console.log(`\u2713  OpenAPI spec written to ${outFile}`);
+  });
+}
+
 // src/cli/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../../package.json");
@@ -2260,4 +2688,5 @@ program.name("yrest").description("Zero-config REST API mock server powered by a
 registerInit(program);
 registerServe(program);
 registerHandler(program);
+registerOpenApi(program);
 program.parse();

package/dist/index.d.mts

@@ -4,6 +4,48 @@ import * as http from 'http';
 
 /** A single REST resource item. Field names and value types are user-defined in the YAML file. */
 type Resource = Record<string, unknown>;
+/**
+ * Descriptor for a single field declared in the `_schema` block.
+ *
+ * All properties are optional — omit what you don't need. Fields not mentioned
+ * in `_schema` are inferred from the collection data and treated as optional.
+ *
+ * Shorthand: `fieldName: required` normalises to `{ required: true }`.
+ */
+type FieldDef = {
+    /** If `true`, the field is listed in the OpenAPI `required` array and (Phase B) validated on POST/PUT. */
+    required?: boolean;
+    /** Explicit type override. If absent, inferred from the data. */
+    type?: "string" | "integer" | "number" | "boolean" | "object" | "array";
+    /** OpenAPI `format` hint (e.g. `email`, `date`, `uuid`, `uri`, `date-time`). */
+    format?: string;
+    /** Restricts the field to a fixed set of values. */
+    enum?: unknown[];
+    /** Human-readable description included in the OpenAPI spec. */
+    description?: string;
+    /** Default value included in the OpenAPI spec. */
+    default?: unknown;
+};
+/**
+ * Field-level schema declarations for one or more collections, parsed from `_schema` in the YAML.
+ *
+ * - Outer key: collection name.
+ * - Inner key: field name within that collection.
+ * - Value: {@link FieldDef} descriptor (or the string shorthand `"required"` / `"optional"`).
+ *
+ * @example
+ * ```yaml
+ * _schema:
+ *   users:
+ *     name: required          # shorthand
+ *     email:
+ *       required: true
+ *       format: email
+ *     age:
+ *       type: integer
+ * ```
+ */
+type SchemaBlock = Record<string, Record<string, FieldDef>>;
 /**
  * The full in-memory database.
  * Keys are collection names (e.g. `"users"`); values are arrays of {@link Resource} items.
@@ -180,6 +222,8 @@ interface YrestStorage {
     getData(): Data;
     /** Returns the relational mappings declared under `_rel`. */
     getRelations(): Relations;
+    /** Returns the field-level schema declarations from `_schema`, or `{}` if absent. */
+    getSchema(): SchemaBlock;
     /**
      * Returns the items in a named collection, or `undefined` if it does not exist.
      *