The Problem

Current behavior: The OpenAPI document generated by DAB includes schemas for models like EntityName_NoAutoPK (entities without auto-generated primary keys) regardless of the runtime.rest.request-body-strict configuration setting.

Issue #1838 screenshot shows: The OpenAPI document exposes Book_NoAutoPK schema even though it may not be necessary depending on strictness settings.

Understanding `request-body-strict`

The request-body-strict configuration controls whether DAB allows extraneous fields in REST request bodies:

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api",
      "request-body-strict": true  // Default: true
    }
  }
}

When true (strict mode - DEFAULT):

Request body must contain ONLY valid fields for the entity
Extraneous/extra fields cause a 400 Bad Request error
Read-only fields cannot be included in request bodies

When false (non-strict mode):

Extra fields in the request body are ignored (not cause errors)
Provides more flexibility for clients

How It Works at Runtime

Looking at the request validation code:

/// <summary>
/// Helper method to check if the request body for REST allows extra fields.
/// </summary>
/// <returns>true if extra fields are not allowed in REST request body.</returns>
private bool IsRequestBodyStrict()
{
    if (_runtimeConfigProvider.TryGetConfig(out RuntimeConfig? runtimeConfig))
    {
        return runtimeConfig.IsRequestBodyStrict;
    }

    return true; // Default is strict mode
}

And the validation enforcement:

// There may be unvalidated fields remaining because of extraneous fields in request body
// which are not mapped to the table. We throw an exception only when we operate in strict mode,
// i.e. when extraneous fields are not allowed.
if (unvalidatedFields.Any() && isRequestBodyStrict)
{
    throw new DataApiBuilderException(
        message: "Invalid request body. Either insufficient or extra fields supplied.",
        statusCode: HttpStatusCode.BadRequest,
        subStatusCode: DataApiBuilderException.SubStatusCodes.BadRequest);
}

The Enhancement Request

What DAB currently does in OpenAPI generation:

Creates multiple schema models for each entity regardless of request-body-strict:
- EntityName - Full schema with all fields
- EntityName_NoAutoPK - Schema excluding auto-generated PKs (for POST)
- EntityName_NoPK - Schema excluding all PKs (for PUT/PATCH)

What the enhancement wants:

If request-body-strict: true: Include all schema variations (current behavior)
If request-body-strict: false: Potentially simplify the OpenAPI schema since extra fields are allowed anyway

The current OpenAPI generator doesn't check this setting:

private static OpenApiRequestBody CreateOpenApiRequestBodyPayload(string schemaReferenceId, bool requestBodyRequired)
{
    OpenApiRequestBody requestBody = new()
    {
        Content = new Dictionary<string, OpenApiMediaType>()
        {
            {
                MediaTypeNames.Application.Json,
                new()
                {
                    Schema = new OpenApiSchema()
                    {
                        Reference = new OpenApiReference()
                        {
                            Type = ReferenceType.Schema,
                            Id = schemaReferenceId  // ← Always includes _NoAutoPK, _NoPK variants
                        }
                    }
                }
            }
        },
        Required = requestBodyRequired
    };

    return requestBody;
}

Current Impact

When `request-body-strict: true` (Default)

OpenAPI shows:

Book - Full schema
Book_NoAutoPK - For POST requests (excludes id if auto-generated)
Book_NoPK - For PUT/PATCH (excludes all PKs)

This is accurate because in strict mode, clients must send exactly the right fields.

When `request-body-strict: false`

OpenAPI still shows:

Book - Full schema
Book_NoAutoPK - For POST
Book_NoPK - For PUT/PATCH

This could be misleading because:

Clients might think they can only send those specific fields
In reality, they can send additional fields which will be ignored
The OpenAPI schema doesn't communicate the "extra fields allowed" behavior

Proposed Solution

The enhancement suggests that when request-body-strict: false, the OpenAPI document should:

Option A: Use a more permissive schema
- Set additionalProperties: true on request body schemas
- This tells clients "you can send extra fields"
Option B: Simplify schema generation
- Only create the main EntityName schema
- Skip _NoAutoPK and _NoPK variants since extra fields are allowed anyway
Option C: Add OpenAPI extension
- Include custom property like x-dab-strict-mode: false to document the behavior

Workarounds

Since this is an enhancement request (not implemented yet), here are workarounds:

Workaround 1: Manually Edit the OpenAPI Document

Export the OpenAPI JSON: GET /api/openapi
Modify the schemas to add additionalProperties: true:

{
  "components": {
    "schemas": {
      "Book": {
        "type": "object",
        "properties": { ... },
        "additionalProperties": true  // ← Add this
      }
    }
  }
}

Serve the modified document

Workaround 2: Document in API Description

Add clear documentation in your entity descriptions:

{
  "entities": {
    "Book": {
      "description": "Book entity. NOTE: Extra fields in request body are ignored (request-body-strict: false)",
      "source": { "object": "books", "type": "table" }
    }
  }
}

Workaround 3: Use Strict Mode

If you want accurate OpenAPI documentation, use the default request-body-strict: true:

{
  "runtime": {
    "rest": {
      "request-body-strict": true
    }
  }
}

This ensures the OpenAPI schemas accurately reflect what's accepted.

Workaround 4: Client-Side Documentation

Document the non-strict behavior in your API consumer documentation separately from the OpenAPI spec.

Example of the Issue

Configuration:

{
  "runtime": {
    "rest": {
      "request-body-strict": false  // ← Extra fields allowed
    }
  },
  "entities": {
    "Book": {
      "source": { "object": "books", "type": "table" }
    }
  }
}

OpenAPI shows for POST /api/Book:

requestBody:
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Book_NoAutoPK'  # Only specific fields

Reality:

// This works (normal case)
POST /api/Book
{ "title": "Test", "author_id": 1 }

// This ALSO works (extra fields ignored)
POST /api/Book
{ 
  "title": "Test", 
  "author_id": 1,
  "extra_field": "ignored",
  "another_field": "also ignored"
}

The OpenAPI doc doesn't communicate that the second request is valid.

Summary

Enhancement #2947 requests that DAB's OpenAPI generator respect the request-body-strict configuration to produce more accurate API documentation.

Current state:

✅ Runtime correctly enforces request-body-strict
❌ OpenAPI document doesn't reflect the setting

Desired state:

When request-body-strict: false, OpenAPI should indicate that additional fields are allowed

Best current workaround: Use request-body-strict: true (default) for accurate OpenAPI documentation, or manually document the non-strict behavior for API consumers.

Related issues:

For more code references: GitHub search for "request-body-strict"

[Enh]: Obey "request-body-strict" in OpenAPI #2947

Description

What?

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions