allOf schema composition

The JSON Schema allOf keyword combines several schemas, called subschemas, into a single composition. A JSON value must satisfy every subschema.

To expose a record type of your own web service as a composition, set the JSONAllOf attribute on it. The attribute composes record types only.

Types generated from a composition

The type fglrestful generates depends on what the subschemas are:

Objects. Where the composition contains only object schemas, the tool merges their properties into one record. For an Employee composition of the Person and Address schemas, it generates the following record. The field types come from those two schemas, which are not shown:

PUBLIC TYPE Employee RECORD
    id INTEGER,
    name VARCHAR(40),
    street VARCHAR(60),
    city VARCHAR(30)
END RECORD

Primitives. Where the composition contains only schemas of primitive JSON types, the tool merges them into a single primitive data type. A common use of allOf is to restrict an existing type further. In the following schemas, OpenOrderStatus references the OrderStatus enumeration and adds a subschema that lists two of its three values and sets a shorter length limit:

"OrderStatus": {
  "type": "string",
  "enum": ["NEW", "SHIPPED", "CANCELLED"],
  "maxLength": 16
},
"OpenOrderStatus": {
  "allOf": [
    { "$ref": "#/components/schemas/OrderStatus" },
    { "enum": ["NEW", "SHIPPED"], "maxLength": 10 }
  ]
}

The second subschema does not list CANCELLED, so the type allows only NEW and SHIPPED. It also sets the shorter length limit, resulting in a VARCHAR(10) type:

PUBLIC TYPE OpenOrderStatus VARCHAR(10) ATTRIBUTE(JSONEnum = '"NEW","SHIPPED"')

Differing primitives. Where the composition contains schemas of different primitive JSON types, no single BDL type can hold the value. For example, from the following schema:

"OrderRef": {
  "allOf": [
    { "type": "string", "maxLength": 12 },
    { "type": "integer" }
  ]
}

The tool generates a util.JSONObject:

PUBLIC TYPE OrderRef util.JSONObject {fallback type}

It outputs a warning for each subschema it skips, and then the fallback warning.

Mixed. Where the composition contains a mixture of object schemas and schemas of primitive JSON types, the tool builds the record from the object schemas only. For example, from a composition of a Customer object schema with id and name properties and a string:

"LabeledCustomer": {
  "allOf": [
    { "$ref": "#/components/schemas/Customer" },
    { "type": "string", "maxLength": 10 }
  ]
}

The tool generates the Customer properties only, and outputs a warning that the type and maxLength keywords of the string are not mapped:

PUBLIC TYPE LabeledCustomer RECORD
    id INTEGER,
    name VARCHAR(40)
END RECORD

Where the composition contains an object schema and a subschema with only keywords such as nullable or description, the tool also skips that subschema and outputs the same warning. For example, OpenAPI 3.0 ignores keywords placed next to a $ref, such as nullable, so a specification often wraps the reference in a composition:

"OptionalCustomer": {
  "allOf": [
    { "$ref": "#/components/schemas/Customer" },
    { "nullable": true }
  ]
}

The tool generates the Customer properties only, and the nullable keyword is not mapped:

PUBLIC TYPE OptionalCustomer RECORD
    id INTEGER,
    name VARCHAR(40)
END RECORD

Separate types for object subschemas (--no-merge-allof)

The default merge gives one record for each composition, so a schema that several compositions reference has its properties copied into each one, as Person and Address are in the Employee record. To keep those schemas as types of their own, run --no-merge-allof. The tool then generates a type for each $ref subschema, and a composing type that holds those types as members, with the JSONAllOf attribute set on it:

PUBLIC TYPE Person RECORD
    id INTEGER,
    name VARCHAR(40)
END RECORD

PUBLIC TYPE Address RECORD
    street VARCHAR(60),
    city VARCHAR(30)
END RECORD

PUBLIC TYPE Employee RECORD ATTRIBUTE(JSONAllOf)
    Employee_Person Person,
    Employee_Address Address
END RECORD

The tool names each member for the composing type and the subschema it came from. An inline object subschema has no type of its own, so it becomes an anonymous record member named Type_specific, Type_specific2, and so on, where Type is the composing type.

The option changes nothing for a composition of schemas of primitive JSON types, because the attribute applies to record members only.

How constraints are merged

The tool merges the constraints of all the subschemas as follows:

• enum: only the values allowed by every subschema. Where the subschemas have no value in common, the tool drops the constraint and outputs a warning.
• maxLength: the smallest value.
• minimum and maximum: the narrowest range.
• multipleOf: the first value found.
• pattern: the first regular expression found. BDL supports one JSONPattern attribute per field, so the tool drops any further expression and outputs a warning.

For the BDL types fglrestful generates from these keywords, go to Converting OpenAPI types to BDL in client stubs.

Duplicate properties in object subschemas

These rules apply to a schema fglrestful reads. Where you set the JSONAllOf attribute on a record type of your own, the composed records cannot repeat a property name.

Where several object subschemas define the same property, what the tool generates depends on the mode.

Warnings

The tool outputs a warning wherever BDL cannot represent a constraint of the description. Warnings are on by default, and you run -W no to silence them. Each message begins with the path of the schema that caused it.

The messages name the values the tool found, so your own output differs in the pattern text, the property names, and the subschema numbers.