mapping-sheet: script omits original description when a reference is used for an object

[duncandewhurst]

Currently the flattened schema produced by the mapping-sheet script omits the original description (and other properties) for objects where a reference is used, this means users of the flattened schema may miss out on important context.

Example 1:

The description for buyer is:

The buyer is the entity whose budget will be used to purchase the goods. This may be different from the procuring entity who may be specified in the tender data.

However in the flattened schema this is replaced by the description from the referenced organizationReference object:

path	title	description
buyer	Organization reference	The id and name of the party being referenced. Used to cross-reference to the parties section

So the user misses out on the distinction between buyer and procuring entity.

Example 2:

The description for organizationReference/address is:

(Deprecated outside the parties section)

However in the flattened schema this is replaced by the description from the referenced address object:

path	title	description
buyer/address	Address	An address. This may be the legally registered address of the organization, or may be a correspondence address for this particular contracting process.

So the user can't see that the address object is deprecated in this case (the deprecation properties are not set because the address object itself has not been deprecated, just it's use in this location)

Suggested approach:

Where the reference is inside an array the mapping-sheet already produces two rows, one for the array and one for the objects in it, e.g.

path	title	description	type
planning/documents	Documents	A list of documents related to the planning process.	array
planning/documents	Document	Links to, or descriptions of, external documents can be attached at various locations within the standard. Documents may be supporting information, formal notices, downloadable forms, or any other kind of resource that should be made public as part of full open contracting.	object

We could extend that behavior to references which aren't in arrays, using a type of "reference" for the row displaying the properties of the parent:

path	title	description	type
buyer	Buyer	The buyer is the entity whose budget will be used to purchase the goods. This may be different from the procuring entity who may be specified in the tender data.	reference
buyer	Organization reference	The id and name of the party being referenced. Used to cross-reference to the parties section	object

[jpmckinney]

Assigning @Bjwebb as one of the committers on mapping-sheet-generator (the code for the mapping-sheet subcommand is just a copy of that).

[Bjwebb]

Looks like the problem is the deepcopy introduced in this commit - https://github.com/open-contracting-archive/mapping-sheet-generator/commit/87bc6e1e79738cccf3ee96340a4132a156ff5613

It would be useful to be able to see the associated issue - https://github.com/open-contracting-archive/mapping-sheet-generator/issues/3 - but I can't, presumably because that repo is archived. Which is odd, because GitHub says "You can also search for issues and pull requests within archived repositories.". @jpmckinney do you know anything more about this?

[jpmckinney]

Ah, it's because issues were also disabled. I've enabled issues, so that link should now work.

[Bjwebb]

Some code to fix this is now available on the 42-reference branch https://github.com/open-contracting/ocdskit/pull/51