about $ref as used in Open Contracting Data Standards

[ruifortes]

OCDS uses $ref's in they're schema in an interesting way.
In this excerpt it the $ref object has a "description" property besides "$ref". (see code below)
References to Value type can have different descriptions which is vert useful but isn't this against the json-reference/pointer RFC (and this repo) directives?

{
  "title": "Tender",
  "description": "Data regarding tender process - publicly inviting prospective contractors to submit bids for evaluation and selecting a winner or winners.",
  "type": "object",
  "properties": {
    "id": {
      "title": "Tender ID",
      "description": "An identifier for this tender process. This may be the same as the ocid, or may be drawn from an internally held identifier for this tender.",
      "type": ["string", "integer"],
      "mergeStrategy": "ocdsVersion"
    },
    "title": {
      "description": "Tender title",
      "type": ["string", "null"],
      "mergeStrategy": "ocdsVersion"
    },
    "description": {
      "description": "Tender description",
      "type": ["string", "null"],
      "mergeStrategy": "ocdsVersion"
    },
    "value": {
      "description": "The total upper estimated value of the procurement.",
      "$ref": "#/definitions/Value"
    }
  },
  "definitions": {
    "Value": {
      "type": "object",
      "properties": {
        "amount": {
          "description": "Amount as a number.",
          "type": ["number", "null"],
          "minimum": 0,
          "mergeStrategy": "ocdsVersion"
        },
        "currency": {
          "description": "The currency in 3-letter ISO 4217 format.",
          "type": ["string", "null"],
          "mergeStrategy": "ocdsVersion"
        }
      }
    }
  }
}

[handrews]

isn't this against the json-reference/pointer RFC (and this repo) directives?

Yes, the current correct usage would be something like:

{
    "definitions": {...},
    "properties": {
        "value": {
            "allOf": [
                {"description": "The total upper estimated value of the procurement."},
                {"$ref": "#/definitions/Value"}
            ]
        }
    }
}

Although see also $use from #98 , or the more expansive metadata extension proposal in #136 for some possible other approaches under consideration.

[epoberezkin]

Spec only says that other keywords should be ignored. description is ignored anyway. So what is the problem with having it in the same object?

[handrews]

Ignored means that when the reference is replaced, those extra fields go away. Otherwise the behavior would be a merge, and we've discussed many times in many issues that $ref does not merge.

[handrews]

@ruifortes does this answer your question? If so could you please close this issue? If not, what is needed to resolve it?

[awwright]

Adding a "description" field to a $ref object is as meaningful as making it a comment (if JSON had comments): It's not illegal, but it has no semantic value whatsoever.

If you want to make it meaningful, then using "allOf" would be the solution.

[handrews]

@ruifortes it's been over a month since we asked if this answer satisifed you so I'm assuming it did in fact answer your question. Please re-open if not, or file a new issue with any new questions.

See also #197 for more ideas about commenting.