lakutata 3.0.0 → 3.1.1

package/doc/en/DBus.md

@@ -0,0 +1,291 @@
+# Lakutata D-Bus
+
+D-Bus is the message bus of the Linux desktops and system services: the programs of a machine call each other's
+methods, read each other's properties and listen to each other's signals through it. The package `@lakutata/dbus`
+serves controller methods as the methods of a D-Bus service, exposes objects, properties and signals, and calls the
+other services as a client. It is not part of `lakutata`:
+
+```bash
+npm install lakutata @lakutata/dbus
+```
+
+It needs a D-Bus daemon: the session bus or the system bus of a Linux machine, or a private bus started with
+`dbus-daemon` (for the tests, and on macOS with the `dbus` package of Homebrew).
+
+## 1. A service
+
+```typescript
+import {Application, DTO} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {Expect, Return} from 'lakutata/decorator/dto'
+import {dbusEntrypoint, DBusInterface, DBusMethod} from '@lakutata/dbus'
+
+class ConfigureDTO extends DTO {
+    @Expect(DTO.String().required())
+    public sn: string
+
+    @Expect(DTO.Number().integer().min(0).optional())
+    public retries?: number
+}
+
+@DBusInterface('com.example.Manager', {path: '/com/example/Manager'})
+class ManagerController extends Controller {
+    //No argument, returns a string (s)
+    @DBusMethod('Ping', {returns: 's'})
+    public async ping(): Promise<string> {
+        return 'pong'
+    }
+
+    //One argument a{sv}, returns a dictionary a{sv} (the type of @Return)
+    @DBusMethod('Configure', ConfigureDTO)
+    @Return(ConfigureDTO)
+    public async configure(input: ConfigureDTO): Promise<ConfigureDTO> {
+        return input
+    }
+}
+
+Application.run(() => ({
+    id: 'devices.app',
+    name: 'Devices',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [ManagerController],
+            dbus: dbusEntrypoint({bus: 'session', service: 'com.example.DeviceService'})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+```text
+$ gdbus call --session --dest com.example.DeviceService --object-path /com/example/Manager --method com.example.Manager.Ping
+('pong',)
+$ gdbus call --session --dest com.example.DeviceService --object-path /com/example/Manager --method com.example.Manager.Configure "{'sn': <'A1'>, 'retries': <3>}"
+({'sn': <'A1'>, 'retries': <3>},)
+```
+
+- `@DBusInterface(name, {path})` makes a controller an interface, served at an object path. Several controllers with
+  the same path are the interfaces of the same object.
+- `@DBusMethod(name, DTO?, options?)` makes a method of the controller a method of the interface. Its options are
+  those of every action, and `returns`, the type of its result (section 3).
+- Every object also implements `org.freedesktop.DBus.Properties`, `Introspectable` and `Peer`; the root object `/`
+  implements `ObjectManager`.
+- On a machine with systemd, `busctl --user call com.example.DeviceService /com/example/Manager com.example.Manager
+  Ping` does the same as the first `gdbus` command.
+
+## 2. The adapter
+
+| Option | Default | Meaning |
+|---|---|---|
+| `service` | required | The well-known name of the service: elements of letters, digits and `_`, separated by dots |
+| `bus` | `'session'` | `'session'` (the address in `DBUS_SESSION_BUS_ADDRESS`), `'system'`, an address (`'unix:path=…'`, `'tcp:host=…,port=…'`), or the path of the socket of a private bus |
+| `replaceExisting` | `false` | Take the name from its owner, when the owner allows it |
+| `allowReplacement` | `false` | Let another service take the name |
+| `decode` | `{int64: 'number'}` | How the arguments are decoded (section 3) |
+| `name`, `middlewares` | | The name of the adapter, and the middlewares of its calls, after those of the entrypoint |
+
+- The adapter connects and takes the name when the application starts. A bus that cannot be reached (for `'session'`,
+  also a `DBUS_SESSION_BUS_ADDRESS` not set), or a name owned by another connection, makes the start fail.
+- D-Bus allows `-` in the names of the services, but this adapter does not: the name of the service prefixes the names
+  of the errors, which may not hold it.
+- On the system bus, a policy file in `/etc/dbus-1/system.d/` must allow the process to own the name.
+- With `allowReplacement`, a service that takes the name with `replaceExisting` receives the calls from then on. The
+  replaced application keeps running without the name, and does not get it back when the other one stops.
+- When the application stops, the adapter releases the name (new calls fail with
+  `org.freedesktop.DBus.Error.ServiceUnknown`), lets the calls in progress end, then disconnects.
+
+## 3. Arguments and results
+
+**The input.** A method with a DTO takes one argument, a dictionary of variants (`a{sv}`) holding the properties of the
+DTO; a method without a DTO takes no argument. The input goes through the middlewares, the validation and the access
+control, as on the other transports. A variant accepts any type, so a dictionary of strings (`a{ss}`) is accepted too.
+
+| D-Bus type | JavaScript value |
+|---|---|
+| `s`, `o` | A string |
+| `y`, `n`, `i`, `u`, `d` | A number |
+| `x`, `t` (64 bits) | A number when it is a safe integer, else a bigint |
+| `b` | A boolean |
+| `as`, `ai`… | An array |
+| `a{…}` | An object |
+| `(…)` | An array |
+
+The 64-bit integers are decoded as numbers so that `DTO.Number()` accepts them; `decode: {int64: 'bigint'}` keeps them
+as bigints, for `DTO.BigInt()`.
+
+**The result** has the type of the `returns` option: a signature such as `'s'`, or a DTO, sent as `a{sv}`. Without
+`returns`, it has the type of the schema of `@Return`:
+
+| `@Return` schema | D-Bus type |
+|---|---|
+| An object, a DTO | `a{sv}` |
+| A string | `s` |
+| A boolean | `b` |
+| An integer (`.integer()`) | `x` |
+| Another number | `d` |
+| A bigint | `x` |
+| An array | `av` |
+| Anything else | `v` |
+
+- Without `returns` and `@Return`, the method has no result.
+- The dates are sent as ISO strings, and the `null` and `undefined` values are left out of the objects and arrays: a
+  variant has no null. A method that returns `a{sv}` and returns nothing sends `{}`.
+- A method whose result is a single type (`'s'`, `'i'`…) must return a value: `undefined` fails the call.
+- The `Map`s, the `Buffer`s and the typed values of `dbus-sdk` (`new DBusUInt32(7)`) are sent as they are.
+
+## 4. Objects, properties and signals
+
+The path of an interface is either a path (`/com/example/Manager`), whose object is exported when the adapter starts,
+or a template (`/com/example/Devices/{sn}`), whose objects the application adds and removes with `DBusObjectManager`.
+The variables of the path are merged into the input of the methods, over the values sent by the client.
+
+```typescript
+import {Component, DTO} from 'lakutata'
+import {Controller} from 'lakutata/com/entrypoint'
+import {Expect, Return} from 'lakutata/decorator/dto'
+import {Inject} from 'lakutata/decorator/di'
+import {
+    DBusInterface,
+    DBusMethod,
+    DBusObjectManager,
+    defineDBusProperty,
+    defineDBusSignal,
+    type DBusPropertyWrite
+} from '@lakutata/dbus'
+
+class DeviceSnDTO extends DTO {
+    @Expect(DTO.String().required())
+    public sn: string
+}
+
+class StatusDTO extends DTO {
+    @Expect(DTO.String().required())
+    public sn: string
+
+    @Expect(DTO.Boolean().required())
+    public online: boolean
+}
+
+export const DeviceChanged = defineDBusSignal<StatusDTO>('Changed', StatusDTO)
+export const DeviceState = defineDBusProperty<string>('State', 's', {initial: 'idle'})
+export const DeviceLevel = defineDBusProperty<number>('Level', 'i', {writable: true, initial: 1, schema: DTO.Number().integer().min(0).max(10)})
+
+@DBusInterface('com.example.Device', {path: '/com/example/Devices/{sn}', signals: [DeviceChanged], properties: [DeviceState, DeviceLevel]})
+export class DeviceController extends Controller {
+    //The sn of the input is the one of the object path
+    @DBusMethod('Status', DeviceSnDTO)
+    @Return(StatusDTO)
+    public async status(input: DeviceSnDTO): Promise<StatusDTO> {
+        return {sn: input.sn, online: true} as StatusDTO
+    }
+}
+
+//Declared in the components of the application
+export class Devices extends Component {
+    @Inject(DBusObjectManager)
+    protected readonly manager: DBusObjectManager
+
+    protected async init(): Promise<void> {
+        this.manager.on('propertyWritten', (write: DBusPropertyWrite): void => {
+            if (write.property === DeviceLevel) console.log(`${write.path}: level ${write.value}`)
+        })
+    }
+
+    public plug(sn: string): void {
+        const path: string = `/com/example/Devices/${sn}`
+        this.manager.addObject(path)
+        this.manager.setPropertyValue(path, DeviceState, 'running')
+        this.manager.emitSignal(path, DeviceChanged, {sn: sn, online: true} as StatusDTO)
+    }
+
+    public unplug(sn: string): void {
+        this.manager.removeObject(`/com/example/Devices/${sn}`)
+    }
+}
+```
+
+- `DBusObjectManager` is a component of every application: inject it (`@Inject(DBusObjectManager)`) without declaring
+  it. The objects added before the adapter starts are exported when it starts. The clients learn of the objects added
+  and removed through the signals `InterfacesAdded` and `InterfacesRemoved` of the root object.
+- A property keeps one value per object, its `initial` value until it is set. `setPropertyValue()` validates the value
+  with the `schema` of the property, and tells the clients of the change (`PropertiesChanged`).
+- A client may write a `writable` property: the value is validated (the error is given to the client), kept, and
+  `propertyWritten` is emitted. A write that must reach a device, or that may fail after its validation, is better a
+  method, whose errors reach the caller.
+- `emitSignal()` validates the data with the DTO of the signal, and returns whether an object at that path sends it.
+- The signatures of the properties and of the signals are checked when they are defined.
+
+## 5. Errors
+
+An error thrown by a method, its validation or its access control included, reaches the caller as a D-Bus error, with
+its message:
+
+| Error thrown | D-Bus error name |
+|---|---|
+| An exception with an `errno` (`E_OFFLINE`) | `com.example.DeviceService.E_OFFLINE` |
+| An `errno` that holds dots (`org.example.Device.Offline`) | `org.example.Device.Offline` |
+| An `errno` that does not start with a letter (`500`, `_HIDDEN`) | `com.example.DeviceService.E500`, `….E_HIDDEN` |
+| An error without `errno` (`Error`, `TypeError`) | `com.example.DeviceService.Error`, `….TypeError` |
+
+The other cases are answered before any action runs: `org.freedesktop.DBus.Error.UnknownObject` for an object that does
+not exist, `UnknownMethod` for a method that does not exist, `InvalidArgs` for arguments of the wrong type; the bus
+answers `ServiceUnknown` when no application owns the name.
+
+## 6. The context and the access control
+
+In a D-Bus method, `this.context` is a `DBusContext`: its `type` is `'DBUS'` (`DBUS_CONTEXT_TYPE`), `path` is the path
+of the object called, `interface` and `member` name the method, and `data` holds the dictionary received, before the
+validation.
+
+The access rules of the entrypoint apply to the methods declared with `acl: true` when their `supportContextTypes()`
+include `DBUS_CONTEXT_TYPE` (see [Middlewares](Middlewares.md)). The context does not tell who calls: a rule cannot
+check the caller, which is the job of the bus policy on the system bus.
+
+## 7. The client
+
+`DBusClientComponent` connects to a bus when it is created, to call the services, read their properties and listen to
+their signals:
+
+```typescript
+import {Application} from 'lakutata'
+import {DBusClientComponent, type DBusRemoteInterface} from '@lakutata/dbus'
+
+Application
+    .run(() => ({
+        id: 'client.app',
+        name: 'Client',
+        components: {
+            dbus: {class: DBusClientComponent, busAddress: process.env.DBUS_SESSION_BUS_ADDRESS!, callTimeout: 5000}
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const dbus: DBusClientComponent = await app.getObject('dbus')
+        //A call with its signature: the output arguments, as an array
+        const [status] = await dbus.invoke({
+            service: 'com.example.DeviceService',
+            objectPath: '/com/example/Devices/A1',
+            interface: 'com.example.Device',
+            method: 'Status',
+            signature: 'a{sv}',
+            args: [{sn: 'A1'}]
+        })
+        console.log(status)
+        //An interface built from the introspection of its object
+        const device: DBusRemoteInterface = await dbus.interface('com.example.DeviceService', '/com/example/Devices/A1', 'com.example.Device')
+        console.log(await device.property.State.get())
+        device.signal.on('Changed', (data: unknown): void => console.log(data))
+    })
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `busAddress` | required | The address of the bus (`'unix:path=/var/run/dbus/system_bus_socket'`), not `'session'` nor a path |
+| `timeout` | 20 seconds | How long the connection may take, in milliseconds |
+| `callTimeout` | none | How long a call may wait for its reply, in milliseconds; a call can give its own `timeout` |
+| `decode` | `{int64: 'number'}` | How the replies and the signals are decoded |
+
+- `invoke()` resolves with the array of the output arguments; the methods of an interface (`device.method.Status()`)
+  resolve with the value itself.
+- A call that fails rejects with an `Error` whose `name` is the D-Bus error name
+  (`com.example.DeviceService.E_OFFLINE`); it has no `errno`.
+- The component disconnects when the application stops.

package/doc/en/DTOValidation.md

@@ -1,10 +1,9 @@
 # Lakutata DTO and Validation
 
-A **DTO** (data transfer object) is a class whose properties are declared with validation schemas. The framework
-validates with them the options of the objects (`@Configurable`), the arguments and results of methods (`@Accept`,
-`@Return`) and the inputs of the controller actions. `DTO` is exported by `lakutata`, the decorators by
-`lakutata/decorator/dto`; the validation engine is the framework's own, with the API of joi (extended with bigints and
-the numeric types below).
+A **DTO** (data transfer object) is a class whose properties are declared with validation schemas. The framework uses
+DTOs to validate the options of objects (`@Configurable`), the arguments and results of methods (`@Accept`, `@Return`)
+and the input of controller actions. `DTO` is exported by `lakutata` and the decorators by `lakutata/decorator/dto`; the
+validation engine is the framework's own, with the API of joi (extended with bigints and the numeric types below).
 
 ## 1. Defining a DTO
 
@@ -45,16 +44,16 @@ class CustomerDTO extends DTO {
 The schemas are built by the static methods of `DTO`: `DTO.String()`, `DTO.Number()`, `DTO.BigInt()`, `DTO.Boolean()`,
 `DTO.Date()`, `DTO.Binary()`, `DTO.Symbol()`, `DTO.Object()`, `DTO.Array()`, `DTO.Alternatives()`, `DTO.Any()`,
 `DTO.Function()`, `DTO.AsyncFunction()`, `DTO.Class()`, `DTO.InstanceOf()`, `DTO.Cron()`, `DTO.Glob()`, `DTO.Ref()`,
-`DTO.Link()`… Their rules are the ones of joi (`.required()`, `.optional()`, `.default()`, `.valid()`, `.min()`,
+`DTO.Link()`… Their rules are those of joi (`.required()`, `.optional()`, `.default()`, `.valid()`, `.min()`,
 `.max()`, `.pattern()`, `.email()`, `.uri()`…).
 
 - **Strict by default**: a value of the wrong type is rejected, not converted (the string `'5'` is not the number 5).
-  Call `.strict(false)` to convert, as for the query strings and route parameters of HTTP, which are always strings.
+  Call `.strict(false)` to convert, for example for HTTP query strings and route parameters, which are always strings.
 - **Numeric types**: `DTO.Number()` provides the integer types `int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`,
   `int64` and `uint64` (the 64-bit types limited to the safe integers of JavaScript), and the floating point types
   `float` (32-bit range) and `double`.
-- **Validation options**: by default the validation stops at the first error (`abortEarly`), and the unknown keys are
-  removed (`stripUnknown`). `MyDTO.options({...})` gives other options for a DTO used as a schema.
+- **Validation options**: by default, validation stops at the first error (`abortEarly`) and unknown keys are removed
+  (`stripUnknown`). `MyDTO.options({...})` returns the schema of a DTO with other options.
 - **A DTO class as a schema**: `MyDTO.Schema()` is its object schema, `MyDTO.required()` and `MyDTO.optional()` the same
   schema marked required or optional. A DTO class is accepted wherever a schema is expected (`@Accept`, `@Return`, the
   action decorators).
@@ -62,18 +61,30 @@ The schemas are built by the static methods of `DTO`: `DTO.String()`, `DTO.Numbe
 ## 2. Validating
 
 ```typescript
-//Validated when constructed: the defaults applied, the unknown key "note" removed;
-//an InvalidValueException is thrown when the data is invalid
-const customer: CustomerDTO = new CustomerDTO({name: 'Ada', email: 'ada@example.com', address: {city: 'London'}, note: 'vip'})
+import {DTO} from 'lakutata'
+import {Expect} from 'lakutata/decorator/dto'
+
+class CustomerDTO extends DTO {
+    @Expect(DTO.String().min(2).required())
+    public name: string
+
+    @Expect(DTO.Number().integer().min(0).default(0))
+    public credit: number
+}
+
+//Validated when constructed: defaults are applied and the unknown key "note" is removed;
+//invalid data throws an InvalidValueException
+const customer: CustomerDTO = new CustomerDTO({name: 'Ada', note: 'vip'})
 
 //A DTO instance validates each change of its properties: an invalid change throws and is undone
 customer.credit = 10
 
-//Validated without an instance: the validated value, or an InvalidValueException
-const data: CustomerDTO = CustomerDTO.validate({name: 'Ada', email: 'ada@example.com', address: {city: 'London'}})
-const later: CustomerDTO = await CustomerDTO.validateAsync({name: 'Ada', email: 'ada@example.com', address: {city: 'London'}})
+//Validated without creating an instance: returns the validated data (a plain object) or throws an InvalidValueException
+const received: any = JSON.parse('{"name": "Ada"}')
+const data: CustomerDTO = CustomerDTO.validate(received)
+const later: CustomerDTO = await CustomerDTO.validateAsync(received)
 
-//Checked without exception
+//Checked without throwing
 const valid: boolean = CustomerDTO.isValid({name: ''})
 
 //Any value against any schema
@@ -88,13 +99,13 @@ own by default) and the validation options.
 | Decorator | Applies to | Effect |
 |---|---|---|
 | `@Expect(schema)` | A property of a DTO | Declares the schema of the property |
-| `@IndexSignature(schema)` | A DTO class | Keeps the keys without `@Expect` schema, validated against the schema, instead of removing them |
+| `@IndexSignature(schema)` | A DTO class | Keeps the keys that have no `@Expect` schema, validating them against this schema, instead of removing them |
 | `@Accept(...schemas)` | A method | Validates the arguments of each call, by position; throws `InvalidMethodAcceptException` |
 | `@Return(schema)` | A method | Validates the result of each call (awaited for an async method); throws `InvalidMethodReturnException` |
 
-`@Accept` and `@Return` give the method (or its caller) the validated values: defaults applied, unknown keys removed.
-A DTO class validates an argument or a result against its schema, and the value given is a plain object, not an
-instance of the class. A missing argument is accepted unless its schema is required (`MyDTO.required()`).
+`@Accept` and `@Return` pass the validated values on to the method (or to its caller), with defaults applied and unknown
+keys removed. When a DTO class validates an argument or a result, the value passed on is a plain object, not an instance
+of the class. A missing argument is accepted unless its schema is required (`MyDTO.required()`).
 
 ```typescript
 import {Component, DTO} from 'lakutata'
@@ -142,15 +153,15 @@ class Bank extends Component {
 
 ## 4. DTOs in the framework
 
-- **Object options**: `@Configurable(schema)` (from `lakutata/decorator/di`) validates an option of a component,
-  provider or module; see [Core](Core.md).
+- **Object options**: `@Configurable(schema)` (from `lakutata/decorator/di`) validates an option of a component or a
+  provider; see [Injection](Injection.md).
 - **Controller actions**: the DTO given to `@GET`, `@POST`, `@CLIAction`, `@ServiceAction`… validates the input of the
-  action; an invalid input is answered with the status 400. See [ActionPattern](ActionPattern.md).
-- **Pagination** (`lakutata/dtos`): `PaginationSearchDTO` and `PaginationResultDTO` are the input and the result of the
-  paginated actions, `paginator` computes the pages; `FlexibleDTO` is a DTO accepting any key.
-- **Validation messages**: the messages of the errors are translated; `registerValidationMessages`,
-  `runInValidationLanguage` and `currentValidationLanguage` (from `lakutata`) manage their languages, and the language
-  middleware of the I18n component sets the language of each request (see [I18n](I18n.md)).
+  action; invalid input gets a 400 response. See [Controllers](Controllers.md).
+- **Pagination** (`lakutata/dtos`): `PaginationSearchDTO` and `PaginationResultDTO` are the input and the result of
+  paginated actions, and `paginator` computes the pages; `FlexibleDTO` is a DTO that accepts any key.
+- **Validation messages**: error messages can be translated; `registerValidationMessages`, `runInValidationLanguage` and
+  `currentValidationLanguage` (from `lakutata`) manage their languages, and the language middleware of the I18n
+  component sets the language of each request (see [I18n](I18n.md)).
 
 ## 5. JSON Schema and OpenAPI
 
@@ -162,44 +173,62 @@ documents.
 
 ```typescript
 import {DTO} from 'lakutata'
+import {Expect} from 'lakutata/decorator/dto'
 import {toJsonSchema} from 'lakutata/dtos'
 
+class UserDTO extends DTO {
+    @Expect(DTO.Number().integer().required())
+    public id: number
+
+    @Expect(DTO.String().required())
+    public name: string
+}
+
 UserDTO.toJsonSchema()                  //JSON Schema 2020-12 (default)
 UserDTO.toJsonSchema('draft-07')        //'draft-2020-12' | 'draft-2019-09' | 'draft-07' | 'draft-04'
 UserDTO.toOpenAPIJsonSchema()           //OpenAPI 3.1 (default), or '3.0'
 toJsonSchema(DTO.String().email(), {target: 'openapi-3.0'})   //any schema, or a DTO class
 ```
 
-- The JSON Schema describes the values the schema accepts without conversion, so ajv (with ajv-formats) and other
-  validators accept exactly these values; what JSON Schema cannot express (custom rules, references to other values,
-  conversions) is dropped, so the JSON Schema may accept more values, never fewer.
-- The unknown keys follow the validation options: with the defaults of lakutata (`allowUnknown`, `stripUnknown`) the
-  objects accept them; pass `preferences` to convert for other options.
-- The numeric types convert to integer bounds (`int8` to `uint64`) and float ranges; OpenAPI also names the formats
+- The JSON Schema describes the values the schema accepts without conversion, and ajv (with ajv-formats) and other
+  validators accept those values. What JSON Schema cannot express (custom rules, references to other values,
+  conversions) is left out, so the JSON Schema may also accept values the schema rejects, never the reverse.
+- Unknown keys follow the validation options: with the defaults of lakutata (`allowUnknown`, `stripUnknown`), objects
+  accept them; pass `preferences` to convert a schema for other options.
+- The numeric types become integer bounds (`int8` to `uint64`) and float ranges; in OpenAPI they also get the formats
   `int32`, `int64`, `float` and `double`.
 
 ### 5.2 Import
 
 ```typescript
-import {DTO} from 'lakutata'
+import {readFileSync} from 'node:fs'
+import {DTO, type JSONSchema} from 'lakutata'
 import {fromJsonSchema} from 'lakutata/dtos'
 
-const schema = fromJsonSchema({type: 'object', properties: {id: {type: 'integer'}}, required: ['id']})
+const userJsonSchema: JSONSchema = {
+    type: 'object',
+    properties: {id: {type: 'integer'}, name: {type: 'string'}},
+    required: ['id']
+}
+
+//A schema
+const schema = fromJsonSchema(userJsonSchema)
 DTO.validate({id: 1}, schema)
 
-//A DTO class, a subclass of the class it is created from
+//A DTO class, a subclass of the class on which fromJsonSchema() is called
 const UserDTO = DTO.fromJsonSchema(userJsonSchema)
 const user = new UserDTO({id: 1, name: 'Alice'})
 
 //The DTO classes of the object schemas of an OpenAPI document (components.schemas), by name
+const openApiDocument: Record<string, unknown> = JSON.parse(readFileSync('openapi.json', 'utf8'))
 const {Pet, Person} = DTO.fromOpenAPI(openApiDocument)
 ```
 
-- The imported schemas validate like JSON Schema: the values are not converted (`convert: true` converts them), the
-  unknown keys follow `additionalProperties`, the formats validate like ajv-formats, and the defaults are applied.
-- The references resolve by JSON pointer, `$anchor` and `$id` (pass other documents with `schemas`, an OpenAPI document
-  with `document`); recursive references are supported.
+- Imported schemas validate as JSON Schema does: values are not converted (unless `convert: true` is given), unknown
+  keys follow `additionalProperties`, formats are checked as ajv-formats checks them, and defaults are applied.
+- References are resolved by JSON pointer, `$anchor` and `$id` (pass other documents in `schemas`, and an OpenAPI
+  document in `document`); recursive references are supported.
 - The version is read from `$schema`, or given with `dialect` (default: 2020-12).
-- JSON Schema is lossy for the schemas of lakutata (custom rules, conversions): to store a schema and restore it
-  exactly, keep its `describe()` output (a JSON value unless it holds functions) and rebuild it with
+- Converting a lakutata schema to JSON Schema loses information (custom rules, conversions): to store a schema and
+  restore it exactly, keep its `describe()` output (a JSON value unless it contains functions) and rebuild it with
   `DTO.Build(description)`.