docs: clarify multipart array validation#627
Open
barry166 wants to merge 1 commit into
Open
Conversation
The docs currently show array validation with shared multipart schemas but do not explain that a single submitted field remains one field object. Adding that note helps users avoid expecting AJV coerceTypes to wrap multipart field objects into arrays. Constraint: Issue fastify#318 was labeled documentation/good first issue and maintainer guidance asked for a docs update. Rejected: Change parser behavior based on route schema | this would require schema introspection and could alter existing multipart body shapes. Confidence: high Scope-risk: narrow Directive: Do not change field grouping semantics from docs-only issues without adding explicit behavior tests. Tested: npm test Tested: npm run test:typescript Tested: git diff --check Not-tested: rendered README preview
There was a problem hiding this comment.
Pull request overview
This docs-only PR clarifies how @fastify/multipart’s attachFieldsToBody output is shaped before JSON Schema validation, and how repeated multipart field names become arrays while a single occurrence stays a single field object—addressing confusion seen in issue #318 around Ajv coerceTypes: 'array'.
Changes:
- Document that multipart field conversion happens before validation.
- Clarify the “single field object vs repeated field array” behavior for repeated field names.
- Provide an
anyOfschema pattern for accepting either a single field object or an array of field objects.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| If provided, the `sharedSchemaId` parameter must be a string ID and a shared schema will be added to your fastify instance so you will be able to apply the validation to your service (like in the example mentioned above). | ||
|
|
||
| Multipart fields are converted before validation. Repeated field names are grouped into arrays, but a field sent once remains a single field object. This means AJV `coerceTypes: 'array'` will not wrap a single multipart field object in an array for a schema like `myFiles: { type: 'array', items: fastify.getSchema('#mySharedSchema') }`. If a field accepts one or more values, validate both the single-value and repeated-value shapes, then normalize the value in your handler if needed: |
Comment on lines
+379
to
+383
| myFiles: { | ||
| anyOf: [ | ||
| { $ref: '#mySharedSchema' }, | ||
| { type: 'array', items: fastify.getSchema('#mySharedSchema') } | ||
| ] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
anyOfschema for accepting either a single shared-schema field or repeated fields.Fixes #318
Verification
npm testnpm run test:typescriptgit diff --checkNotes
AI-assisted: I used Codex to inspect the issue/repository, prepare this docs-only change, and run verification. I manually reviewed the diff and test output before opening the PR.