-
Notifications
You must be signed in to change notification settings - Fork 19
How should we represent argument types? #11
All reactions
-
👍 1
Replies: 7 comments 11 replies
@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
All reactions
@AllanOricil answered here: oclif/oclif#1806 (comment)
All reactions
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.
All reactions
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
All reactions
-
👍 1
File paths in one CLI framework: https://ajalt.github.io/clikt/parameters/#file-paths
All reactions
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).
All reactions
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.
All reactions
-
👍 2
Perhaps with JSON Schema as OpenAPI do?
All reactions
|
Here is an initial proposal. I've aimed to keep the functionality minimal while still ensuring usability. Primitive types
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 Schema
FormatsInteger
Float
String
|
All reactions
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
All reactions
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
All reactions
-
👍 1
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
All reactions
-
👍 1
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.)
All reactions
-
👍 1
Whether a file is input/output, directory/file, and file type are concerns that are useful for autocompletion system, for example.
All reactions
-
👍 1
File or directory paths are super useful. I would also like to have other symbols typed like the - symbol for stdin which is common
All reactions
-
👍 1
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.
All reactions
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.
All reactions
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.