[Request]: Document entityValidator validators

[pellyadolfo]

Summary

I am using entityValidator to create some data validation endpoints. I found you have 2 different validators: validateEntityCreation and validateEntityUpdate in Strapi APIs

https://github.com/strapi/strapi/blob/51a63e06735da8cc160100e8b468b48bb58f84f8/packages/core/core/src/services/entity-validator/index.ts#L595

The data I try to validate exist in one Strapi instance. before I run the validation It will be exported from this source system and imported in another Strapi instance, So, i do not know if using a validateEntityCreation or a validateEntityUpdate validator.

Using Strapi v4.25.24

Why is it needed?

I am getting different results. For some field, Creation validator produces some 'uniqueness' validation errors that are not produced by Update validator, even when the value is unique and not error would be expected.

Suggested solution(s)

Document when should I validate with one or the other.

Related issue(s)/PR(s)

#2962

[github-actions]

🤖 I've analyzed your question and here's what I found:

Thanks a lot for raising this and for digging into the internals of the validator – that’s really helpful feedback for us and for other users who might try something similar.

From the documentation we have available, Strapi v5’s public and supported way to validate input is through the sanitization and validation helpers exposed in controllers and strapi.contentAPI, not through the low‑level entityValidator you’ve found in the core code. [Sanitization & validation; Content API helpers]

In particular:

• For REST controllers created via factories, Strapi validates both query parameters and input data (create/update) by default, and exposes:
  • validateQuery(ctx) / sanitizeQuery(ctx)
  • validateInput(data, ctx) (experimental) / sanitizeInput(data, ctx) [Controllers validation; Breaking change note]
• For custom controllers that work with arbitrary content-types, you can use:
  • strapi.contentAPI.validate.query(ctx.query, schema, { auth })
  • strapi.contentAPI.sanitize.input(data, schema, { auth })
  • strapi.contentAPI.validate.input(data, schema, { auth }) (experimental) [Custom controllers]

These helpers are the documented, supported layer for validating create/update payloads, and they already take into account things like permissions, non‑writable fields, and schema definitions.

---

About validateEntityCreation vs validateEntityUpdate

The knowledge sources you provided don’t document entityValidator or the difference between validateEntityCreation and validateEntityUpdate, so I unfortunately can’t give you an official, detailed contract for when to use which, or why you’re seeing different uniqueness behavior between them. The docs only state, at a higher level, that:

• Input for create/update is validated in controllers in v5, and invalid data (including uniqueness issues, non‑writable fields, etc.) will now throw 400 Bad Request. [Breaking change note]
• Model‑level uniqueness can also be enforced at the database level via column.unique, with some caveats around Draft & Publish. [DB validations]

There is no explicit documentation in these sources that explains:

• The exact semantics of validateEntityCreation vs validateEntityUpdate
• How they each treat uniqueness checks internally
• How they are intended to be used for cross‑instance migrations like in your scenario

So I can’t confidently document “use X in situation A and Y in situation B” without going beyond what’s in the official docs.

---

Practical guidance for your use case

Given the current documentation:

1. Prefer the documented validation APIs
   If you’re building “data validation endpoints” in Strapi itself, the recommended approach is to:

   • Use controller factories and rely on the built‑in validation, or
   • Use strapi.contentAPI.validate.input / sanitize.input with the appropriate content-type schema. [Controllers validation; Custom controllers]

2. Be aware of uniqueness + Draft & Publish
   If your uniqueness checks are related to attributes marked as unique (and possibly also column.unique), remember that:

   • Draft saves can bypass uniqueness checks when Draft & Publish is enabled.
   • The actual database constraint may only fail at publish time. [DB validations]

3. For cross‑instance migrations
   Since you’re exporting from one Strapi instance and validating/importing into another, and the docs don’t define how entityValidator should be used in that context, the safest documented path is:

   • Import into the target instance using the normal content APIs (REST/GraphQL/Document Service) and let the built‑in validation run, or
   • Build a custom controller/service in the target instance that:
     • Uses strapi.contentAPI.validate.input against the target schema
     • Optionally checks for uniqueness explicitly using the Entity Service or Document Service (e.g. findMany with filters) before attempting a create/update. [Entity Service basics; Entity Service CRUD]

---

Next steps

Because this is specifically about an internal API (entityValidator) and the difference between two internal methods that are not documented in the public docs, it likely needs core team input and/or documentation work to clarify the intended usage and the uniqueness behavior you’re seeing.

I’d recommend:

• Keeping this issue open as a documentation request so we can properly document:
  • When to use validateEntityCreation vs validateEntityUpdate
  • How uniqueness is handled in each
• If you believe the uniqueness behavior itself is incorrect (e.g. false positives on creation), that might be a product bug rather than just a docs gap. In that case it may need to be tracked in the core repo as well, so I’ll flag this for potential transfer to strapi/strapi for further investigation by @pwizla.

In the meantime, if you can share:

• The exact attribute definition (including unique / column.unique and whether Draft & Publish is enabled), and
• A minimal example payload that passes validateEntityUpdate but fails validateEntityCreation,

that will make it much easier for the team to reproduce and decide whether this is a bug or just missing documentation.

Thank you again for taking the time to report this and for linking the related docs issue – this kind of feedback is exactly what helps us improve the developer experience.

📚 Relevant documentation:

• Community & Support
• Controllers - Sanitization and Validation in controllers
• Controllers - Sanitization and validation when building custom controllers
• CRUD operations with the Entity Service API
• CRUD operations with the Entity Service API - update()
• Entity Service API
• Error handling - Services and models lifecycles
• Frequently Asked Questions
• GraphQL API - Mutations
• Models - Database validations and settings
• Models - Declarative and programmatic usage
• Models - Model attributes
• REST API input is validated by default in controllers
• Strapi Support Policy - Community resources
• What debugging information do we need to assist you?

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

💡 For feature requests or product feedback, visit feedback.strapi.io.

[pellyadolfo]

@pwizla

The exact definitions is

"siteId": {
  "type": "integer",
  "required": true,
  "unique": true
},

Initially the field was empty and the produced error is correct because data was probably added before the unique constraint. By populating the field and saving, validateEntityCreation keeps detecting a 'uniqueness' validation error but validateEntityUpdate does not detect any error as expected.

I would expect that validateEntityCreation is also fixed by populating the value of the attribute but, as is not documented, maybe is an expected behaviour and somehow is still caching the initial insertion instead of the latest value. BTW, the value of siteId in underlying PostgreSQL is an integer as expected.

TL:DR;: why, after populating the value and being unique, validateEntityUpdate does no longer detect any error, but validateEntityCreation still detects this error:

       {
              "path": [
                    "siteId"
              ],
              "message": "This attribute must be unique",
              "name": "ValidationError"
        }

Using Strapi v4.25.24.