Compatibility Config
Introduction
The CompatibilityConfig object is a metadata object that defines the compatibility configuration of the Hasura metadata.
How CompatibilityConfig works
Lifecycle
By default, all projects are created with a default CompatibilityConfig object in the globals subgraph. It can be defined in any subgraph of your choice, but only once across your supergraph.
The date field in the CompatibilityConfig object specifies the date after which any new backwards-incompatible changes
made to Hasura DDN will be disabled and will not impact the Hasura project. For example, if your project has its date
set to 2024-10-16, then any new features added after that date that would result in breaking changes to your project
will be disabled. To enable these features, simply increase your date to a newer date.
Compatibility dates and breaking changes
The following is a list of dates at which backwards-incompatible changes were added to Hasura DDN. Projects with
CompatibilityConfig dates prior to these dates will have these features disabled.
2025-01-07
Disallow duplicate operator definitions for scalar type
A build error is now raised when a scalar type has multiple operator definitions with the same name. For example, if you have a custom scalar type and define multiple operators with the same name in its boolean expression configuration, the build will fail. This ensures that operator definitions for scalar types are unique and prevents ambiguity in boolean expressions.
Disallow multidimensional arrays in boolean expressions
A build error is now raised when multidimensional arrays (arrays of arrays) are used in boolean expressions. This restriction applies to both array comparison operators and array relationship fields within boolean expressions. Previously, such configurations might have been allowed but could lead to runtime errors or undefined behavior. This change ensures that only single-dimensional arrays can be used in boolean expressions, making the behavior more predictable and preventing potential runtime issues.
Disallow duplicate names across types and expressions
A build error is now raised when:
-
Duplicate names exist within a subgraph for the following definitions:
-
Type name conflicts exist within a subgraph across the following type definitions:
2024-12-18
Disallow non-scalar fields in Model v1 orderableFields
orderableFields in Model v1 now only allows fields of scalar types. Previously this was allowed, but queries that
tried to order against the non-scalar fields would fail at runtime or produce unexpected results. To order over nested
object fields, upgrade to Model v2 and use OrderByExpressions instead.
Disallow nested fields and nested relationships in OrderByExpressions when the data connector does not support them
Previously OrderByExpressions that incorporated nested fields and nested relationships were allowed to be used with
Models that sourced from data connectors that did not support ordering by nested fields and nested relationships. Such
a configuration will now result in a build error.
Prevent usage of array relationships in OrderByExpressions
Previously OrderByExpressions could specify array relationships in orderableRelationships. This was incorrect
behaviour, as only object relationships can be ordered over, and now results in a build error.
2024-12-10
Disallow multiple fields on input objects in GraphQL in order_by
GraphQL queries with order_by arguments that contain multiple properties set on one input object now properly return
an error. For example order_by: { location: { city: Asc, country: Asc } } is no longer allowed. This is because the
order of input object fields in GraphQL is not defined, so it is unclear whether ordering should be first by city or
first by country. Instead, write this query like so:
order_by: [{ location: { city: Asc } }, { location: { country: Asc } }].
Additionally, ordering by nested fields using a nested array is no longer allowed (for example:
order_by: { location: [{ city: Asc }, { country: Asc }] }). Instead, write this query like so:
order_by: [{ location: { city: Asc } }, { location: { country: Asc } }].
2024-12-05
Prevent conflicts between boolean expression fields in GraphQL
Conflicts between fields on boolean expression types that have the same name (such as conflicts between fields and logical operators) are now detected and a build error is raised.
2024-11-26
Logical operators in scalar boolean expression types
Previously, if logical operators (ie. _and, _or, _not) were enabled in scalar BooleanExpressionTypes, they would
not appear in the GraphQL API. Now, if they are enabled, they will correctly appear in the GraphQL API as configured.
2024-11-18
Disallow object boolean expression type
A build error is now raised if ObjectBooleanExpressionType is used to define a boolean expression. To resolve this,
you can upgrade all object boolean expression types in your metadata by running the following DDN codemod command.
ddn codemod upgrade-object-boolean-expression-types
Learn more about the command here.
2024-11-15
Require unique model GraphQL names
A build error is now raised if a root field defined in a Model's GraphQL config conflicts with an existing root field.
Previously, the conflicting root field was silently excluded from the GraphQL schema.
Require a valid NDC version in data connector capabilities
A build error is now raised when there is an invalid version in the capabilities of a data connector's schema. To fix
the error, please consider upgrading to the latest version of the data connector and running ddn connector introspect
to correct the invalid version. Prior to this change, it was assumed that the data connector with the invalid version
was an NDC v0.1.x connector.
2024-11-13
Allow resolving boolean expression fields without GraphQL config
Previously, comparable fields, relationships, and aggregate fields of a BooleanExpressionType were validated only if
the graphql field was configured in the metadata. These fields are now validated regardless of whether the graphql
configuration is specified.
2024-10-31
Disallow comparisons against scalar array fields in predicates
A build error is now raised if a scalar array field is configured in a BooleanExpressionType as a comparable field. Comparisons against scalar array fields are not supported as at this compatibility date.
2024-10-16
Enable JSON session variable support
Session variables provided in JWT claims, webhook responses or in the NoAuth settings can now be any JSON value, instead of just a string. This enable scenarios such as being able to put lists of values into a single session variable. However, this now means that if you use the session variable in a comparison against a field, the field's type must match the type of the session variable. For example, if you are comparing against an integer field, your session variable must be set as a JSON number and not a string.
2024-10-07
Require unique command GraphQL names
A build error is now raised when there is a conflict with a GraphQL root field or GraphQL type name that is already in use. Before this, the command would be silently dropped from the GraphQL schema.
2024-09-26
Propagate boolean expression deprecation status
The deprecated status for relationship fields is now propagated to boolean expressions that use them. The default
GraphQL introspection behavior is to hide such fields from the schema, so this behavior is considered a breaking change.
Disallow scalar types names conflicting with inbuilt types
A build error is now raised when a ScalarType metadata type is defined that conflicts with any of the built-in type
names (ID, Int, String, Boolean, Float).
2024-09-18
Require nested array filtering capability
A build error is now raised when a nested array field is defined on an ObjectType used in a Model whose underlying data
connector does not have the query.exists.nested_collections capability defined.
2024-09-03
Enable relationships in predicates to be used even if the data connector does not support it
Previously, only data connectors that supported the relationships.relation_comparisons capability supported
relationships in predicates. This change allows you to use relationships in boolean expressions even if the data
connector lacks support. When the capability is available, relationship predicates are resolved directly within the
native data connector for more efficient processing. If not, the predicates are handled at the API layer.
2024-06-30
Require GraphQL Config
A build error is now raised if a GraphQLConfig is not provided in the project metadata.
Metadata structure
v2_CompatibilityConfig
The compatibility configuration of the Hasura metadata.
| Key | Value | Required | Description |
|---|---|---|---|
kind | CompatibilityConfig | true | |
date | CompatibilityDate | true | Any backwards incompatible changes made to Hasura DDN after this date won't impact the metadata. |
CompatibilityDate
Any backwards incompatible changes made to Hasura DDN after this date won't impact the metadata
One of the following values:
| Value | Description |
|---|---|
2024-06-30 / 2024-09-03 / 2024-09-18 / 2024-09-26 / 2024-10-07 / 2024-10-16 / 2024-10-31 / 2024-11-13 / 2024-11-15 / 2024-11-18 / 2024-11-26 / 2024-12-05 / 2024-12-10 / 2024-12-18 / 2025-01-07 | Known compatibility dates |
| string | Any date |
