Cannot use $ref with other keywords in the same object

[Relequestual]

In draft-7 JSON Schema, you cannot use $ref with other keywords. All other keywords in that object are ignored.

For example:
https://github.com/ga4gh-schemablocks/blocks-json-schema/blob/e3d0e382cf245c544427c32b8633ab8cda70f624/src/yaml/Individual.yaml#L47-L53

In stead, wrap the object in an allOf, splitting the $ref and annotations and/or other keywords into separate subschemas.

[theisuru]

Something like this ?
https://github.com/ga4gh-schemablocks/blocks-json-schema/blob/6618757de2a71a512ed98c5190b0bf8918d373e5/src/yaml/Age.yaml#L12-L25

[mbaudis]

@Relequestual @theisuru This is a bit awkward. There is a clear case to be made for description and examples to be either provided by the instance of the $ref. This is especially relevant for these very "prototype" prototypes (think OntologyClass) where the documentation of the use cases is highly relevant.

Probably the this could be solved more elegant by having a special structure á la:

age_class: 
  "$ref": https://schemablocks.org/schemas/ga4gh/OntologyClass.json 
  instance:
    description: | 
      The age of the subject (e.g. individual at the onset of a phenotype), 
      as Ontology_class. An example ontology here is HsapDv (Human 
      Developmental Stages). 
    examples: 
      - id: 'HsapDv:0000083'
        label: 'infant stage'

... in JSON Schema. I also wonder how this works with arrays, where the $ref is a child of items?

[Relequestual]

I totally understand it's akward and not ideal. This is why we made changes in draft-8 to allow $ref alongside other keys in an object.
If you don't wrap it in an allOf and want to use standard tooling later to do annotation collection, you're likely to run into problems.

If documentation is a pre-step to actual JSON Schema, and only annotations are included alongside $ref, then you don't have a problem, however it looks bad, and may lead others to believe it's OK to put validation there also.

So you could do it either way, and both have trade offs.

[mbaudis]

@Relequestual So, especially w/ respect to draft-8, I think we stick w/o the allOf constructor. If descriptions, examples are ignored by the validator that would be fine.

BUT: I really think the JSON Schema spec. needs something akin to the instance object for documentation/example/format purposes. Or better instantiation.

If draft-8 will allow additional keys: Can't we directly do it like that?

Also: This can be explained in a yet-to-be-written BlockSchema prototype.