Please clarify the examples of "Extending Closed Schemas" with Schema references

[haumacher]

As discussed in json-schema-org/understanding-json-schema#197, the examples for "Extending Closed Schemas" at https://json-schema.org/understanding-json-schema/reference/object.html?highlight=extending%20closed%20schemas#extending-closed-schemas are confusing, because of using an allOf construct with a single constraint as replacement for a schema defined elsewhere that is subject to extension.

The key point of the section is the extension of a schema defined independently. Therefore, the examples should use the schema referencing syntax with $ref and $defs. Otherwise, the reader could be distracted from the schema extension aspect. Since the referencing constructs are not yet introduced at this point when reading the documents linearly, a forwards pointer to the definition of the schema reference constructs should be introduced.

[eritain]

Reading "Understanding JSON Schema" in sequence, this allOf hack hasn't been explained by this point either. (Assuming it's explained anywhere.)

I'm also inclined to think the Right Thing is indeed to use referencing, briefly explain that that's what it is, and provide a link.

But until the rewrite with the referencing example is all put together, at a bare minimum, the allOf example needs a note that says something like, "Here, wrapping allOf around a single constraint is a hack for [whatever it's supposed to accomplish]."

And on that point, to me as a reader it's 100% unclear what it is supposed to accomplish, even after reading both this thread and json-schema-org/understanding-json-schema#197 (where the intent is described, circularly, as "this kind of constraint").

I understand from that thread that it's mostly just a setup for demonstrating something about additionalProperties, but the wording about that is not very clear either: "additionalProperties only recognizes properties declared in the same subschema as itself"?

OK, um, so talking about additionalProperties doing anything is metonymy for what a schema validator does when processing additionalProperties. And talking about recognizing is conceptual metaphor that imagines the validator as a homunculus. And still I have no idea what "recognizing" a property, during that activity, is supposed to make that homunculus think or not think or do or not do.

Often, if an example doesn't seem to illuminate the point being made, I can at least find the point and turn it around to illuminate the example. But here, I'm in the dark about both.