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-03-26

Validate scalar boolean expression operators

A build error is now raised if any of the following validations for operators in scalar boolean expressions fail.

• Non-list argument types are not allowed for the _in operator
• Argument type must match the scalar type for _eq, _lt, _lte, _gt and _gte operators
• Mapped operators must exist in the data connector
• Argument type must be compatible with the mapped operator's NDC argument type
• Operators such as contains, icontains, starts_with, istarts_with, ends_with, and iends_with are only applicable on string scalars, with arguments strictly of type string

2025-03-20

Disallow duplicate model permissions roles

A build error is now raised if the same role is defined more than once in a ModelPermissions object.

2025-03-12

Disallow procedure command relationships

A build error is now raised if a relationship is defined between an object type and a procedure command. Procedure commands cannot be used in relationships. This prevents navigation of relationships from accidentally causing side-effects, as procedures can modify data.

2025-03-11

Validate object type field types in data connector type mappings

A build error is now raised when there is a mismatch between the field types defined in an object type and the corresponding field types in the data connector type mapping. This ensures type safety and prevents runtime errors due to incompatible type mappings.

For example, if a PostgreSQL data connector defines a column as INTEGER, mapping it to an object type field defined as String would raise an error:

{
  "kind": "ObjectType",
  "version": "v1",
  "definition": {
    "name": "User",
    "fields": [
      {
        "name": "age",
        "type": "String!" // Error: PostgreSQL column is INTEGER but object type defines it as String
      }
    ],
    "dataConnectorTypeMapping": [
      {
        "dataConnectorName": "postgres",
        "dataConnectorObjectType": "users",
        "fieldMapping": {
          "age": {
            "column": {
              "name": "age"
            }
          }
        }
      }
    ]
  }
}

Validate argument type mappings

A build error is now raised when argument mapping types are invalid or incompatible with their corresponding data connector types. This validation ensures that arguments passed to commands and models are properly typed and match the expected types in the data connector.

For example, if a PostgreSQL function expects an INTEGER argument, mapping it to an argument defined as String would raise an error:

{
  "kind": "Command",
  "version": "v1",
  "definition": {
    "name": "get_users_by_age",
    "arguments": [
      {
        "name": "age",
        "type": "String!" // Error: PostgreSQL function expects INTEGER but argument is defined as String
      }
    ],
    "source": {
      "dataConnectorName": "postgres",
      "dataConnectorCommand": {
        "function": "get_users_by_age"
      },
      "argumentMapping": {
        "age": "age"
      }
    }
  }
}

Disallow invalid headers in AuthConfig

When using webhook mode in AuthConfig, Hasura DDN now validates all specified headers. Any invalid headers will trigger a build error, whereas previously they were silently discarded.

Require aud claim validation in JWTs

If a JWT contains an aud claim, Hasura DDN will validate it against the audience field in the AuthConfig. Previously this was optional, but now if the JWT contains an aud claim, audience is must be configured in the AuthConfig. If the JWT contains an aud claim and audience is not configured, the JWT will be rejected and authentication will fail.

This protects customers from accidentally misconfiguring their audience and exposing their API to unauthorized users.

2025-02-27

Require valid command output type

A build error is now raised when a command's output type references a type that doesn't exist in the metadata. Previously, invalid output types might have been allowed but could lead to runtime errors. This ensures that all commands have valid and well-defined output types that can be properly handled by the system.

2025-02-20

Disallow unknown values in arguments

Previously if an argument preset was provided via a session variable, and contained unknown fields, the engine would ignore those fields and pass them on to the data connector.

For an object type with name and age fields, an input like this will throw an error, saying that we don't know anything about the not_in_our_object_type field.

{
  "name": "Bruce",
  "age": 30,
  "not_in_our_object_type": "bad value"
}

Disallow recursive object types

A build error is now raised when object types contain infinite recursion through non-nullable fields. This prevents creating object type structures that could lead to infinite loops during query execution. For example:

{
  "kind": "ObjectType",
  "version": "v1",
  "definition": {
    "name": "Person",
    "fields": [
      {
        "name": "id",
        "type": "Int!"
      },
      {
        "name": "name",
        "type": "String!"
      },
      {
        "name": "bestFriend",
        "type": "Friend!"  // Non-nullable reference to Friend type
      }
    ]
  }
},
{
  "kind": "ObjectType",
  "version": "v1",
  "definition": {
    "name": "Friend",
    "fields": [
      {
        "name": "id",
        "type": "Int!"
      },
      {
        "name": "name",
        "type": "String!"
      },
      {
        "name": "bestFriend",
        "type": "Person!"  // Non-nullable reference back to Person type
      }
    ]
  }
}

This creates an infinite recursion because Person must have a Friend, who must have a Person, who must have a Friend, and so on infinitely. This is now disallowed. To fix this, make at least one of the references nullable:

{
  "kind": "ObjectType",
  "version": "v1",
  "definition": {
    "name": "Person",
    "fields": [
      {
        "name": "id",
        "type": "Int!"
      },
      {
        "name": "name",
        "type": "String!"
      },
      {
        "name": "bestFriend",
        "type": "Friend" // Now nullable, breaking the infinite recursion
      }
    ]
  }
}

This ensures that all object type relationships have a clear termination point.

2025-02-08

Disallow unsupported orderable relationships

Build errors are now raised if unsupported orderable relationships are defined on OrderByExpressions. Specifically:

• If the relationship is a remote relationship
• If the data connector does not support performing relationships
• If the target Model or Command of the relationship does not have a source defined

Disallow relationships where the data connector does not support relationships or remote relationships

A build error is now raised if a Relationship is defined between an ObjectType and a Model or Command that are sourced from the same data connector, but that data connector does not support performing relationships or support remote relationships.

2025-02-04

Command and argument preset typechecking

A build error is now raised if an argument preset defined in CommandPermissions or ModelPermissions or a field preset in TypePermissions specifies a literal value that does not match the type of the argument or field it is supposed to be presetting.

Disallow scalar type mismatch in object type fields

A build error is now raised if an ObjectType's field's scalar type does not match the scalar type of the underlying data connector's object type field. The field's specified scalar type must have a DataConnectorScalarRepresentation defined that specifies it as the representation for the data connector's scalar type.

Disallow unknown ObjectType field types

A build error is now raised if an ObjectType's field's type is an unknown type.

Disallow orderable fields that have field arguments

A build error is now raised if an orderable field on an OrderByExpression has field arguments. This scenario is not supported.

2025-01-25

Disallow duplicate scalar type aggregate functions

A build error is now raised if a data connector scalar type has multiple aggregate functions of the same type (for example, two sum functions for the same scalar type). This ensures that there is no ambiguity when choosing an aggregate function for a particular purpose (for example, performing a sum aggregate).

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:

  • BooleanExpressionType
  • OrderByExpression

• Type name conflicts exist within a subgraph across the following type definitions:

  • ScalarType
  • ObjectType
  • BooleanExpressionType

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 / 2025-01-25 / 2025-02-04 / 2025-02-08 / 2025-02-20 / 2025-02-27	Known compatibility dates
string	Any date