847 record uniqueness

[duncandewhurst]

Closes #847

records_reference.md:

• Update the first paragraph to clarify the uniqueness rules for records.
• Update Record structure to clarify that:
  • the releases list need only contain all releases at the time of the record's publication.
  • the versioned release need only contain a history of changes up to the time of the record's publication.
• Update Compiled release to clarify that the compiled release need only contain the latest values at the time of the record's publication.

releases_and_records.md

• Change 'While releases are never updated, records are updated each time there is a change.' to 'While releases are never updated, records can be updated each time there is a change.' to clarify that there is no requirement to update old records.

• Update .description in record-package-schema.json to describe only a record package, similar to description in release-package-schema.json. Previously, .description also paraphrased the description of a record in definitions.Record.description, possibly because there is no record-schema.json file. However, I think it's best to document the description of a record in only one place in the schema.

• Update .description in definitions.Record:

  • Align with the first sentence of records_reference.md.
  • Describe only the must/should/may rules for the releases list, compiled release and versioned release.

  Previously, .description also paraphrased the descriptions from .properties.releases, .properties.compiledRelease and .properties.versionedRelease. However, I think it's best to document the descriptions of each property in only one place in the schema.

• Update .description in definitions.Record.properties.releases to clarify that the releases list need only contain all releases at the time of the record's publication

• Update .description in definitions.Record.properties.compiledRelease to clarify that the compiled release need only contain the latest values at the time of the record's publication and to replace 'latest version of all the contracting data' with 'latest value of each field'.

• Update .description in definitions.Record.properties.versionedRelease to clarify that the versioned release need only contain a history of changes up to the time of the record's publication and, since a versioned release can be published independently of a compiled release, replace 'all the data in the compiled release' with 'each field'.

[duncandewhurst]

@jpmckinney, before I request a review from a helpdesk analyst, should we also document the uniqueness rules in the schema by adding the following to the description of Record?

There should be a single record per contracting process per distribution, where a distribution might be a specific API endpoint or a specific bulk download file.

[jpmckinney]

@duncandewhurst I have not reviewed, but yes, makes sense to also update the schema.

[jpmckinney]

You'll need to merge 1.2-dev to get tests to pass.

[mrshll1001]

All these changes reflect the clarifications indicated, and are very well written.

[jpmckinney]

I prefer using "releases about a contracting process" throughout instead of related to, because a release is a data artifact that describes a real-world contracting process (an "about" relationship), whereas "relates to" is much more generic (e.g. a release about a contract renewal could, in a sense, "relate" to the original contract).

[duncandewhurst]

Makes sense. Fixed in 5b055f7

[jpmckinney]

The "must" statement is enforced by required, which I don't think we typically repeat in field descriptions. I wonder whether the should statement can be moved to the compiledRelease description. The remaining "may" statement is not necessary.

[duncandewhurst]

I guess the original intention was to have all the statements in one place. However, that need is met by records_reference.md so I've made the changes you suggest in 5521210

[jpmckinney]

Thanks!