Define a schema

The extract endpoint maps a document to the JSON Schema you provide in the schema field. The schema defines which fields Nutrient DWS Data Extraction API extracts and the shape of the returned output.data object.

Use this guide to understand supported schema keywords, closed-schema behavior, field types, and size limits.

Root requirements

Set the root schema to type: "object". The API rejects any other root type, such as array, with a 400 error:

{
  "type": "object",
  "properties": {
    "invoice_number": { "type": "string", "description": "Invoice identifier" },
    "total_amount": { "type": "number", "description": "Total including tax" }
  },
  "required": ["invoice_number", "total_amount"]
}

Supported keywords

Keep the schema self-contained. The API supports only these keywords.

The API passes pattern, minimum, and maximum to the extraction engine as constraints. Accepting them doesn’t guarantee that every extracted value satisfies them, so validate the output in your application.

The API rejects unsupported keywords, including:

• External or circular $ref references
• Other composition forms, such as allOf, oneOf, or anyOf with two typed branches
• Other validation keywords, such as maxLength
• String format values other than date
• Conditional schemas, such as if, then, and else

Send only the supported keywords listed above.

Closed schemas

The API treats schemas as closed, and it returns only the properties you declare. It processes every object as if you set additionalProperties: false, so undeclared fields don’t appear in the response.

Don’t send additionalProperties in your schema. The API rejects requests that include it.

Use required to mark fields that extraction must always include in its output. The API can omit fields that aren’t required when the document doesn’t contain them.

Field types

Use primitive fields, arrays, and nested objects to model the values you want to extract.

Primitive fields

String, number, integer, and Boolean fields can include a description. String fields also support enum and format: "date":

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["paid", "unpaid", "overdue"],
      "description": "Payment status of the invoice"
    },
    "issue_date": {
      "type": "string",
      "format": "date",
      "description": "Date the invoice was issued"
    },
    "is_tax_exempt": { "type": "boolean" }
  }
}

Array fields

Array fields require an items schema that defines each element. Use arrays for repeated structures, such as invoice line items:

{
  "type": "object",
  "properties": {
    "line_items": {
      "type": "array",
      "description": "One entry per row in the line-item table",
      "items": {
        "type": "object",
        "properties": {
          "description": { "type": "string" },
          "quantity": { "type": "integer" },
          "unit_price": { "type": "number" }
        },
        "required": ["description", "quantity", "unit_price"]
      }
    }
  }
}

Nested objects

Object fields can nest other objects up to the nesting depth limit. Citations mirror the same nesting, so a value at data.vendor.address.city has its citation at metadata.vendor.address.city:

{
  "type": "object",
  "properties": {
    "vendor": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "address": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "country": { "type": "string" }
          }
        }
      }
    }
  }
}

Size limits

Keep the schema within these limits. The API rejects requests that exceed them.

The total node count includes the root object, each property, and each array items schema. These limits describe the schema structure, independent of JSON formatting or the number of extracted array elements.

Write effective descriptions

The description on each field guides the extraction model. Use clear, specific descriptions to improve extraction accuracy.

• Name the field the way it appears in the document, such as “the ‘Bill To’ company name” or “the grand total at the bottom of the invoice.”
• State the expected format when it matters, such as “ISO 4217 currency code” or “two-letter country code.”
• For ambiguous fields, state which value to extract when the document contains several values, such as “the final total after discounts and tax.”

For document-wide guidance that doesn’t fit a single field, use the top-level instructions string. To configure the parse stage that feeds extraction, refer to the parse configuration guide.

Next steps

Use these guides to continue setting up extraction.

• Refer to the extract endpoint overview guide for request formats and response structure.
• Refer to the citations and confidence guide to ground extracted values back to source locations.
• Refer to the parse configuration guide to tune the parse stage that feeds extraction.