Closed keighrim closed 6 months ago
Re-opening this after a recent discussion (https://github.com/clamsproject/app-swt-detection/issues/84).
Few suggestions from the latest discussion;
view.metadata.parameters
field for backward compatibility.
parameters
field to something else (rawParameter
, inputParameters
, userParameters
were mentioned), but I later realized that will be breaking backward compatibility. parameters
field.choices
but the passed value is not one of possible choices. Note that discarded parameters are still going to be recorded as UserWarning
s in the output MMIF. refinedParameters
, runtimeParameters
was newly suggested. However, after reviewing past issues, now I'd like to suggest something that doesn't include string "parameters". view.metadata.appConfiguredAs
. Hopefully, this will reduce some confusion of readers. Again, very open to more suggestions. Let us know what you think.
More on the versioning:
Let's first assume that we use firsthandParameters
and secondaryParameters
for names for the fields in discussion. Then, let's call the current version as x
and the next version with secondaryParameters
added as y
. We don't know for sure yet the actual values of those undecided variables. But we have pretty good candidates.
firsthandParameters
parameters
(keep as it's now.)userParameters
(completely new name, and definitely break early.)parameters
, userParameters
] (I pitched this as "non-breaking" during our meeting, but that's not true.)secondaryParameters
refinedParameters
(the old named used in #211.)runtimeParameters
(a new name proposed (and well-received) today.)appConfiguredAs
(a new name I proposed in the above comment.)x
1.0.n
(probably the only candidate)view.metadata
field can take any extra fields not defined in the schema as "opitonal" fields. (https://github.com/clamsproject/mmif/blob/1.0.3/schema/mmif.json#L55)y
1.0.n+1
(patch level)1.1.n
(minor level)2.0.n
(major level)schema
changes section)Here's some possible enumeration of MMIF generation
x_p
= MMIF generated under x
(firsthandP
== parameters
) , no secondary params recorded
x_p_s
= MMIF generated under x
(firsthandP
== parameters
), secondaryP
== any of candidates
secondaryP
as an extray_p
= MMIF generated under y+fP=p
(fP
== parameters
) , no secondary params
y_p_s
= MMIF generated under y+fP=p
(fP
== parameters
), sP
== anyy_u_s
= MMIF generated under y+fP=u
(fP
== userParameters
) , sP
== anyy_pu_s
= MMIF generated under y+fP=pu
(fP
== [userParameters
or parameters
]), sP
== anyThen the validation matrix;
valid under | x |
y+fP=p |
y+fP=u |
y+fP=pu |
---|---|---|---|---|
x_p |
valid | valid | invalid | ?valid |
x_p_s |
valid | valid | invalid | ?valid |
y_p |
valid | valid | - | - |
y_p_s |
valid | valid | - | - |
y_u_s |
invalid | - | valid | - |
y_pu_s |
?valid | - | - | valid |
(?-prefix means conditaonally valid )
(Please correct me if I did something wrong anywhere in the above, not so confident I though of all possible combinations of proposals)
After this calculation, it's pretty clear to me that we only do a patch number bump unless we wan't to change the name of existing parameters
field. In fact, we don't really have to update our json schema and bump MMIF version to support a secondary parameters field in the view metadata.
BTW, this is exactly one of the example scenarios for patch level bump from the previous discussion;
An addition of a field where
additionalProperties=true
: a newer input might have that new field, it was optional in the past anyway. Input is valid.
(I guess I didn't know that view.metadata
has additionalProperties=true
by default when I was suggesting 1.1.0 in #211 or here.)
Currently, in the MMIF json scheme, we have a place to store the runtime parameters.
https://github.com/clamsproject/mmif/blob/79c621f5c3dabb499a0878f30a59ca25b56bbb5d/schema/mmif.json#L93-L95
However, as raised in https://github.com/clamsproject/clams-python/issues/166 , often times apps will use some additional (or corrected/normalized) configuration (as their default behaviors) that are not necessarily passed at the runtime. Ideally, all these default configurations should be retrievable via the app metadata of that exact version, but I wonder if there's any value in adding one (optional) field (e.g.,
configuration
as a sibling toparameters
) in the MMIF to record the configuration after the "normalization" (see the linked issue, if you're not sure what this normalization is).