Discussion: How to handle $ref with additional properties

[RicoSuter]

NJS (in NSwag) currently generates $refs as allOf if other properties are in the object:

 properties:
      audit:
        description: Audit data with information regarding document creation and modification.
        allOf:
             - $ref: '#/definitions/StoreAudit'  

Most tools expect the schema to be

 properties:
      audit:
        description: Audit data with information regarding document creation and modification.
        $ref: '#/definitions/StoreAudit'  

but this is invalid:

Any members other than $ref in a JSON Reference object are ignored.

See https://swagger.io/docs/specification/using-ref/

Discussions:

• allOf as schema reference is not allowed Azure/autorest#2652
• Extra JSON Reference properties ignored - reduces reusability of references OAI/OpenAPI-Specification#556

Code in question:

https://github.com/RSuter/NJsonSchema/blob/master/src/NJsonSchema/Generation/JsonSchemaGenerator.cs#L253-L274

Solutions:

1. Add AllowReferencesWithProperties setting to always use $refs (i.e. first condition in the code is always executed)?
   • Main problem: The generated Swagger spec will be valid in AutoRest (it must be like that) and invalid in swagger-editor...
   • Whats the best name for this setting so that people understand it?
   • I'd suggest to set the default to true because most tools expect only $refs and cannot handle oneOf/allOf refs
2. Add support for allOf/oneOf and $ref references in all other tools :-)

[alb3ric]

Add ForceDirectReferences setting to always use $refs

I think the ForceDirectReferences name is quite a good name.

[RicoSuter]

I dont like ForceDirectReferences because it implies that $ref is always used but this is not true. This would still be generated:

"Gender": {
      "oneOf": [
        {
             "type": "null"
        },
        {
          "$ref": "#/definitions/Gender"
        }
      ]
    },

maybe AllowReferencesWithAdditionalProperties?

[alb3ric]

Ok, but won't we mistake AdditionalProperties with the other AdditionalProperties term?

[RicoSuter]

true... AllowReferencesWithProperties? :-)

[alb3ric]

Perfect

[RicoSuter]

Release v9.9.5 => Releasing: https://ci.appveyor.com/project/rsuter/njsonschema

[alb3ric]

It works great. Thanks