Fix inconsistent JSON key styles

biocompute-objects / BCO_Documentation

Repository for documentation to support the IEEE 2791-2020 standard. Please see our home page for communications/publications:

http://biocomputeobject.org/

BSD 3-Clause "New" or "Revised" License

16 stars 12 forks source link

Fix inconsistent JSON key styles #30

Closed stain closed 6 years ago

stain commented 6 years ago

There are some inconsistencies in JSON key names. Generally BCO use lower_case_with_underscore which is common in JSON.

Some inconsistencies that unnecessarily deviate from this style should be fixed, for example:

Name in domain_prerequisites
false discovery vs false_discovery in error_domain examples
BCO_id in top level (why not bco_id ? )
FHIR_extension including FHIRendpoint_Resource, FHIRendpoint_URL and FHIRendpoint_Ids
github_URI in github_extension

corburn commented 6 years ago

address instead of url or uri

HadleyKing commented 6 years ago

Agreed on everything but the following:

BCO_id in top level (why not bco_id ? )

I think that distinguishing the defining field in the BCO is important, and as such the CAPS are appropriate. If anyone disagrees, please convince me.

corburn commented 6 years ago

@HadleyKing why is the principle of least astonishment (i.e. be boring/predictable) important?

Take for example the task of entering a URL. How closely do you need to study the specs, cross-reference them with the schema, and cross-reference again with the examples to determine which key should be used in a given section?

Should I use:

script
address
URI
uri
Github_URI
Github_URL
github_uri
github_url
GitHub_url
Github_Url
githubURL
github_URI
FHIRendpoint_URL
FHIRendpoint_Resource
fhir_endpoint_url
FHIR_endpoint_URL
FHIR_Endpoint_URL
FhirEndpointUrl
FhirEndpointURL
...

After determining which key to use, what combination of other keys must be set for a URL to be valid?

As a specification, you are setting the standards of consistency for others to follow. It is much easier to follow a consistent convention than to wade through a series of ever growing exceptions.

corburn commented 6 years ago

@HadleyKing you changed the case of all the fhir* keys to lowercase in the HCV1a.json and most of the keys in the antiviral_resistance_detectionTypeDef.json

The FHIR_extension in the schema was not changed nor were its other occurrences: https://github.com/biocompute-objects/BCO_Specification/blob/f25293352bd2d806acaf4909717c20ebf1985d74/bco-domains.md#L20

https://github.com/biocompute-objects/BCO_Specification/blob/d0aa195bdbd64ce43291277affcbec7f02cb56a5/user_guide.md#L493

@jpat1546 you closed #20 which cites the same consistency issue without resolving it.