Spec Bug: Inconsistent $ref usage rules in examples

[clemensv]

Summary

The spec contains contradictory guidance on where $ref is permitted. Section 3.4.1 states $ref is only permitted inside the type attribute, but examples throughout the spec show bare $ref usage in items, values, and choices.

The Rule (Section 3.4.1 - $ref Keyword)

"The $ref keyword is only permitted inside the \type\ attribute value of a schema definition, including in type unions."
"$ref is NOT permitted in other attributes..."

Contradicting Examples in the Spec

1. Array items - CONSISTENT

{
  "type": "array",
  "items": { "type": { "$ref": "#/Namespace/TypeName" } }
}

2. Set items - INCONSISTENT

{
  "type": "set",
  "items": { "$ref": "#/Namespace/TypeName" }
}

Should be: "items": { "type": { "\": "#/Namespace/TypeName" } }

3. Map values - INCONSISTENT

{
  "type": "map",
  "values": { "$ref": "#/StringType" }
}

Should be: "values": { "type": { "\": "#/StringType" } }

4. Choice choices - INCONSISTENT

{
  "type": "choice",
  "choices": {
    "StreetAddress": { "$ref": "#/definitions/StreetAddress" },
    "PostOfficeBoxAddress": { "$ref": "#/definitions/PostOfficeBoxAddress" }
  }
}

Should be: "StreetAddress": { "type": { "$ref": "#/definitions/StreetAddress" } }

Affected Spec Sections

• Line 580: set example with bare $ref
• Line 606: map example with bare $ref
• Lines 738-739: choice example with bare $ref

Recommendation

Either:

1. Update the rule to explicitly allow bare ~~~ in items, values, and choices as a shorthand, OR
2. Update all examples to use { "type": { "$ref": "..." } } consistently

Option 1 seems more ergonomic since these contexts unambiguously expect a type reference.

Impact

SDK implementations are confused about whether to accept bare $ref in these contexts.