Change syntax for Level 1 by wrapping optional JSON fields in “Optional:”

[vdhamer]

Why change?

• Progressive disclosure. The data format is less intimidating when you can clearly see which fields in the level1.json format must be provided. And which ones can be postponed or even left out altogether. Consider it a documentation thing: users typically ignore readme files - in favor of videos, FAQs, in-app feedback.
• Consistency. The level2.json format already uses “Optional:” for comparable reasons.
• Safety. Currently you don’t get any feedback if you omit a mandatory field (typically IDs). So an explicit distinction prevents unexpected behavior. Yes, we may add proper schema-based validation of the input file later. And/or an standalone app for data entry and maintenance.

Backwards compatibility

The old syntax:

{
    “IdPlus”: { .. },
    “coordinates”: { .. },
    “somethingOptional1“: { .. },
    “somethingOptional2”: { .. }
    :
}

The new syntax:

{
    “IdPlus”: { .. },
    “coordinates”: { .. },
    “optional”: { 
        “somethingOptional1“: { .. },
        “somethingOptional2”: { .. }
        :
    }
}

So older app versions will be able to find all mandatory fields because the path hasn’t changed.
But optional fields in the new syntax will be ignored by older app versions.
For example, 2.7.0 versions of the app will not find somethingOptional1 because they are looking for it at foobar/somethingOptional1 instead of foobar/optional/somethingOptional1.

Stepwise release of root.level1.json file

1. Stick to old root.level1.json format as long as new app release is not available
2. Provide testers on TestFlight a version which loads a temporarytemproot.level1.json
3. Release app ver 2.7.1 using root.level1.json
4. Replace root.level1.json
5. At some point, delete temproot.level1.json

The only glitch to expect is “what if user of 2.7.0 doesn’t upgrade and thus runs 2.7.0 while fetching the new syntax version of root.level1.json. But this will hardly be visible: new clubs will appear, while having coordinates on the map, will have hardcoded level2.json members and portfolios. But will not see changes to e.g. remarks or club websites.

Note that “not upgrading” may sound temporary, but 2.7.1 was expected to require iOS 18. Which could delay the upgrading to 2.7.1. So maybe the iOS 18 requirement should be moved to a separate 2.8 release. To allow users to upgrade to the new file format, even if their phone doesn’t support iOS 18, which would effectively delay upgrading until the user buys a new device!

Stepwise development

• add new "optional" in Level 1 syntax. Data examples.
• add new "optional" in Level 1 syntax. Data files.
• add new "optional" in Level 1 syntax. Code.
• Handle new type of club officers #429
• Update to data model diagram (isDeceased, isOther)
• Undo dependency of iOS 18 of release 2.7.1