How should we represent argument types?

[patriksvensson]

[AllanOricil]

@mdonnalley this could be useful to ease the usage of CLIs built with oclif by AI agents. You can help defining the standard using oclif's well rounded model. Then you can create @oclif/plugin-opencli

[cristiand391]

@AllanOricil answered here: oclif/oclif#1806 (comment)

[xoofx]

Love the initiative! 🤗

It would be quite valuable to support argument types to automate parsing from the specs to a strongly typed language.

I would think that having a default string type and then provide support for:

• some basic primitive types: bool, i8, u8, i16, u16, i32, u32, i64, u64, f32, f64
• some common structured types: guid, datetime, url...

In case of list arguments e.g. separated by , with primitive/structured types, using vec<i32> with only one level for now would be enough. (e.g. no vec<vec<xyx>>)

Should cover most of the usecases and things can be expanded further in minor versions.

[ap0llo]

Since arguments to CLI tools often are file systems paths, I think it could be useful to also have "file path" and "directory path" types to allow for more stongly-typed clients to be generated (rather than treating all paths as strings).

Also, CLIs often define a finite set of allowed values for a argument, so something like an user defined "enum type" could be useful.
maybe something along the lines of JSON Schema's Enumerated values

[mikaelstaldal]

File paths in one CLI framework: https://ajalt.github.io/clikt/parameters/#file-paths

[idle-code]

I would extend it event further and introduce "non existent file path" and "existing file path" as there are tools that expect the passed argument to exist (consumers) and not (often asking if the file should be overridden if it's present).

[joffrey-bion]

In the Clikt framework mentioned above, it is possible to express whether this path should be a directory, a file, or either; whether it should already exist, must not exist, or it doesn't matter; whether it should be readable, writable, or both, etc. It would be nice if the spec could encompass that as well.

[mikaelstaldal]

Perhaps with JSON Schema as OpenAPI do?

[patriksvensson]

Here is an initial proposal. I've aimed to keep the functionality minimal while still ensuring usability.

Primitive types

Type	Description
integer	Represents an integer number. Defaults to i32 format if format is not specified.
float	Represents a floating point number. Defaults to f32 format if format is not specified.
string	Represents zero or more characters.
boolean	Represents true or false. Does not support formats.

Additional type-specific keywords can be used to refine the data type, for example, limit the string length or specify a maximum value for an integer.

An optional format keyword serves as a hint for tools to use a specific format. Supporting formats are optional and may vary between implementations.

Schema

Field Name	Type	Description
type	string	REQUIRED. The base type of the value.
format	string	A format hint specific to the type. Optional.
minimum	integer | float	Specifies the inclusive lower bound. Only applicable to integer or float.
maximum	integer | float	Specifies the inclusive upper bound. Only applicable to integer or float.
minLength	integer	The minimum number of characters (inclusive). Only applicable to string.
maxLength	integer	The maximum number of characters (inclusive). Only applicable to string.

Formats

Integer

Format	Description
u8	Unsigned 8-bit integer
u16	Unsigned 16-bit integer
u32	Unsigned 32-bit integer
u64	Unsigned 64-bit integer
i8	Signed 8-bit integer
i16	Signed 16-bit integer
i32	Signed 32-bit integer
i64	Signed 64-bit integer

Float

Format	Description
f32	Single-precision floating point type.
f64	Double-precision floating point type.

String

Format	Description
file	A file name
directory	A directory name
url	A Uniform Resource Identifier as defined in RFC3986
email	An email address as defined as Mailbox in RFC5321
regex	A string containing a regular expression pattern, as defined in ECMA-262

[mikaelstaldal]

I suggest we also support pattern property for strings, to restrict the syntax of a string with a regular expression, like OpenAPI and JSON Schema: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-01#section-6.3.3

[mikaelstaldal]

I suggest we also support enum property for strings, to restrict the value to a fixed set, like OpenAPI and JSON Schema: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-01#section-6.1.2

[mikaelstaldal]

I suggest the url format is named uri to avoid confusion, and to be consistent with OpenAPI and JSON Schema: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-01#name-resource-identifiers

[mikaelstaldal]

I suggest we don't have a float type, since binary floating-point numbers have surprising semantics, and are most of the time not what you would want in this context. A proper decimal type would be better, but best to leave non-integer numbers out completely, you can always encode them as string anyway (especially if we support a regular expression pattern).

(At least, the minimum/maximum values should be exclusive (open range) for float, since close ranges and equality comparisons are not recommended.)

[cmcgee1024]

Whether a file is input/output, directory/file, and file type are concerns that are useful for autocompletion system, for example.

[doron-cohen]

File or directory paths are super useful. I would also like to have other symbols typed like the - symbol for stdin which is common

[reitzig]

For practical reasons, I think it makes sense to use exactly the data types and formats from the JSON schema version used to express the OpenCLI format (2020-12 currently). Anything different wouldn't be supported by general-purpose schema validators, IDEs etc, which might make it hard to write OpenCLI specs in common editors/IDEs.

[cmcgee1024]

Unfortunately, the JSON schema spec has no format for files. Given how crucial they are for this domain, I think an exception should be made for them, and also further semantics as mentioned in previous comments.

[reitzig]

It should be possible to cover the syntactic restrictions of stringy types with formats and, where unavailable, pattern.

Neither is available for numeric types, although some can modelled using min and max.