Include default values in the spec

[ap0llo]

As brought up in #16 it would be useful to include the default values for non-required fields in the spec.

I think for most fields some general rules can be formulated, but especially the arity field should have an non-null default

General Rules

• Boolean fields default to false
• Array fields default to an empty array
• Object fields default to a object filled with the default values of the specified type (i.e. the conventions field in the Document object defaults to a Conventions object with it's default values)

Argument Object / arity

I think in most CLIs, the default case for arguments is that an argument is optional and may appear once, so a sensible default for an argument's arity may be

{
  "minimum": 0,
  "maximum": 1
}

[baronfel]

An 'option' appearing once is IMO a bit up for discussion though - it's quite common for repeated uses of an option to either

• accrue/increase some logical counter (as in POSIX-style -v/-vv/-vvvvvvv scenarios)
• be overwritten in a 'last one wins' manner (as in --foo a --foo b => --foo b effectively)

and I'm sure there are other strategies that I'm missing as well. How do these modalities interact with Arity?

[ap0llo]

In my understanding, the arity field is currently only there for arguments but not for options.

However, I think it makes sense to have an arity on the Option object as well and I think there would need to be different default arities for options vs arguments.

I've opened up a separate discussion regarding the Option arity here: #35

[patriksvensson]

I don't think arity on the Option Object will do any good here since they only will take the values 0:1, 1:1, or 1:*.

I'm also starting to think that perhaps having an argument property on the Option Object is the wrong way to go here as well, since it makes things a bit difficult to understand and follow, and not sure if it really helps any use cases. I will open a new discussion around that.

Scenarios

The scenarios I can think of (that @baronfel mentioned as well) is:

1. Only one option with the same name is allowed per command.
2. Repeatable use of an option is allowed. If the option only takes one value (ex. arity is 0:1 or 1:1) then:
   1. That's an error.
   2. The last one wins.
   3. The first one wins. Never seen this personally, but might exist.

Special case

Then it's the scenario with the -v, -vv, and -vvv which accrue/increase some logical counter that @baronfel mentioned,
but I would be OK not supporting this initially in the spec.

[patriksvensson]

Here's a proposal for default values:

Document Object

Field Name	Type	Default Value	Description
opencli	string		REQUIRED The OpenCLI version number
info	CliInfo Object		REQUIRED Information about the CLI
conventions	Conventions Object		The conventions used by the CLI
arguments	[Argument Object]		Root command arguments
options	[Option Object]		Root command options
commands	[Command Object]		Root command sub commands
exitCodes	[ExitCode Object]		Root command exit codes
examples	[string]		Examples of how to use the CLI
interactive	bool	false	Indicates whether or not the command requires interactive input
metadata	[Metadata Object]		Custom metadata

CliInfo Object

Field Name	Type	Default Value	Description
title	string		REQUIRED The application title
summary	string		A short summary of the application
description	string		A description of the application
contact	Contact Object		The contact information
license	License Object		The application license
version	string		REQUIRED The application version

Conventions Object

Field Name	Type	Default Value	Description
groupOptions	bool	true	Whether or not grouping of short options are allowed
optionArgumentSeparator	string	U+0020 (space)	The option argument separator

Contact Object

Field Name	Format	Default Value	Description
name	string		The identifying name of the contact person/organization
url	string		The URI for the contact information. This MUST be in the form of a URI
email	string		The email address of the contact person/organization. This MUST be in the form of an email address

License Object

Field Name	Type	Default Value	Description
name	string		The license name
identifier	string		The SPDX license identifier

Command Object

Field Name	Type	Default Value	Description
name	string		REQUIRED The command name
aliases	[string]		The command aliases
options	[Option Object]		The command's options
arguments	[Argument Object]		The command's arguments
commands	[Command Object]		The command's sub commands
exitCodes	[ExitCode Object]		The command's exit codes
description	string		The command description
hidden	bool	false	Whether or not the command is hidden
examples	[string]		Examples of how to use the command
interactive	bool	false	Indicates whether or not the command requires interactive input
metadata	[Metadata Object]		Custom metadata

Argument Object

Field Name	Type	Default Value	Description
name	string		REQUIRED The argument name
required	bool	false	Whether or not the argument is required
arity	Arity Object		The argument arity. Arity defines the minimum and maximum number of argument values
acceptedValues	[string]		A list of accepted values
group	string		The argument group
decription	string		The argument description
hidden	bool	false	Whether or not the argument is hidden
metadata	[Metadata Object]		Custom metadata

Option Object

Field Name	Type	Default Value	Description
name	string		REQUIRED The option name
required	bool	false	Whether or not the option is required
aliases	[string]		The option's aliases
arguments	[Argument]		The option's arguments
group	string		The option group
description	string		The option description
recursive	bool	false	Specifies whether the option is accessible from the immediate parent command and, recursively, from its subcommands
hidden	bool	false	Whether or not the option is hidden
metadata	[Metadata Object]		Custom metadata

Arity Object

Field Name	Type	Default Value	Description
minimum	int	1	The minimum number of values allowed
maximum	int	1	The maximum number of values allowed. If not specified (nil), unlimited number of items are allowed

ExitCode Object

Field Name	Type	Default Value	Description
code	int		REQUIRED The exit code
description	string		The exit code description

Metadata Object

Field Name	Type	Default Value	Description
name	string		REQUIRED The metadata name
value	object		The metadata value

[patriksvensson]

Created issue: #58

[patriksvensson]

Added in #59