GraphQL schema accessibility metadata handling in Apollo Server 4 when using a custom @accessible directive

Directive Behavior in Apollo Server 4

In Apollo Server 4, a custom @accessible directive can be defined in your schema, but it cannot be used as a primary mechanism to pass accessibility metadata to clients via standard introspection. While the server recognizes the directive's existence, it does not expose the application of that directive to individual fields during introspection queries.

Introspection and Visibility

• Schema Definition: The @accessible directive will appear in the __schema.directives list, confirming that the server knows the directive exists and understands its valid locations.
• Field-Level Usage: Standard GraphQL introspection does not include a directives field on __Field or __EnumValue. Consequently, a client querying for field metadata will not see which fields are marked with @accessible.
• Tooling: Because Apollo Studio relies on standard introspection, it will not surface field-level directive metadata in its UI.

Error Payloads and Metadata

Apollo Server 4 does not automatically inject directive metadata into error responses. The default error payload contains only message, locations, and path. To include accessibility-focused properties (like ARIA labels for a specific failing field) in an error, you must manually extend the GraphQLError extensions object within your resolver or plugin.

Implementation Alternatives

If your clients require accessibility metadata to render screen-reader-friendly UIs, consider these alternatives:

1. Metadata Fields: Create a separate accessibilityMetadata field on your types that returns a dedicated AccessibilityInfo object.
2. Custom Introspection Resolvers: Implement a custom resolver for the __schema or __type fields to inject directive data into the introspection response (though this may break compatibility with some standard clients).
3. Client-Side Mapping: Maintain a shared JSON mapping of field paths to accessibility labels on the frontend.

Verification Steps

To verify this behavior in your environment, run the following introspection query:

{
  __schema {
    directives {
      name
    }
    types {
      name
      fields {
        name
        # Note: There is no 'directives' field available here in standard GraphQL
      }
    }
  }
}

You will observe that while @accessible appears in the directives list, it is absent from the fields metadata.

Diagnostic Detail Needed: Are you using a custom introspectionSchema or a specific Apollo plugin that modifies the default introspection resolvers?