Link object with operationRef is not validated correctly

[Alan-Cha]

Link objects with operationRef properties do not have $ref properties, yet oas-validator complains that they do.

Checklist

• Conversion: I have checked my source definition is valid OpenAPI 2.0
• Conversion: On valid OpenAPI 2.0 input, the conversion looks wrong
• Validation: I believe my source definition is valid OpenAPI 3.0.x but the validator complains
• Validation: I believe my source definition is invalid OpenAPI 3.0.x but the validator does not complain
• Linting issue
• Resolver issue

Detailed Description

Here is what my link object looks like:

"ReviewsWithOperationRef": {
	"operationRef": "#/paths/~1products~1{id}~1reviews/get",
	"parameters": {
		"id": "$request.path.product-id",
		"product-tag": "$request.query.product-tag"
	}
}

And when I try to validate my OAS, I get the following message:

status: false
message: |-
  Failed OpenAPI3 schema validation: [
    {
      "keyword": "required",
      "dataPath": "/components/links/ReviewsWithOperationRef",
      "schemaPath": "#/required",
      "params": {
        "missingProperty": "$ref"
      },
      "message": "should have required property '$ref'",
      "schema": {
        "$ref": {
          "type": "string",
          "format": "uriref"
        }
      },
      "parentSchema": {
        "type": "object",
        "required": [
          "$ref"
        ],
        "properties": {
          "$ref": {
            "type": "string",
            "format": "uriref"
          }
        },
        "description": "A simple object to allow referencing other components in the specification, internally and externally.  The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules.   For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification."
      },
      "data": {
        "operationRef": "#/paths/~1products~1{id}~1reviews/get",
        "parameters": {
          "id": "$request.path.product-id",
          "product-tag": "$request.query.product-tag"
        }
      }
    },
    
    ...

  ]
context: '#/'

---

When I try to add the $ref property as suggested like in the following:

"ReviewsWithOperationRef": {
	"$ref" : "blah",
	"operationRef": "#/paths/~1products~1{id}~1reviews/get",
	"parameters": {
		"id": "$request.path.product-id",
		"product-tag": "$request.query.product-tag"
	}
}

... oas-validator gives the thumbs up.

---

However, link objects with operationRef properties do not have $ref properties.

Here is the link object documentation link again for easy reference.

Thanks!

Other stuff

Just a note, I have the exact same link object but with an operationId property instead of an operationRef property and oas-validator does not complain that it is missing a $ref property.

I am working with the latest version of oas-validator, version 1.1.7.

[MikeRalphson]

Thanks for the detailed report. I'll take a look.

[MikeRalphson]

The full schema validation error is definitely confusing, as it includes all of the oneOf violations which has led it to fail the instance (not just the first which is complaining that your link object isn't a $ref).

But it does include this nugget:

  {
    "keyword": "format",
    "dataPath": "/components/links/ReviewsWithOperationRef/operationRef",
    "schemaPath": "#/properties/operationRef/format",
    "params": {
      "format": "uriref"
    },
    "message": "should match format \"uriref\"",
    "schema": "uriref",
    "parentSchema": {
      "type": "string",
      "format": "uriref"
    },
    "data": "#/paths/~1products~1{id}~1reviews/get"
  }

As the operationRef must match the format uriref, all non-urlsafe characters must be encoded. This includes { and }. Encoding them as %7B and %7D makes your snippet validate.

[Alan-Cha]

Thanks for the quick update. While escaping the curly brackets does fix the validation error, I am not convinced that OAS supports URL encoding, at least for operationRef.

Take a look at the following examples, taken directly from OAS documentation:

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

In both of these examples, operationRef uses curly brackets without escaping them.

[MikeRalphson]

Thanks for the follow-up. The fact that the operationRef is defined as a reference and elsewhere in the OAS that means a URL or relative-reference and that the draft schema enforces this leads me to believe the url-encoding is necessary.

Perhaps you could raise an issue on the OAS repository so we can get a decisive answer and then either fix the examples or the draft schema?

[Alan-Cha]

I filed an issue! Here's a link. Hopefully we will hear back soon.