Is it allowed to combine $ref with other keywords in JSON Schema?

Question

I'm learning JSON Schema for one of the open-source projects. Have a question concerning combining an already defined schema with some additional keywords.

Assume I've defined some schema which is available via the reference, for example #/definitions/positiveInteger.

Now I would like to refer to that type and extend it with few other keywords. For instance, I'd like to add enum or description.

Is it allowed to do this:

{
    "$ref" : "#/definitions/positiveInteger",
    "description" : "This is positive integer with enums",
    "enum" : [ 2, 4, 6, 8 ]
}

Or do I have to do this:

{
    "allOf" : [ { "$ref" : "#/definitions/positiveInteger" } ],
    "description" : "This is positive integer with enums",
    "enum" : [ 2, 4, 6, 8 ]
}

I could not find the formal reference for that and not sure how validation tools would react.

Basically I have two question here:

• Should the validation keyword like enum work in the first case?
• Will be there any conflicts if I include a metadata keyword like description next to $ref like in the first case?

I'd actually prefer to inline $refs and not to include them in allOf and kinds but not sure if this is legal. I couldn't even find a description of $ref in the spec (just a couple of examples).

Answer 1

You have to use allOf to extend a definition. Here is the relevant documentation.

Any members other than "$ref" in a JSON Reference object SHALL be ignored.

• https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03#section-3