Deprecating fields in OpenAPI spec via Directus

Help
, ,
1

We’re exploring how to mark fields as deprecated in the OpenAPI spec generated by Directus.
In OpenAPI itself, this is straightforward (using the deprecated property on fields), but we haven’t found a way to configure this through Directus. Ideally, we’d like something like a deprecated: boolean option at the field/schema level in Directus that gets reflected in the generated spec.

From what we can tell:

This doesn’t seem to be supported out of the box in Directus.
There’s no system field/property for marking fields as deprecated.

  • A possible workaround is to post-process the generated OpenAPI spec (e.g. via an extension) and inject the deprecated flag manually.

  • Another lightweight alternative could be indicating deprecation in the field description, but this doesn’t propagate to generated types or tooling.

Our main interest is:

  • Having deprecated fields clearly reflected in generated OpenAPI specs

  • Ensuring downstream tooling (e.g. type generation) can pick this up

Questions:

  1. Is there any built-in or recommended way in Directus to mark fields as deprecated for the OpenAPI spec?

  2. If not, is there a known reason this isn’t supported?

  3. How are others handling field deprecation in Directus-based APIs?

1 Answer

1
2

There’s no built-in way to do this in Directus at the moment. The OpenAPI spec is indeed dynamically generated, and we currently don’t offer an extension point to tap into that generation to add custom metadata or other information. I feel like this would best be implemented as a “deprecated” flag in the core system which would then hide the field in the UI, and add the deprecated metadata in the OpenAPI/GraphQL specs. I’ve jotted down your feature request on our tracker for future consideration :slight_smile: