Skip to content

Navigation Menu

Sign in
Sign up

How should we represent argument types? #11

Unanswered
Discussion options

You must be logged in to vote

Replies: 7 comments 11 replies

Comment options

@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

You must be logged in to vote
0 replies
Comment options

You must be logged in to vote
0 replies
Comment options

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.

You must be logged in to vote
4 replies
Comment options

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

Comment options

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

Comment options

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).

Comment options

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.

Comment options

Perhaps with JSON Schema as OpenAPI do?

You must be logged in to vote
0 replies
Comment options

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
You must be logged in to vote
4 replies
Comment options

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

Comment options

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

Comment options

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

Comment options

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.)

Comment options

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

You must be logged in to vote
1 reply
Comment options

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

Comment options

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.

You must be logged in to vote
2 replies
Comment options

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.

Comment options

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Converted from issue

This discussion was converted from issue #3 on July 09, 2025 11:01.

AltStyle によって変換されたページ (->オリジナル) /