HttpRequestBody

Package: @opra/common

HttpRequestBody represents the request body declaration on an HttpOperation. It holds one or more HttpMediaType entries (one per supported content type), size limits, and decoding options that control how the adapter reads and validates the incoming body.

---

Inheritance

DocumentElement
└── HttpRequestBody

---

Properties

Property	Type	Description
content	HttpMediaType[]	One entry per supported content type. The adapter selects the matching entry based on the request's Content-Type header.
description	string | undefined	Human-readable description of the request body.
required	boolean | undefined	Whether the body must be present.
maxContentSize	number | undefined	Maximum allowed body size in bytes.
partial	boolean | 'deep' | undefined	Makes all body fields optional. 'deep' applies recursively to nested types.
immediateFetch	boolean | undefined	If true, the adapter reads and buffers the body immediately before calling the handler.
allowPatchOperators	boolean | undefined	Allows _$push / _$pull patch operator fields in the decoded body.
keepKeyFields	boolean | undefined	Keeps key fields even when partial mode would otherwise strip them.
allowNullOptionals	boolean | undefined	When true, optional fields accept null as a valid value in addition to being absent. Without this flag, optional fields only accept undefined (i.e. the field must be omitted entirely).
owner	HttpOperation	The operation this body belongs to.

allowNullOptionals

By default, OPRA treats optional request body fields strictly: a client must either omit the field entirely or supply a valid value. Sending null for an optional field is a validation error.

Set allowNullOptionals: true when clients legitimately need to send null to explicitly clear a field — common in PATCH endpoints where null signals "remove this value" rather than "leave it unchanged".

@(HttpOperation.PATCH({ path: ':id' })
  .PathParam('id', { type: 'integer' })
  .RequestContent('application/json', { partial: true, allowNullOptionals: true })
  .Response(200, { type: Customer }))
async update(ctx: HttpContext) {
  const body = await ctx.getBody<Partial<Customer>>();
  // body.email may be undefined (omitted), a string, or null
}

---

Accessing the request body at runtime

HttpRequestBody is a schema-level descriptor. At request time, read the body through HttpContext:

async create(ctx: HttpContext) {
  const body = await ctx.getBody<Customer>();
}

To inspect the declaration programmatically:

const op = document.httpApi.findOperation('/customers', 'create');
const rb  = op.requestBody;

if (rb) {
  console.log(rb.required);         // true | false | undefined
  console.log(rb.maxContentSize);   // number | undefined
  for (const ct of rb.content) {
    console.log(ct.contentType, ct.type?.name);
  }
}

---

toJSON(options?)

Returns an OpraSchema.HttpRequestBody plain object for schema export.

toJSON(options?: ApiDocument.ExportOptions): OpraSchema.HttpRequestBody

---

→ HttpOperation · HttpMediaType