From fc604ef586d3bd055339349d5cbfe64d20ef27de Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Tue, 11 Jan 2022 13:36:01 +1100 Subject: [PATCH 1/2] Inheritance principle: No unsetting as corollary The rule regarding the fact that it is not possible to "unset" a key-value pair from a JSON file from higher in the filesystem hierarchy is here moved to the "corollaries" section. This is because this behaviour is a natural consequence of loading consecutive JSON files using a simple merge operation, and the absence of an equivalent to Python' "None" in the JSON specification. --- src/02-common-principles.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 57525b605c..5dfefb49f4 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -563,15 +563,12 @@ for more information. only the file lowest in the filesystem hierarchy SHALL be treated as being associated with that data file. - 1. For [JSON files](#key-value-files-dictionaries): - - 1. Files are loaded from the top of the directory hierarchy downwards, - such that values from the top level are inherited by all data files - at lower levels to which it is applicable unless overridden - by a value for the same key present in another metadata file at a lower level - (though it is RECOMMENDED to minimise the extent of such overrides). - - 1. There is no notion of "unsetting" a key/value pair. + 1. For [JSON files](#key-value-files-dictionaries), key-values are loaded + from files from the top of the directory hierarchy downwards, such that + key-values from the top level are inherited by all data files at lower + levels to which it is applicable unless overridden by a value for the + same key present in another metadata file at a lower level + (though it is RECOMMENDED to minimise the extent of such overrides). Corollaries: @@ -585,6 +582,11 @@ Corollaries: across multiple data files, it is RECOMMENDED to store metadata in this way, rather than duplicating that metadata content across multiple metadata files. +1. Where multiple applicable JSON files are loaded as per rule 5.2, key-values can + only be overwritten by files lower in the filesystem hierarchy; the absence of + a key-value in a later file does not imply the "unsetting" of that field + (and indeed there is no notion of such). + Example 1: Demonstration of inheritance principle {{ MACROS___make_filetree_example( @@ -623,10 +625,10 @@ metadata file `task-rest_bold.json` is read; file entity "`acq-longtr`" that is absent from the image path (rule 2.3). When reading image `sub-01/func/sub-01_task-rest_acq-longtr_bold.nii.gz`, metadata file `task-rest_bold.json` at the top level is read first, followed by file -`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` at the bottom level (rule 5.2.1); +`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` at the bottom level (rule 5.2); the value for field "`RepetitionTime`" is therefore overridden to the value 3000.0. The value for field "`EchoTime`" remains applicable to that image, and is not unset by its -absence in the metadata file at the lower level (rule 5.2.2). +absence in the metadata file at the lower level (rule 5.2; corollary 3). Example 2: Impermissible use of multiple metadata files at one directory level (rule 4) From 2590d0ac82a8689ceb861187d7a7ad360eded60e Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Thu, 13 Jan 2022 10:52:59 +1100 Subject: [PATCH 2/2] Inheritance principle: Rephrase corollary RE: unsetting --- src/02-common-principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 5dfefb49f4..6e1b7251d8 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -585,7 +585,7 @@ Corollaries: 1. Where multiple applicable JSON files are loaded as per rule 5.2, key-values can only be overwritten by files lower in the filesystem hierarchy; the absence of a key-value in a later file does not imply the "unsetting" of that field - (and indeed there is no notion of such). + (indeed removal of existing fields is not possible). Example 1: Demonstration of inheritance principle