Updates to the "design" group, in order to accommodate vessels with a variable keel or centerboard and some other changes

[fabdrol]

Hi all,

I've made various changes to the group design. Initially, I needed a way to store information regarding a variable keel height and info about sails. Whilst doing so, I made some other changes as the group looked very unfinished.

Changes:

• Various descriptions
• Removed "name" (as it's already in vessel)
• Changed "draft" to be an object (with minimum and maximum properties)
• Changed "length" to be an object (with overall, hull and waterline properties)
• Removed "sailArea", added "sails"
• Added "keel"
• Added type "sail" to definitions.

Whilst doing the changes, some questions popped up regarding keel and sails. In the PR, I've added state to both keel and sails (sails/active and keel/state); this seemed wrong. Would it be an idea to add a group called state to each vessel, which can then be used to store variable information?

[tkurki]

I find it hard to reason about schemas with just the schema def. Do you have a sample for a boat that would give meaning to this all and serve as a validation test at the same time?

Label & name for the same thing, and name is unique? How about id and label?

[tkurki]

I don't see a aplace for current draft?

[fabdrol]

@tkurki what do you mean? It's referenced in vessel.json

[timmathews]

@tkurki, I also find it difficult to reason about JSON schema files, so here is a list of the paths for each value defined in design.json. The ~ is shorthand for the path to your boat's info in the schema.

~/design/displacement/source
~/design/displacement/timestamp
~/design/displacement/value

~/design/draft/source
~/design/draft/timestamp
~/design/draft/minimum
~/design/draft/maximum

~/design/canoeDraft/source
~/design/canoeDraft/timestamp
~/design/canoeDraft/value

~/design/length/source
~/design/length/timestamp
~/design/length/overall
~/design/length/hull
~/design/length/waterline

~/design/keel/source
~/design/keel/timestamp
~/design/keel/type
~/design/keel/state

~/design/sails/available/{^[a-zA-Z0-9]$}/brand
~/design/sails/available/{^[a-zA-Z0-9]$}/type
~/design/sails/available/{^[a-zA-Z0-9]$}/material
~/design/sails/available/{^[a-zA-Z0-9]$}/area
~/design/sails/available/{^[a-zA-Z0-9]$}/name
~/design/sails/available/{^[a-zA-Z0-9]$}/label
~/design/sails/available/{^[a-zA-Z0-9]$}/minimumWind
~/design/sails/available/{^[a-zA-Z0-9]$}/maximumWind

~/design/sails/active/{^[a-zA-Z0-9]$}/brand
~/design/sails/active/{^[a-zA-Z0-9]$}/type
~/design/sails/active/{^[a-zA-Z0-9]$}/material
~/design/sails/active/{^[a-zA-Z0-9]$}/area
~/design/sails/active/{^[a-zA-Z0-9]$}/name
~/design/sails/active/{^[a-zA-Z0-9]$}/label
~/design/sails/active/{^[a-zA-Z0-9]$}/minimumWind
~/design/sails/active/{^[a-zA-Z0-9]$}/maximumWind

~/design/sails/area/total
~/design/sails/area/active

~/design/sails/source
~/design/sails/timestamp

~/design/beam/source
~/design/beam/timestamp
~/design/beam/value

~/design/airHeight/source
~/design/airHeight/timestamp
~/design/airHeight/value

[fabdrol]

@timmathews thanks. What's your view on the changes, and my question regarding state?

[timmathews]

I have a few concerns:

1. I've never heard the term "canoe draft" before. Is it a catamaran thing? Or is it a regional term? Regardless, it should live under draft, not as its own thing.
2. Keel type should probably include canting as an option, and we need to store keel angle.
3. I don't see the value in a separate area for active sails, why not just a flag on each sail to indicate whether it's in use? But ... this brings me to the next point
4. The design section really ought to contain fixed info that doesn't change (or at least doesn't change very often). So the list of sails currently in use, total area (which could probably be calculated on the fly), keel stats (angle, amount lowered, etc) would be better located in the performance section since those things directly affect how fast the boat is going to go.

[fabdrol]

@timmathews 3 & 4 relate to my concern regarding "state". I think it should be in a different group altogether - called state - where we store "volatile" information. I agree with your points regarding static information.

canoedraft: same here, but it was in there so I kept it. To be honest, the original version of design.json seemed to be done in a hurry as the descriptions were all off.

So, todo: a new group for state information and some changes to design?

[timmathews]

But isn't most of the model "state"? I think we need a better name for the grouping of "current physical vessel configuration." However, I agree in principle that we need a separate location for it. Other things that might end up in there are position of trim tabs for power boats, up/down state of stabilizers, etc.

[keesverruijt]

I've never heard the term "canoe draft" before. Is it a catamaran thing? Or is it a regional term? Regardless, it should live under draft, not as its own thing.
I’ve heard it before. Canoe is the hull without the keel.

Keel type should probably include canting as an option, and we need to store keel angle.
I don't see the value in a separate area for active sails, why not just a flag on each sail to indicate whether it's in use? But ... this brings me to the next point
The design section really ought to contain fixed info that doesn't change (or at least doesn't change very often). So the list of sails currently in use, total area (which could probably be calculated on the fly), keel stats (angle, amount lowered, etc) would be better located in the performance section since those things directly affect how fast the boat is going to go.

That was my main concern as well. And if the design part is fixed, why does it need a source and timestamp?
If we remove those the entire design section can be both ‘shallower’ and simpler.

[fabdrol]

@canboat that would make this specific group quite different from the rest/our conventions... Don't you think that might introduce confusion? Otherwise I'm all for reducing boilerplate.

[tkurki]

How about

• put stuff that very rarely changes, like hull & rig dimensions, under design
• add separate top level branch for sails

~/sails/$byId/$sailRef

defs/sail/brand | type | material | inUse (true/false) | area | name | label | minimumWind | maximumWind

Under design a URI might be useful to identify designs, say http://www.signalk.org/boatdesigns/melges24.

[tkurki]

Suggestion: future schema updates should include a test/sample that covers the proposed change. Like the stuff under https://github.com/SignalK/specification/tree/master/samples.

That way we can accumulate a test suite and with future changes some easy indication of how it affects stuff done previously - you have to either modify the accumulated samples to be in line with the proposed change or make the change backwards compatible.

[fabdrol]

@tkurki +1 for sails at the top-level
@timmathews that's a good point. But, apart from sails, there will be other stuff that changes often (like your state - underway using engine etc)

[tkurki]

Imho navigation state should be under navigation...

[fabdrol]

sure, but it was just an example

[tkurki]

It was really about seconding Tim's point that there is no separate state, stuff should find a logical place in the model. State of your AC charger, state of your navigation lights...the list goes on.

[rob42]

There is a key already for vessel 'state', eg underway, etc
'~.navigation.state' was added to hold the AIS options:
(from my code)

                navStatusMap.put(0, "Under way using engine");
        navStatusMap.put(1, "At anchor");
        navStatusMap.put(2, "Not under command");
        navStatusMap.put(3, "Restricted manoeuverability");
        navStatusMap.put(4, "Constrained by her draught");
        navStatusMap.put(5, "Moored");
        navStatusMap.put(6, "Aground");
        navStatusMap.put(7, "Engaged in Fishing");
        navStatusMap.put(8, "Under way sailing");
        navStatusMap.put(9, "Reserved for future amendment of Navigational Status for HSC");
        navStatusMap.put(10, "Reserved for future amendment of Navigational Status for WIG");
        navStatusMap.put(11, "Reserved for future use");
        navStatusMap.put(12, "Reserved for future use");
        navStatusMap.put(13, "Reserved for future use");
        navStatusMap.put(14, "Reserved for future use");
        navStatusMap.put(15, "Not defined (default)");

[fabdrol]

@tkurki @canboat @timmathews @rob42 this PR was a bit stale, sorry for that. I've committed some more changes according to our discussion up here; the only thing I have not done yet is change anything on the sails bit. I'm actually in favour of moving this to a separate group. I believe that could proof useful for racing vessels in particular.

[fabdrol]

I removed the group sails in order to move it into a separate group (#67). @timmathews @tkurki @canboat @rob42 any more feedback or shall I merge?

[rob42]

Same as #67, merge as experimental and review later