event-schema-malformed

• Routes: register-event-schema, restore-backup, write-events, and import-events
• Description: event schema is malformed: <reason>, or, when writing events, /events/<index>: event schema is malformed: <reason>, with the place of the event in its list, counting from 0; when importing events, only the last of the reasons below; the reason is one such as these:
  • '<place>' does not conform to JSON Schema: <message>, for a keyword whose value JSON Schema does not take, with the place in the schema, such as '/properties/title/type' does not conform to JSON Schema: value must be one of "array", "boolean", "integer", "null", "number", "object", "string"; for a keyword that takes several forms, such as a single type or a list of them, the message says what is wrong with the form the value has, such as '/type' does not conform to JSON Schema: items at index 0 and 1 are equal for "type": ["string", "string"]; for a schema with several such keywords, one for each, separated by semicolons, in the order of their places, at most 10 of them, and ending with ; and more where there are more
  • schema refers to '<reference>', which it does not define, for a reference to a part that the schema lacks, such as schema refers to '#/$defs/title', which it does not define
  • schema refers to '<address>', which is not part of it: a schema may only refer to its own parts, such as '#/$defs/address', for a reference to another document
  • the number <number> is out of range: a number may have at most 1000 digits before or after its decimal point, for a number with more digits, as the schema writes it, such as the number 1e-999999 is out of range: a number may have at most 1000 digits before or after its decimal point
• Details: When registering a schema, none; details is an empty object. When writing events, event, the place of the event in its list, counting from 0. When restoring a backup, part, the part of the backup that holds the schema, counting from 0, with the full backup as part 0, and value, the event type of the schema. When importing events, eventId, the ID of the event whose type has the schema, and value, that event type.

Why It Happens#

EventSourcingDB compiles every schema before it registers it, and refuses one that is not a valid JSON Schema: one with a keyword whose value it does not take, such as "type": "text", one with a $ref to a part of the schema that does not exist, or one with a $ref to another document, such as a URL or a file. A schema may only refer to its own parts, such as #/$defs/address, since EventSourcingDB loads nothing from elsewhere.

Every number of a schema, wherever it stands, may have at most 1,000 digits before its decimal point and at most 1,000 after it, counted as its exponent moves the point, so 1e-999999 has 999,999 digits after it. This is the bound to which EventQL keeps integers exact, so a schema can still state every number that the data of an event can hold. It also keeps compiling the schema fast, which takes the longer, the farther the exponent of a number moves its decimal point. See Limits.

The schema is checked before the database is touched, so the error comes whether or not the event type has events or a schema already, and even in read-only mode. When restoring a backup, every schema of the backup is checked the same way, as it is read; the restore then fails, and the database removes what it has restored so far, see When a Restore Fails.

Writing events reports this error for an event whose type has a stored schema with such a number, which only a data directory that was changed by hand can hold, since earlier versions converted every number of a schema to a 64-bit floating-point number. Every write of that event type fails this way, and verifying the store reports the schema. Importing events reports it the same way for the first event of that type, and the import then fails, and the database removes what it has imported so far, and keeps its schemas.

How to Fix It#

Correct the schema at the place that the reason names, and copy what it refers to into the schema, under $defs, rather than referring to another document. Sending the same request again fails the same way, since the error depends on the schema alone. A stored schema can be neither replaced nor removed, so for one that holds a number with too many digits, use a new event type instead.

Example#

To register a schema for io.eventsourcingdb.library.book-acquired whose author refers to https://library.eventsourcingdb.io/schemas/author.json, EventSourcingDB answers with this error, as a line of the stream, and then ends the stream with its end item:

{
  "type": "error",
  "data": {
    "code": "https://docs.eventsourcingdb.io/errors/event-schema-malformed",
    "description": "event schema is malformed: schema refers to 'https://library.eventsourcingdb.io/schemas/author.json', which is not part of it: a schema may only refer to its own parts, such as '#/$defs/address'",
    "details": {}
  }
}