$ref siblings

[mikeharder]

The behavior of $ref sibling propeties varies across different spec versions:

Allowed - All Properties

• OpenAPI 3.1 (https://spec.openapis.org/oas/v3.1.0#schema-object)
• JSON Schema 2020-12 (https://json-schema.org/draft/2020-12/json-schema-core#section-8.2.3.1)

Allowed - Selected Properties

• MS Swagger (https://azure.github.io/autorest/openapi/howto/$ref-siblings.html)

Ignored

• OpenAPI 2.0 (https://swagger.io/docs/specification/using-ref/)
• OpenAPI 3.0 (https://swagger.io/docs/specification/using-ref/)
• JSON Schema Draft 5 (https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00#section-7)

Mixing specifications from one bucket, with tools from another bucket, may be problematic.

For example, given this spec:

schemas:
  Foo:
    myProp:
      $ref: "#/components/schemas/Bar"
      readonly: true

The readonly property may be ignored or included, depending on the spec version.

Tools

The behavior also varies across the tools used in the azure-rest-api-specs repo.

azure-openapi-validator

Unit test ensuring it ignores $ref siblings:

azure-openapi-validator/packages/rulesets/src/spectral/test/provisioning-state-must-be-read-only.test.ts

Line 215 in cd5b31b

test("ProvisioningStateSpecified should find errors when readOnly property is present in the envelope property", () => {

azure-openapi-validator/packages/rulesets/src/spectral/test/provisioning-state-must-be-read-only.test.ts

Lines 261 to 280 in cd5b31b

	ProvisioningState: {
	type: "string",
	enum: ["Succeeded", "Failed", "Canceled"],
	"x-ms-enum": {
	name: "ProvisioningState",
	modelAsString: true,
	},
	},
	FooResource: {
	"x-ms-azure-resource": true,
	properties: {
	provisioningState: {
	$ref: "#/definitions/ProvisioningState",
	readOnly: true,
	type: "string",
	description: "Provisioning state of the foo rule.",
	enum: ["Creating", "Canceled", "Deleting", "Failed"],
	},
	},
	},

oav

READONLY_PROPERTY_NOT_ALLOWED_IN_REQUEST ignores $ref siblings: Azure/oav#1063

@apidevtools/json-schema-ref-parser

$RefParser.dereference() preserves $ref siblings:

// properties: {
//   name: { '$ref': '#/definitions/name', readOnly: true },
//   age: { '$ref': '#/definitions/age' }
// },
console.log("# Schema");
console.log(JSON.stringify(getSchema()) + "\n");

async function testRefParser() {
  console.log("# @apidevtools/json-schema-ref-parser");

  let derefSchema = await $RefParser.dereference(getSchema());

  // properties: {
  //   name: { readOnly: true, type: 'string', minLength: 1 },
  //   age: { type: 'integer', minimum: 0 }
  // },
  console.log(inspect(derefSchema) + "\n");
}

https://github.com/mikeharder/ref-siblings/blob/6b989b296dbc3fc51a55cfd464251918435de4e1/test.js#L26-L43

ajv

ajv.validate() has 3 options for extendRefs: true, "ignore", and "fail"

  // # ajv({ extendRefs: true})
  // valid: false
  // errors: [
  //   {
  //     keyword: 'minLength',
  //     dataPath: '.name',
  //     schemaPath: '#/properties/name/minLength',
  //     params: { limit: 2 },
  //     message: 'should NOT be shorter than 2 characters'
  //   }
  // ]

  // # ajv({ extendRefs: ignore})
  // $ref: keywords ignored in schema at path "#/properties/name"
  // valid: true
  // errors: null

  // # ajv({ extendRefs: fail})
  // Error: $ref: validation keywords used in schema at path "#/properties/name" (see option extendRefs)

https://github.com/mikeharder/ref-siblings/blob/6b989b296dbc3fc51a55cfd464251918435de4e1/test.js#L46-L64

Related

• [ProvisioningStateMustBeReadOnly] Rule ignores siblings of $ref #637
• Test false "false positive" for ProvisioningStateMustBeReadOnly #561
• oav not throwing expected READONLY_PROPERTY_NOT_ALLOWED_IN_REQUEST oav#1063