Decide how multiple applicable schema values should be handled

[kd-ods]

Summary of the bug or issue

We have properties like this one in the entity-record.json schema file:

    "jurisdiction": {
      "title": "Jurisdiction",
      "description": "The jurisdiction in which this entity was registered or created (for legal and registered entities, and arrangements). Or the state's jurisdiction (for states and state bodies).",
      "propertyOrder": 15,
      "$ref": "urn:components#/$defs/Jurisdiction"
    }

When the ref is resolved, there are mutliple values for description:

"The jurisdiction in which this entity was registered or created (for legal and registered entities, and arrangements). Or the state's jurisdiction (for states and state bodies)."

and

"A Jurisdiction MUST have a name. A jurisdiction SHOULD have a 2-letter country code (ISO 3166-1) or a subdivision code (ISO 3166-2)."

This is fine, but the 2020-12 spec is clear that it is up to individual applications to decide how to handle these multiple values.

I'm not entirely sure how the sphinx directives like '.. json-value::' on the references.rst page work, but somewhere along the line a decision will be being made about multiple description values. Likewise for docson.

We've also come across handling of mulitple values wrt an enum, with this bit of schema in entity-record.json:

      "items": {
        "$ref": "urn:components#/$defs/Address",
        "properties":{
          "type":{
            "enum":[
              "registered",
              "business",
              "alternative"
            ]
          }
        }
      },

Since this schema 'works' against the test data, do we have to assume that there is an implicit and default decision within the Draft202012Validator constructor about how to approach multiple values?

My primary motivation is from editing the schema descriptions... I want to be clear about how multiple descriptions are handled. In version 0.3 and prior: we overwrote the more general applicable description (i.e. that provided via a $ref) with the more specific description. So in the above example, the first description for jurisdiction would be used.

Suggested resolution

Wrt descriptions, I actually quite like the idea of appending the more generally applicable description to the more particular description. So for the jurisdiction field in the entity record details you'd get:

"The jurisdiction in which this entity was registered or created (for legal and registered entities, and arrangements). Or the state's jurisdiction (for states and state bodies). A Jurisdiction MUST have a name. A jurisdiction SHOULD have a 2-letter country code (ISO 3166-1) or a subdivision code (ISO 3166-2)."

[kd-ods]

@rhiaro - assigning to you for your reckons. Is my understanding above correct?? Is there a fundamental 'compiler' or constructor for a complex schema like BODS within which we can instantiate all decisions about mutliple-value-handling behaviour... ?

[kd-ods]

There is an instance of this issue wrt docson. See '3. Overlapping schemas problems' here: #682

[kd-ods]

Noting here how the schema is intended to be interpreted by tooling, when a $ref brings in different values for the same property. Let's gather these as we go and document properly soon. (cc @radix0000)

• Where there are 2 values for description, they are joined to form a compound description. The more specific description (in the referring property) should be a prefix to the more general description (on the referenced object). So, users of the schema would see that the description for jurisdiction for entity record details is:

"The jurisdiction in which this entity was registered or created (for legal and registered entities, and arrangements).
Or the state's jurisdiction (for states and state bodies). A Jurisdiction MUST have a name. A jurisdiction SHOULD
have a 2-letter country code (ISO 3166-1) or a subdivision code (ISO 3166-2)."

• Where there are 2 "enum" lists for a property, both sets of constraints apply. (So the constraints better overlap(!) from a schema design pov.)