Required inheritance and generated objects when using allOf

[florentchauveau]

Considering the following schema:

    FooProperties:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
        firstname:
          type: string
        lastname:
          type: string

    Foo:
      allOf:
        - $ref: "#/components/schemas/FooProperties"
        - type: object
          required:
            - uuid
            - firstname
            - lastname

    NewFoo:
      allOf:
        - $ref: "#/components/schemas/FooProperties"
        - type: object
          required:
            - firstname

According to the specs, also confirmed in the https://editor.swagger.io/, and swagger-api/swagger-editor#1212, NewFoo should have firstname as required, and Foo should have all properties as required.

The validation works as expected.

However, the resulting objects in Go are:

type Foo struct {
	// Embedded struct due to allOf(#/components/schemas/FooProperties)
	FooProperties `yaml:",inline"`
	// Embedded fields due to inline allOf schema
}

// FooProperties defines model for FooProperties.
type FooProperties struct {
	Firstname *string `json:"firstname,omitempty"`
	Lastname  *string `json:"lastname,omitempty"`
	Uuid      *string `json:"uuid,omitempty"`
}

// NewFoo defines model for NewFoo.
type NewFoo struct {
	// Embedded struct due to allOf(#/components/schemas/FooProperties)
	FooProperties `yaml:",inline"`
	// Embedded fields due to inline allOf schema
}

Because of the struct embedding, the properties are all pointers instead of values (like when using "required" directly in objects).

Now, because the validation works as expected, this might not be an issue at all. I wonder however if in this case, if the generated code should embed FooProperties as is, or if a new struct should be generated per "merge".

This has been discussed, and sometimes fixed, in several other projects:

• Can optional properties be made required when "allOf" and "discriminator" are used? OAI/OpenAPI-Specification#1870
• Required properties on an extended schema are not handled expectedly cyclosproject/ng-openapi-gen#108
• Required properties in the models with inheritance sylvainlaurent/swagger-validator-maven-plugin#19
• Making fields required during use of allOf acacode/swagger-typescript-api#275
• Failure to correctly validate required in allOf python-openapi/openapi-schema-validator#15

[deepmap-marcinr]

This is a hard one, and not a part of the spec that I was aware of when I was initially writing this code.

I think the right way to do it is to process "allOf" on the schema level, not on the Go struct level - meaning, we don't embed FooProperties as a struct inside Foo or NewFoo, but rather, generate a new struct where all fields are promoted to the higher level. However, you can't easily assign FooProperties into Foo anymore.

I didn't realize that allOf could modify the required property alone.

[florentchauveau]

Maybe we can add a "merge strategy" option? Either embed, or create a new struct with values (according to the required fields).

[Swiftwork]

Thought I would share my temporary and convoluted solution using JavaScript to "transpile" a schema by flattening allOf and dereferencing objects with a custom x-deref attribute. I don't suggest you use this method but it might be hint as to how you can have both embedded and dereferenced types.

const fs = require("fs").promises;
const path = require("path");
const mergeAllOf = require("json-schema-merge-allof");
const yaml = require("js-yaml");
const refParser = require("@apidevtools/json-schema-ref-parser");
const { Command } = require("commander");
const program = new Command();

/** Recursively mutates and dereferences all objects with the property x-deref set to true
 * @param {Object} schema - The schema to dereference
 * @param {Object} dereferenced - The dereferenced schema
 */
async function dereference(schema, dereferenced) {
  Object.entries(schema).forEach(([key, value]) => {
    if (typeof value === "object" && value !== null) {
      // Work deepest to shallowest
      dereference(value, dereferenced[key]);
      if (value["x-deref"] === true) schema[key] = dereferenced[key];
      else if (value["x-deref"] === false) dereferenced[key] = value;
    }
  });
}

async function processOpenAPISpec(schema) {
  let dereferenced = JSON.parse(JSON.stringify(schema));
  await refParser.dereference(dereferenced);
  dereference(schema, dereferenced);

  function mergeAllOfRecursively(candidate, parent, k) {
    if (typeof candidate !== "object" || candidate === null) return;

    if (candidate.allOf) {
      parent[k] = mergeAllOf(candidate, {
        ignoreAdditionalProperties: true,
        deep: true,
        resolvers: {
          "x-go-type": mergeAllOf.options.resolvers.default,
        },
      });
    } else {
      for (const [key, value] of Object.entries(candidate)) {
        mergeAllOfRecursively(value, candidate, key);
      }
    }
  }

  for (const [key, value] of Object.entries(schema)) {
    mergeAllOfRecursively(value, schema, key);
  }

  return schema;
}

const main = async (options) => {
  let specYaml = await fs.readFile(path.resolve(options.input), "utf8");
  const spec = yaml.load(specYaml);
  const merged = await processOpenAPISpec(spec);
  if (path.extname(options.output) === ".yaml") {
    specYaml = yaml.dump(merged);
    fs.writeFile(path.resolve(options.output), specYaml, "utf8");
  } else {
    fs.writeFile(
      path.resolve(options.output),
      JSON.stringify(merged, null, 2),
      "utf8"
    );
  }
};

program
  .name("OpenAPI Spec Transformer")
  .description("Transfrom OpenAPI Spec dereferencing and merging allOf.")
  .version("0.1.0");

program
  .requiredOption("-i, --input <path>", "Path to the OpenAPI spec file.")
  .requiredOption("-o, --output <path>", "Path to the output file.")
  .action(main);

program.parse();

Example:

    User:
      title: User
      allOf:
        - type: object
          properties:
            id:
              $ref: '#/components/schemas/id'
        - $ref: '#/components/schemas/UserProperties'
        - type: object
          required:
            - id
            - email
            - name
            - photo
            - verified
      x-deref: true