How the OpenAPI importer reads a document

This is the detail behind Where packages come from: what jadpo package import openapi <file> reads from a provider's OpenAPI document, what it writes, and what it leaves for you or your agent to check.

• Where it writes. Always the app's own integration, shared/providers/<name>/<version>/; installing another Jadpo app's package into packages/ is jadpo package add. The name and version are --as AcmeCouriers.v1, or the document's title in UpperCamelCase and its version's major number (1.4.0 is v1), or its date (2024-06-20 is v2024_06_20), else v1, as for a Jadpo application, whose document's version is a hash of its record.
• What it reads. OpenAPI 3.0 and 3.1 as JSON, from a local file. YAML and Swagger 2.0 are refused with what to do (cli.package_unreadable and cli.package_not_openapi, listed under Command errors). Nothing is fetched.
• The files. package.jadpo with Licence.proprietary (an own integration may use it) and jadpo: "1.0"; provider.jadpo with protocol: Protocol.json_http, imported: { file: digest: } (the path from the project's root and sha256: of the file's bytes), hosts: { live: } from the first absolute server, and credential: CredentialScheme.bearer or .basic from the security schemes; a resource per tag, in resources/, every resource public; the types and failures the operations reach, each public in its own file, and nothing else of the description. Every operation is source: PackageSource.imported.
• Operations. By path, then get, put, post, delete and patch. A resource is the operation's first tag in lower_snake_case, else its path's first fixed segment that isn't a version. On the resource's shortest fixed path an operation is list or create; with one placeholder after it get, update (replace for a PUT beside a PATCH) or delete; any other is its operationId in lower_snake_case, or a Jadpo application's method and fixed segments (post_archive). Its input is its body's type when it has no placeholders or query parameters, else <Resource><Operation>Input holding them and the body's fields; header and cookie parameters and a body that isn't JSON are left out and listed. Its output is its lowest 2xx answer's JSON body.
• What it can't know from another provider is written the safe way and listed: changes: true for every method but GET, no idempotent:, no failures, no idempotency: or error_code:, and no sandbox host.
• Types. The exact mappings of Mapping imported types to standard types (date-time Instant, date CalendarDate, email Email, uri Url, uuid Uuid, ipv4 and ipv6 IpAddress, byte Bytes, duration Duration, and an enumeration of ISO 4217 codes Currency or of ISO 3166-1 codes Country), integer Int, number Decimal, boolean Bool, an array List (Set with uniqueItems), an object of one kind of value Map<Text, V>, and their rules (minLength, maxLength, pattern, minimum, maximum, minItems, maxItems). A field not required, or nullable, is ?. An object or enumeration inside another is a type of its own, <Parent><Field>; a constrained item of a list is a refined type, <Parent><Field>Element. A schema named as a built-in type is <Name>Type, and listed. oneOf and anyOf of several shapes, and an object of any fields, are left out and listed. Shape and name detection is under "Shape and name detection".
• A Jadpo application's document (one whose operations carry x-jadpo-changes) is read exactly: each field's type from x-jadpo-constraints, changes: from x-jadpo-changes, idempotent: true where a key keeps the response, the provider's idempotency: from x-jadpo-idempotency, error_code: "error.code", its failures from x-jadpo-failure (named from the code, with its kind and message), no host (the connection gives host:), and no finding. Its runtime's own routes (x-jadpo-generated: the exchange, passkeys, the served document) are left out. An API that signs callers in only with a browser session gets no credential, and a finding.
• Importing again merges one declaration and one member at a time: what the description adds is added, what both have is kept as the file has it, so corrections survive, and what only the file has is kept and listed; only imported: is always the description's. A file that doesn't read is left alone and listed.
• The summary says what was written where and counts what the package holds, lists a merge's changes, and groups what is left to check by what to do, each (agent), with --json for agents.
• Field and variant names on the wire. A field or variant is the provider's name in lower_snake_case; where that differs (collectAt, after-noon, or type written type_value to avoid a reserved word), the importer writes the provider's spelling as the field's or variant's wire_name: (Decoding).

Importing Smithy, Postman, HAR and .d.ts isn't built yet: each is toolchain.not_built_yet.