$ref not well specified

[DavidBiesack]

The current spec is not clear at all on how $ref is used; it is simply underspecified:

Reference Object

A simple object to allow referencing other definitions in the specification. It can be used to reference parameters and responses that are defined at the top level for reuse.

Fixed Fields

Field Name	Type	Description
$ref	string	Required. The reference string.

This does not say how the reference string should be specified. Comments on swagger-api/swagger-editor#182 which uses references such as '#/parameters/productId' imply it is not JSONPath which uses $ for the root.

[webron]

Fair enough. I'll add an explanation that this is a JSON Reference that uses a JSON Pointer as a value.

[hornc]

Hi, I am confused as to why the $ref needs to be explicitly included in the Swagger spec -- if it is a JSON reference, it is already built in to the JSON parsing, so couldn't I use a $ref for a Path Item Object regardless of the Swagger 2.0 schema having

"properties": {
    "$ref": {
          "type": "string"
    }, ...

?

I'm trying to understand this as a JSON validator I am using is failing to validate the Swagger 2.0 spec against draft4, and it seems to be stumbling on trying to parse "$ref":{ "type": "string" }.

While I am pretty sure there's a bug in the validator, I'm not exactly sure how this redefining(?) of $ref should be processed.

Any clarification of why this is explicitly in the spec will be much appreciated!

[ep1804]

Hi, I'm confused too.

This point was checked months ago but there's no progress.
On Nov 18, 2014 11:50 AM, "Charles Horn" [email protected] wrote:

Hi, I am confused as to why the $ref needs to be explicitly included in
the Swagger spec -- if it is a JSON reference, it is already built in to
the JSON parsing, so couldn't I use a $ref for a Path Item Object
regardless of the Swagger 2.0 schema having

"properties": {
"$ref": {
"type": "string"
}, ...

?

I'm trying to understand this as a JSON validator I am using is failing to
validate the Swagger 2.0 spec against draft4, and it seems to be stumbling
on trying to parse "$ref":{ "type": "string" }.

While I am pretty sure there's a bug in the validator, I'm not exactly
sure how this redefining(?) of $ref should be processed.

Any clarification of why this is explicitly in the spec will be much
appreciated!

—
Reply to this email directly or view it on GitHub
#135 (comment)
.

[whitlockjc]

$ref is a JSON Reference. The schema for a JSON Reference is it requires a $ref key that is of type string. That's its point and that is why the schema as-is.

[mission-liao]

Here is my guess plus reference to http://json-schema.org/latest/json-schema-core.html#anchor27

$ref could be one of these format:

• Canonical dereferencing: $ref would be a JSON pointer.
• Inline dereferencing: Just a name under the same scope, ex:

"Pet":{
  "properties":{
    "id":{
      "type":"integer",
      "format":"int64",
    },
    "category":{                                                            
      "$ref":"Category"
    }
}

in this case, if this $ref is under #/definitions, it would resolve to "#/definitions/Category"

[mohsen1]

Implementations MUST support canonical dereferencing, and MAY support inline dereferencing.

I don't really know what is position of Swagger 2.0 regarding to this.

[webron]

@mohsen1, @mission-liao - Obviously we support canonical dereferencing. As for inline dereferencing, I'm still not 100% sure. It seems that in order to support it, there's a need for the id property which we do not have, so I'm inclined towards a negative answer.

@hornc - we actually have an issue with the path item $ref which we are trying to resolve. Other than that, I'm not really sure what you're asking.

[whitlockjc]

My opinion is to make everything canonical references. It might be a few extra strokes vs. inline dereferencing but at least your intentions will be explicit.

[webron]

Well, we're not going to change the spec for that now and that's out-of-scope for the original post. Feel free to open a separate issue for the next version, giving out as much information as you can :)

[webron]

Or maybe you were just talking about canonical vs inline?

[whitlockjc]

I've updated my comment to be more clear, I want to only support canonical references.

[webron]

Okay, sorry, my bad. Yes, I tend to agree. Regardless of tooling support, I think clearer (to humans) to read canonical references as you get a clear path to where the definition resides. An inline definition can be much more confusing when there are multiple instances of the same name.