diff --git a/README.md b/README.md
index 9491125..72a3cc1 100644
--- a/README.md
+++ b/README.md
@@ -117,22 +117,51 @@ Split documents into semantic chunks perfect for RAG pipelines:
 - Preserves context across chunks
 
 ### Metadata Extraction
-Extract structured data using JSON schemas (OpenAPI spec format recommended):
+Extract structured data using JSON Schema.
+
+Each `schema` must be an object with a top-level `document` key wrapping the JSON
+Schema. Without that wrapper the extraction fails with
+`IllegalArgumentException: Document schema is missing`.
+
 ```python
 result = extract_text_from_file('invoice.pdf', options=ExtractionOptions(
     metadata_schemas=[{
         'id': 'invoice-data',
         'schema': {
-            'invoice_number': 'string',
-            'date': 'string',
-            'total_amount': 'number',
-            'vendor_name': 'string'
+            'document': {
+                'type': 'object',
+                'properties': {
+                    'invoice_number': {'type': 'string', 'description': 'Invoice reference number'},
+                    'date':           {'type': 'string', 'description': 'Invoice date as printed'},
+                    'total_amount':   {'type': 'number', 'description': 'Total amount due'},
+                    'vendor_name':    {'type': 'string', 'description': 'Name of the vendor'}
+                },
+                'required': []
+            }
         }
-    }]
+    }],
+    infer_metadata_schema=False
 ))
 # Returns structured JSON metadata
 ```
 
+Give every property a `type` and a `description` — both materially improve
+extraction accuracy.
+
+Set `infer_metadata_schema=False` when you supply your own schemas, so no schema
+is generated and yours are used as-is. Leave it `True` (the default) to have a
+schema inferred from the document instead.
+
+You may optionally add a sibling `sections` key for per-chunk metadata; omit it
+for document-level extraction only:
+
+```python
+'schema': {
+    'document': { ... },
+    'sections': {'line-items': { ... }}
+}
+```
+
 ### Parsing Instructions
 Guide the extraction with custom instructions:
 ```python
diff --git a/nodejs-api/README.md b/nodejs-api/README.md
index 6afd6c4..d9b0822 100644
--- a/nodejs-api/README.md
+++ b/nodejs-api/README.md
@@ -305,18 +305,28 @@ import type {
   MetadataExtractionStrategySchema
 } from '@vectorize-io/iris';
 
-// Type-safe options with structured schema (OpenAPI spec format)
+// Type-safe options with a JSON Schema.
+// NOTE: `schema` must wrap the JSON Schema in a top-level `document` key.
+// Without it the extraction fails with
+// "IllegalArgumentException: Document schema is missing".
 const options: ExtractionOptions = {
   chunkSize: 512,
   parsingInstructions: 'Extract code blocks',
   metadataSchemas: [{
     id: 'doc-meta',
     schema: {
-      title: 'string',
-      author: 'string',
-      date: 'string'
+      document: {
+        type: 'object',
+        properties: {
+          title:  { type: 'string', description: 'Document title' },
+          author: { type: 'string', description: 'Author name' },
+          date:   { type: 'string', description: 'Publication date as printed' }
+        },
+        required: []
+      }
     }
   }],
+  inferMetadataSchema: false,
   pollInterval: 2000,
   timeout: 300000
 };