Can't find the correct way to use SchemaStorage

Due to a lack of understanding on my part and also the rather slim documentation, I am forced to ask about the proper way to use SchemaStorage here.

I want to have a parent schema in place, located at https://myurl.com/schema/parentschema.schema.json and then multiple schemata, each inheriting the constraints from parentschema at the top level. I.e., the parentschema looks something like

{
  "param1": { "type": "integer" },
  "param2": { "type": "string" }
}

and the subschemas all look something like

{
  "$ref": "https://myurl.com/schema/parentschema.schema.json",
  "required": ["param1"]
}

adding only their own respective required structure to the schema.

I am trying to use SchemaStorage like

$schema = file_get_contents(__DIR__ . "/../schema/subschema.schema.json");

$schemaStorage = new SchemaStorage();
$schemaStorage->addSchema(__DIR__ . "/../schema/parentschema.schema.json", json_decode($schema));

$fac = new Factory($schemaStorage);
$validator = new Validator($fac);

Nevermind, I found it, and I was entirely too quick to open up an issue.
The documentation could be a bit more generous though.

Some further explanation of SchemaStorage for others running into the same sort of trouble:

• its the way to explain to the validator how to resolve references to outside the schema
• you initialize a SchemaStorage and then add reference addresses to it
• you add reference addresses with by $schemaStorage->add("/address/written/out", $objectTheAddressHasToPointTo)
• you initialize the validator with a SchemaStorage
• when the validator comes across a reference to "address/written/out", it already has all the needed structure loaded

[erayd]

If you are confused by something, you are most welcome to open issues to ask - I'm aware the documentation is terrible at the moment. Better documentation is on my list of things to do for this project, and is fairly important, because what we have at the moment is rather useless.

Regarding your original question - what you are trying to do IS NOT SUPPORTED by the JSON Schema standard - there is no official mechanism through which inheritance is possible. If you use $ref somewhere, all other properties of the object where $ref appears MUST be ignored:

An object schema with a "$ref" property MUST be interpreted as a "$ref" reference. The value of the "$ref" property MUST be a URI Reference. Resolved against the current URI base, it identifies the URI of a schema to use. All other properties in a "$ref" object MUST be ignored.

There are some unofficial extensions that allow for this (e.g. $merge, $use), but these haven't yet made their way into the standard, and aren't currently implemented by this library. If inheritance is critical to you, then either using another validator (or patching this one to add the feature) might be something to look into.

That is strange, because using the idiom I sketched above indeed it seems to work.
It throws the violations about type (from the parent schema) as well as the violations about required params (from the child schema).
It's a big then?

[erayd]

That's a big problem - if it's not ignoring the rest of the properties, then it's a major bug that needs fixing. Thanks for bringing it to my attention!

I was not even aware of writing invalid JSON schema... Well I guess once you fix it, a possible workaround for my requirements might be

{
  "allOf": [
    { "$ref": "https://.... },
    {
      "required": ...
    }
  ]
}

[erayd]

Yep, using allOf will work just fine for your particular use-case :-).

I'm wondering if there's something more sinister going on with $ref in this library - I'm writing more unit tests for it now, and it's not behaving how it's supposed to, beyond just this issue... Never mind, I screwed up my test - $ref works.

[erayd]

This is fixed in #437, along with an infinite-loop case. Thanks again for finding the bug :-).