document #362
inconsistent/undesirable property names or property value names
| Status: | closed | Start date: | 02/04/2020 | |
|---|---|---|---|---|
| Priority: | Normal | Due date: | ||
| Assignee: | - | % Done: | 0% |
|
| Category: | - | |||
| Target version: | DFDL v2.0 | |||
| Document Type: | Proposed Recommendation |
Description
For the next major version of DFDL, it would be good to clean up some of the property name or property value name inconsistencies.
This ticket is an open-ended list, in the updates/comments, of such observations about property/property value names.
These are coming in from reviewers of the specification over time, and being accumulated here.
Anything like this is going to be a phased-in kind of thing. I.e., we start accepting the new/changed values, but don't enforce that you must use them unless you set some flag that makes it not allow the older deprecated values/prop-names.
Things appearing on this list/ticket are not necessarily accepted for change/implementation. They are a list of suggestions to be considered.
ignoreCase => caseSensitive rationale: ignore is a verb. Verbs are less declarative than nouns. DFDL is supposed to be declarative.
lengthKind="explicit" but occursCountKind="expression". Inconsistent. The same property value should be used to indicate expressions for any property.
strict/lax not consistently used. We have trailingEmpty and trailingEmptyStrict, but no trailingEmptyLax, but we have strict/lax in as values for textNumberCheckPolicy.
Similarly, it would seem for consistency rather than trailingEmptyStrict and trailingEmpty there should be a trailingEmptyPolicy with values strict/lax.
Policy vs. Kind, vs. Mode suffix: There are things that are setting policies that don't end with the suffix "Policy", which we adopted late in the game. We have suffixes "Kind", "Mode", "Policy" but no rules for when we use these. Things with values "strict" or "lax" are all Policy, but other things are also policy (emptyValueDelimiterPolicy). Some things are Kind like lengthKind and occursCountKind, but generateEscapeBlock is "always" or "whenNeeded" but is not a "Kind" nor "Policy".
There is only one property with "Mode" suffix, and that is textNumberRoundingMode, and that use of "mode" is consistent with outside usage of many things that discuss rounding for numbers, so that is ok. However, prose that discusses the dfdl:calendarCheckPolicy (which has values strict/lax), discusses them as strict "mode" and lax "mode". We should change this to "policy" for consistency.
History
Updated by Michael Beckerle over 2 years ago
A request was made to shorten "documentFinalTerminatorCanBeMissing" to just "finalTerminatorCanBeMissing".
Recording this here to avoid recreating this rationale.
I think I can argue for why it has to be the more verbose "documentFinalTerminatorCanBeMissing".
We might shorten to "documentTerminatorCanBeMissing", but the prefix "document" is important.
First let me discuss why we're stuck with "document" generally.
I would also rather these "documents" were just called "items" or similar less-committal noun, but we are stuck with this formal use of the term "document" from XML, XML Schema, etc.
I have heard people use the term "data document" to clarify that a chunk of XML is formally a document according to the XML well-formedness rules and such, but distinguishing that it's not a human document like someone would read or write, but rather is just a chunk of data.
E.g., when you use SOAP over HTTP protocol, which is a remote procedure call mechanism, you pass an XML data document from the caller to the called context. DFDL uses document in this sense. We mean data document because that's the way we're using XML and XML Schema. If you are parsing messages from a stream, then one parse call returns one message as an XML data document.
About use of "documentFinal..." versus just "final....".
That is intentionally verbose because this property doesn't apply in any relative sense of "final" but only the outermost document scope sense of final.
This leaves us free to use the un-decorated word "final" in a looser sense. E.g., we can discuss the final term in a sequence, or the final character of an element's representation. Those are relative uses of the term "final" to the thing I'm talking about. It's a synonym for "last". When we really want to talk about the ultimate end of things, then "document final" is the way you do that.
If we were going to shorten the name, I claim "documentTerminatorCanBeMissing" is more appropriate, because a terminator is already final in a relative sense and a document can have only one terminator in the data stream, so the word "final" is redundant.
Updated by Michael Beckerle almost 2 years ago
Updated by Michael Beckerle almost 2 years ago
- Status changed from submitted to closed
(Other formats not available in this archive.