Scenario 1:
In this example, we use x-nullable as a vendor extension to represent when a field is allowed to have an expressly null value. As it stands now, we have to make address.yaml contain this property for all uses (which is bad, because it's not always nullable).
# item.yaml
shipping_address:
x-nullable: true # I will be killed by the following $ref
$ref: "address.yaml"
# address.yaml
description: A generic address
properties:
# fields hereOnce this is deferenced, x-nullable has disappeared. It seems like this should be a merge, to allow for overrides as well.
# item.yaml
shipping_address:
description: A generic address
properties:
# fields hereScenario 2:
When using generic/common objects, it's nice to provide usage-specific descriptions. Today we have to use one description for all uses, as the description will be stripped by dereferencing.
# item.yaml
shipping_address:
description: Shipping address for the item # I will disappear after $ref resolves
$ref: "address.yaml"
After dereferencing, this will strip off the overriden description:
# item.yaml
shipping_address:
description: A generic address
properties:
# fields here
Scenario 1:
In this example, we use
x-nullableas a vendor extension to represent when a field is allowed to have an expresslynullvalue. As it stands now, we have to makeaddress.yamlcontain this property for all uses (which is bad, because it's not always nullable).Once this is deferenced,
x-nullablehas disappeared. It seems like this should be a merge, to allow for overrides as well.Scenario 2:
When using generic/common objects, it's nice to provide usage-specific descriptions. Today we have to use one description for all uses, as the description will be stripped by dereferencing.
After dereferencing, this will strip off the overriden description: