Making properties required by the database

In the data model, some entity fields are required. You cannot create an instance of the entity without specifying a value for the field, and the value can never be null. For example, suppose that an insurer has a business rule stating every activity must have an end date (the date by which it is expected to be completed). To enforce this, the Activity entity's EndDate field is required. These fields are sometimes referred to as required by the database.

In a schema, you can configure a resource property to reflect that it is required by the database. To do this, you must set the following properties:

  • "requiredForCreate": true
    • This x-gw-extensions attribute indicates the property must be included in POST payloads.
  • "x-gw-nullable": false
    • This attribute indicates that when the property is specified, its value cannot be set to null

The "requiredForCreate": true attribute, by itself, only mandates that the property must be specified in a POST. There is nothing to prevent a caller from including the property but setting the property's value to null.

The "x-gw-nullable": false attribute, by itself, only mandates that if the property is specified, the property's value cannot be set to null. There is nothing to prevent a caller from omitting the property.

By combining the two expressions, you are stating that the property must be specified in a POST and set to a non-null value, and anytime thereafter that the property is specified, it must be set to a non-null value. This is the equivalence of setting a data model entity field to required.

For example, suppose the CustomEntity_Ext entity has an CustomDescription field, which is a string. The field is required. The property declaration would be:

  "definitions": {
    "CustomEntityExt": {
      ...
      "properties": {
        ...
        "customDescription": {
          "type": "string",
          "x-gw-nullable": false,
          "x-gw-extensions": {
            "requiredForCreate": true
          }
        }
        ...
Note: There is also a concept of requiredness at the schema level. You can specify a property is required at the schema level by specifying "required": true. When a schema property is set to required, it must be provided every time a payload is submitted. In most cases, this is not something you would want to specify in Cloud API schemas, as it forces you to specify a value for PATCHes, even if the property in question is not being changed.

Overriding base configuration properties

If a base configuration property is not required by the database, you can make it required by the database by adding it to the appropriate schema extension file and setting the appropriate properties as shown in the previous example.

If a base configuration property is required by the database, you cannot make it non-required.