"required" attributes aren't pulled from $refs in schemata API description.

[lukeschlather]

We've got an API schema set up using JSON API, and we've got some required fields which are shared between several different API methods. As such, we'd like to include a $ref that defines the API attributes in one place. I dug a bit into the schemata templates which generate the documentation, and while it does attempt to recurse down some things, it seems that when it's deciding which attributes are required, it doesn't do so in a way which allows it to expand $refs.

I tried to strip down our schema a bit to illustrate the issue:

https://github.com/lukeschlather/nested-jsonapi-example/blob/master/docs/schemata/person.yaml

You can see for example that both the "create" and "batch create" operations are supposed to share the /schemata/person#/definitions/resource-without-revision properties, which define the "required" fields for a person. You can see here the generated markdown: https://github.com/lukeschlather/nested-jsonapi-example/blob/master/source/index.html.md

prmd combine --meta docs/meta.yaml docs/schemata/ | prmd verify  | prmd doc -o source/index.html.md

Note that all of the "Create" fields are listed as optional, rather than required.

I was curious if you could implement this in prmd, or if you have any suggestions about how to implement it I could also take a look.

[geemus]

I think attributes may nest those properties more deeply than I would expect? Outside that, one option might be to leave the attributes as they are, but just move the requires directly to the shared definition and pull it out to be along-side the other properties. My suspicion is definitely a mismatch with expected nesting levels of some sort, fwiw.