JSONRequired

Specify properties that are required in a JSON schema.

Syntax

JSONRequired

JSONRequired is an optional attribute.

Usage

You can set JSONRequired on elements of a record or a user-defined type to specify properties that are required in the JSON Schema. You can also set JSONRequired directly at the root of the type, and in this case all members are required.

If the JSONRequired attribute is placed at the root of a record or on one of its primitive members, it may be also necessary to set the json_null="null" attribute on the relevant field, or set the serializeNullAsDefault option for the The json.Serializer class, to allow nulls; otherwise, error-15807 will be raised if a null value is sent. Any attempt to send a null value to a field marked with JSONRequired will result in this error. For examples allowing null values with JSONRequired, go to Example 2: BDL to JSON serialization options to allow nulls.

The JSONRequired attribute supports the required keyword in the JSON schema property of the Swagger and OpenAPI specifiaction.

Example 1 using JSONRequired at the root of a type definition

In this example, the JSONRequired attribute is set directly at the root of the type definition, and in this case all members are required properties in the JSON schema.

TYPE profileType RECORD ATTRIBUTE(JSONRequired)
    id INTEGER ATTRIBUTES(WSDescription = "Internal Identifier"),
    name VARCHAR(100) ATTRIBUTES(WSDescription = "Lastname"),
    email VARCHAR(255),
    category VARCHAR(10) ATTRIBUTES(WSDescription = "User Demographic"),
    status INTEGER,
    ccode VARCHAR(3) ATTRIBUTES(WSDescription = "Country Code")
END RECORD

Example 2 using JSONRequired in members of a type definition

In this example, the JSONRequired attribute specifies the id, name, and email members of the profileType record as required properties in the JSON schema.

TYPE profileType RECORD ATTRIBUTE(WSTypeDescription = "profile of user")
    id INTEGER ATTRIBUTES (WSDescription="Internal Identifier", JSONRequired), 
    name VARCHAR(100) ATTRIBUTES (WSDescription="Lastname", JSONRequired),
    email VARCHAR(255) ATTRIBUTE(JSONRequired),
    category VARCHAR(10) ATTRIBUTES (WSDescription="User Demographic"),
    status INTEGER,
    ccode VARCHAR(3) ATTRIBUTES (WSDescription="Country Code")
    # ...
    END RECORD

In the OpenAPI documentation, the GWS engine exposes the required property in the schema for the record elements defined with JSONRequired.

The output shown is from the Firefox® browser, which converts JSON to human readable format. The output may vary depending on your browser.

In this sample schema defining a record of profileType, a request to the service will require that all members are required; otherwise, the request will fail.

Image from the OpenAPI document showing the profileType JSON schema with all required properties — Figure: Sample JSON schema with all required properties

In this sample schema defining a record of profileType, a request to the service will require that each user has an id, name and email address; otherwise, the request will fail. Providing the properties not required is optional.

Image from the OpenAPI document showing the profileType JSON schema with some required properties — Figure: Sample JSON schema with some required properties