Schema: Location of definitions

[kindly]

At the moment the schema reference page just gives the list of all the fields within all the definitions that exist in the extension.

It would be useful to also display what paths (i.e jsonpointer paths) within the schema showing where those definitions live.

[timgdavies]

In thinking this through, I think we hit a slight issue in that it may only be useful to know about the dereferenced schema paths, but this can lead to lots of duplication of information. E.g. if you extend 'value' object, you don't really want to show users every single place this is changed.

I think though we can interpret updates to things in "/definitions" as 'additional fields every where that object X is used', and updates to things under '/properties' as 'additional fields in X section'.

I've mocked this up below.

I've mocked this up below. Note also that in this mock up I've:

• Used <code></code> around all the field names (a personal preference on formatting perhaps, but helps make clear what is field vs. what is title);

• Ordered the blocks of schema so that the update to something in '/properties' comes first (and ideally comes before the objects it then references);

• Updated the final column so that it does not just say 'Array', but says 'Array of X object' when that is the case (or 'Array of strings', 'Array of numbers' etc. if that was the case) and that it links to the relevant schema block that then defines those

[kindly]

@timgdavies thanks for the mockup. That was pretty close to what I was getting at.

• I was referring to the dereferenced schema paths in this issue. The text below each heading in the mockup could be:

Item objects exist at the following paths:

/awards/items
/tender/items
/contract/items

This extension introduces the following properties to the objects at those locations:

So we just show all the dereferenced paths, as that seems to be the most useful. I do not think there will ever be too many for this to be a problem, even for the Value object in my opinion, but we could have a cutoff of say 5 (and perhaps a modal showing them all).

[jpmckinney]

I've done part of this. The remaining parts are:

• re-ordering definitions so that referenced objects are shown after objects referencing them (I might have some code for easily determining dependency order in pupa-ruby)
• adding the list of referring fields after the paragraph (adding, ", which is used at" to the end of the paragraph to introduce the list)