Abstract Wikipedia/Representation of errors/cs

Motivation and rationale

In Wikifunctions, errors can happen for many different reasons: When an input cannot be interpreted, when a value cannot be calculated, when we don't have sufficient resources to calculate a result, and many more. Added to this, errors can also happen in a controlled way, and can be created and thrown during user-defined functions.

For this reason, Wikifunctions provides a unified way to represent and report errors with the types Z5/Error and Z50/Error type. Similarly, there is a wide variety of built-in Error type instances in the Zid range from Z500-Z599 containing the errors that are generated and returned by internal system failures or problems.

Instances of Z50/Error type can (and probably should) be persisted, so that their labels containing the description of the error can be translated. On the other hand, instances of Z5/Error are generated on runtime (ZObjects of type Z5 are never persisted) whenever a problem occurs. The Z5/Error instance that is returned to the user contains: 1) a reference to the error type that more accurately describes the issue, and 2) the specific data that has generated this error.

Z5/Errors

Every error is a ZObject. Errors will all have the type Z5/Error, that has two keys:

• Z5K1/error type (Z50/Error Type): Takes an object of type Z50, which describes the Error type that is reported by this Z5. It will normally be a reference to one of the pre-defined Error types described below.
• Z5K2/error value (Z1/Any): An instance of the Error type described in the key Z5K1. It will contain the additional information to identify the wrong values.

Here is a simple example.

Assume we ask our validation engines to check the wellformedness of the following ZObject:

{ "value": "test" }

{ "Z6K1": "test" }

We should receive an error back, as the Z1K1/type is missing on the given ZObject. The exact error might depend on the evaluation engine, but some form of non-well-formedness error should be returned. Here is one possible answer.

{ "type": "Error", "error type": "not well-formed error", "error value": { "type": { "type": "Function call", "function": "Errortype to type", "errortype": "not well-formed error" }, "error type": "missing Z1K1", "error value": { "type": { "type": "Function call", "function": "Errortype to type", "errortype": "missing Z1K1" }, "object": { "type": "Quote", "quotation": { "value": "test" } } } } }

{ "Z1K1": "Z5", "Z5K1": "Z502", "Z5K2": { "Z1K1": { "Z1K1": "Z7", "Z7K1": "Z885", "Z885K1": "Z502" }, "Z502K1": "Z523", "Z502K2": { "Z1K1": { "Z1K1": "Z7", "Z7K1": "Z885", "Z885K1": "Z523" }, "Z523K1": { "Z1K1": "Z99", "Z99K1": { "Z6K1": "test" } } } } }

This shows a pretty complicated pattern, where a hierarchy of errors allows the system to filter for specific types of errors. In this instance, the hierarchy includes both Z502/Not wellformed and Z523/Missing Z1K1. We can easily recognize that this is an error because, like every error, it starts with Z5/Error as the top-level type. We'll take a closer look at Z523 in the next section.

Z50/Error types

Error types are represented by Z50, and have a very similar shape to Z4/Type objects. They have one key, Z50K1, that contains a list of the Z3/Keys necessary to describe the error.

For example, following the previous example: Z523 is a ZObject of type Z50/Error type, and its definition is:

{ "type": "Error type", "keys": [ { "type": "Key", "value type": "Quote", "key id": "Z523K1", "label": { "type": "Multilingual text", "texts": [ { "type": "Monolingual text", "language": "English", "text": "object" } ] } } ] }

{ "Z1K1": "Z50", "Z50K1": [ { "Z1K1": "Z3", "Z3K1": "Z99", "Z3K2": "Z523K1", "Z3K3": { "Z1K1": "Z12", "Z12K1": [ { "Z1K1": "Z11", "Z11K1": "Z1002", "Z11K2": "object" } ] } } ] }

We see here that Z523 has a single key, with id Z523K1 and English label "object", of type Z99/Quote. The value of this key will be the (quoted) object that was found to be missing a Z1K1. (Z99/Quote is used here as a wrapper around the malformed object, to indicate that it should not be evaluated during the processing of the Z523.) This error type definition is persisted as Z523, and the key Z2K1 (Persistent object label), not shown here, contains the multilingual name of the error type: "Missing Z1K1". See the full data JSON definition.

When detecting an error of the type Z523/"Missing Z1K1", we build a Z5/Error object by:

1. Adding a reference to the error type Z523 as the value of Z5K1, and
2. Creating an instance of the error type Z523.

Instances of Error Types

To create an instance of an Error Type, we first need to transform that Error Type into a formal Type. We do this by calling to the function Z885/"Error Type to type".

This function uses the keys listed in Z50K1 to create and return a Z4/Type with those keys as its Z4K2. See the function composition Z995, which implements Z885.

An instance of an Error Type will then have, as its type, the result of the Function call to Z885, in this case passing the Error Type id Z523 as its argument Z885K1.

{ "type": { "type": "Function call", "function": "Errortype to type", "errortype": "Missing Z1K1" } }

{ "Z1K1": { "Z1K1": "Z7", "Z7K1": "Z885", "Z885K1": "Z523" } }

If you want to see the Z4/Type resulting from this call, try running the wikilambda_function_call API with the following input:

{
  "Z1K1": "Z7",
  "Z7K1": "Z885",
  "Z885K1": "Z523"
}

Try it in notwikilambda

The response will be the following Z4/Type:

{ "type": "Type", "identity": { "Z1K1": "Z7", "Z7K1": "Z885", "Z885K1": "Z523" }, "keys": [ { "type": "Key", "value type": "Quote", "key id": "Z523K1", "label": { "type": "Multilingual text", "texts": [ { "type": "Monolingual text", "language": "English", "text": "object" } ] } } ], "validator": "Z101" }

{ "Z1K1": "Z4", "Z4K1": { "Z1K1": "Z7", "Z7K1": "Z885", "Z885K1": "Z523" }, "Z4K2": [ { "Z1K1": "Z3", "Z3K1": "Z99", "Z3K2": "Z523K1", "Z3K3": { "Z1K1": "Z12", "Z12K1": [ { "Z1K1": "Z11", "Z11K1": "Z1002", "Z11K2": "object" } ] } } ], "Z4K3": "Z101" }

Nesting of Errors

Before persistence or execution, ZObjects go through a synchronous process of static validation or wellformedness. This validation is done by checking the given ZObject against the JSON Schema definitions found in function-schemata, either in the WikiLambda extension (using opis JSON Schema) or in the NodeJS back-end services (using Ajv JSON schema validator).

Because a ZObject is a nested ZObject, a parent key-value can be not valid due to an error in a child key-value. For example, in the following ZObject:

{
 "Z1K1": "Z12",
 "Z12K1": [
  {
   "Z1K1": "Z11",
   "Z11K1": "Z1002",
   "Z11K2": "true"
  },
  {
   "Z1K1": "Z11",
   "Z11K1": "Z1002",
   "Z11K2": false
  }
 ]
}

The value for the first Z11K2 (line 7) is correct, while the value for the second Z11K2 (line 12) is not. This means that the first ZObject of type Z11/monolingual string from the list is correct, while the second one is incorrect. The validation error from the second element of this list would then propagate up to its parent objects, and would also raise static validation errors in:

1. the whole list (lines 3-14),
2. the value of Z12K1, and finally,
3. the whole Z12/multilingual string ZObject.

The static validation for the object above will produce a Z5/error object that represents this exact tree of validation errors and follows the branch down, key by key, until reaching to the exact value problem. A simplified representation of the above error is:

{
 "Z1K1": "Z5",
 "Z5K1": "Z502",       // Root error. Z502: "Not wellformed" error
 "Z5K2": {
  "Z1K1": "Z502",
  "Z502K1": "Z526",    // What's the internal error? Z526 
  "Z502K2": {          // Okay, let's see it.
   "Z1K1": "Z5",
   "Z5K1": "Z526",      // Z526: "Key value not wellformed" error
   "Z5K2": {
    "Z1K1": "Z526",
    "Z526K1": "Z12K1",  // Which is the non-valid key? "Z12K1"
    "Z526K2": {         // Sure, but why?
     "Z1K1": "Z5",
     "Z5K1": "Z522",   // Z522: "Array element not wellformed" error
     "Z5K2": {
      "Z1K1": "Z522",
      "Z522K1": "1",   // Which element is not valid? The one with index "1"
      "Z522K2": {      // Okay. But, why?!
       "Z1K1": "Z5",
       "Z5K1": "Z526",      // Z526: "Key value not wellformed" error
       "Z5K2": {
        "Z1K1": "Z526",
        "Z526K1": "Z11K2",  // Which is the non valid key this time? "Z11K2"
        "Z526K2": {         // Can I know why?
         "Z1K1": "Z5",
         "Z5K1": "Z521",   // Z521: "ZObjects must not be a number or Boolean or null" error
         "Z5K2": {
          "Z1K1": "Z521",
          "Z521K1": {      // What's the offending value?
           "Z1K1": "Z99",
           "Z99K1": false  // Here, this one.
          }
         }
        }
       }
      }
     }
    }
   }
  }
 }
}

Please note that the ZObject above has been simplified for readability, but a type such as "Z1K1": "Z526" is not valid, and should instead be typed with the result of the function call Z885 (error type to type) instead, as explained above.

The following error types are available to describe root or/and branch errors:

• Z502: "Not wellformed" error: This is the root error type for any error tree returned on static validation. It's second key contains the error or errors found during the parsing process.
• Z526: "Key value not wellformed" error: This is a branch error type. It's first parameter gives information of which key contains a non-valid ZObject, and it's second parameter is error propagated from the bottom.
• Z522: "Array element not wellformed" error: This is also a branch error type. It can only be returned during validation of a canonical object, as is the only form that admits JSON arrays. Its first parameter provides index of the error that caused the validation error (starting from 0), while its second parameter contains the propagated error.

Working with Z509/List of Errors

When multiple errors must be returned, these are wrapped in a parent error of type Z509/list of errors. A error of type Z509 contains a list of Z5/error ZObjects, and it can contain branch error types as well as leaf error types. For example, an ZObject of type Z3/key like the following one would raise a validation error for two reasons:

1. The key Z3K2 contains a number, which is a disallowed value type.
2. The mandatory key Z3K3 is missing.

{
	"Z1K1": "Z3",
    "Z3K1": "Z6",
	"Z3K2": 34
}

The static validation of this ZObject then would cause a validation error that contains two separate error branches:

{
 "Z1K1": "Z5",
 "Z5K1": "Z502",      // Root error of type Z502: "Not wellformed"
 "Z5K2": {
  "Z1K1": "Z502",
  "Z502K1": "Z509",   // What's the internal error? "Z509"
  "Z502K2": {         // Okay, let's see it.
   "Z1K1": "Z5",
   "Z5K1": "Z509",    // Z509: "List of errors" error
   "Z5K2": {
    "Z1K1": "Z509",
    "Z509K1": [       // What errors were found?
     {
      "Z1K1": "Z5",       // First error from the list:
      "Z5K1": "Z526",     // Non terminal error of type Z526: "Key value not wellformed"
      "Z5K2": {
       "Z1K1": "Z526",
       "Z526K1": "Z3K2",  // Which is the non valid key? "Z3K2"
       "Z526K2": {        // Why?
        "Z1K1": "Z5",
        "Z5K1": "Z521",   // Z521: "ZObjects must not be a number or Boolean or null" error
        "Z5K2": {
         "Z1K1": "Z521",
         "Z521K1": {      // What's the offending value?
          "Z1K1": "Z99",
          "Z99K1": 34     // Here, this value is wrong.
         }
        }
       }
      }
     },
     {
      "Z1K1": "Z5",       // Second error from the list:
      "Z5K1": "Z511",     // Terminal error of type Z511: "Key not found"
      "Z5K2": {
       "Z1K1": "Z511",
       "Z511K1": "Z3K3",  // Which is the missing key? "Z3K3"
       "Z511K2": {        // Where is it missing from?
        "Z1K1": "Z99",
        "Z99K1": {        // From here.
         "Z1K1": "Z3",
         "Z3K1": "Z6",
         "Z3K2": 34
        }
       }
      }
     }
    ]
   }
  }
 }
}

As demonstrated, the list of errors that forms the value of the error Z509/list of errors can contain branch-level errors (such as the first one of type Z526/key value not wellformed) as well as leaf errors (like the second one in the list, of type Z511/key not found. Similarly, an error of type Z509/list of errors can be found many times and at any level of the error tree.

For example, for a non-valid ZObject such as this one, where the only element in the list of Z11/monolingual strings is missing two mandatory keys: Z11K1 and Z11K2:

{
 "Z1K1": "Z3",
 "Z3K1": "Z6",
 "Z3K2": "Z1000K1",
 "Z3K3": {
  "Z1K1": "Z12",
  "Z12K1": [
   {
    "Z1K1": "Z11"
   }
  ]
 }
}

The error of type Z509/list of errors will not occur until the direct parent of both errors, and both errors in the list will be leaf errors of the type Z511/key not found:

{
 "Z1K1": "Z5",
 "Z5K1": "Z502",     // Root error of type Z502: "Not wellformed"
 "Z5K2": {
  "Z1K1": "Z502",
  "Z502K1": "Z526",  // What's the internal error? Z526 
  "Z502K2": {        // Okay, let's see it.
   "Z1K1": "Z5",
   "Z5K1": "Z526",         // Non terminal error of type Z526: "Key value not wellformed"
   "Z5K2": {
    "Z1K1": "Z526",
    "Z526K1": "Z3K3",      // Which is the non-valid key? "Z3K3"
    "Z526K2": {            // Okay, why?
     "Z1K1": "Z5",
     "Z5K1": "Z526",       // Non terminal error of type Z526: "Key value not wellformed"
     "Z5K2": {
      "Z1K1": "Z526",
      "Z526K1": "Z12K1",   // Which is the non-valid key? "Z12K1"
      "Z526K2": {          // Again, why?
       "Z1K1": "Z5",
       "Z5K1": "Z522",     // Non terminal error of type Z522: "Array element not wellformed"
       "Z5K2": {
        "Z1K1": "Z522",
        "Z522K1": "0",     // Which element is not valid? The one with index "0"
        "Z522K2": {        // What's wrong with it?
         "Z1K1": "Z5",
         "Z5K1": "Z509",   // Z509: "List of errors" error
         "Z5K2": {
          "Z1K1": "Z509",
          "Z509K1": [
           {
            "Z1K1": "Z5",        // First error from the list, a terminal one:
            "Z5K1": "Z511",      // Z511: "Key not found" error
            "Z5K2": {
             "Z1K1": "Z511",
             "Z511K1": "Z11K1",  // Which is the missing key? "Z11K1"
             "Z511K2": {         // Where is it missing from?
              "Z1K1": "Z99",
              "Z99K1": {         // From here.
               "Z1K1": "Z11"
              }
             }
            }
           },
           {
            "Z1K1": "Z5",        // Second error from the list, also a terminal one:
            "Z5K1": "Z511",      // Z511: "Key not found" error
            "Z5K2": {
             "Z1K1": "Z511",
             "Z511K1": "Z11K2",  // Which is the missing key? "Z11K2"
             "Z511K2": {         // Where is it missing from?
              "Z1K1": "Z99",
              "Z99K1": {         // From here.
               "Z1K1": "Z11"
              }
             }
            }
           }
          ]
         }
        }
       }
      }
     }
    }
   }
  }
 }
}

Pre-defined Error Types

Pre-defined Error Types have reserved the ZID range from Z500-Z599. Here's a list of all the pre-defined Error Types that are currently being used by the different parts of the Wikifunctions stack. The table also gives details of their arguments, their names and their relevant scope. After each argument, in parentheses, we indicate the type of values taken by the argument.

ZID	Scope	Arguments	Name
Z500	global	error information (Z1)	Generic error
Z501	global	error message (Z6), input (Z6)	JSON syntax error
Z502	global	subtype (Z50), value (Z5)	Not wellformed
Z503	executor	feature name (Z6)	Not implemented yet
Z504	global	ZID (Z6)	ZID not found
Z505	executor	expected (Z6), actual (Z6), args (Z10)	Number of arguments mismatch
Z506	executor	expected (Z4), actual (Z4), arg (Z1), propagated error (Z5)	Argument type mismatch
Z507	executor	function call (Z7), propagated error (Z5)	Error in evaluation
Z508	executor	key (Z39), object (Z99)	Competing keys
Z509	global	errors (Z10)	List of errors
Z510	-	-	NIL
Z511	global	key (Z39), object (Z99)	Key not found
Z512	global	expected result (Z99), actual result (Z99)	Test failed
Z513	executor	object (Z99)	Resolved persistent object without value
Z514	executor	implementation (Z14)	Built-in does not exist
Z515	executor	implementation (Z14)	Built-in ID is erroneous
Z516	executor	argument (Z18), bad value (Z99)	Argument value error
Z517	executor	expected type (Z4), actual type (Z4), returned value (Z1), propagated error (Z5)	Return type mismatch
Z518	executor	expected type (Z4), object (Z1), propagated error (Z5)	Object type mismatch
Z519	global	object (Z1)	Undefined list type
Z520	global	object (Z1)	Wrong list type
Z521	global	offending value (Z99)	ZObjects must not be a number or Boolean or null
Z522	global	index of offending element (Z6), propagated error (Z5)	Array element not wellformed
Z523	global	object (Z99)	Missing Z1K1
Z524	global	value (Z99)	Z1K1 must not be a string or array
Z525	global	key (Z6)	Invalid key
Z526	global	key (Z39), propagated error (Z5)	Key value not wellformed
Z527			🆓
Z528			🆓
Z529			🆓
Z530			🆓
Z531	global	object (Z99)	Z6 must have 2 keys
Z532	global	object (Z99)	Z6 without a Z6K1
Z533	global	value of Z6K1 (Z99)	Z6K1 must be a string
Z534	global	object (Z99)	Z9 must have 2 keys
Z535	global	object (Z99)	Z9 without a Z9K1
Z536	global	value of Z9K1 (Z99)	Z9K1 must be a string
Z537	global	value of Z9K1 (Z99)	Z9K1 must look like a reference
Z538	extension	page title (Z6)	Wrong namespace
Z539	extension	page title (Z6)	Wrong content type
Z540	extension	language code (Z6)	Invalid language code
Z541	extension	language code (Z6)	Language code not found
Z542	extension	expected type (Z4), actual type (Z4)	Unexpected ZObject type
Z543	extension	type name (Z6)	Type not found
Z544	extension	type ZID (Z6), type name (Z6), existing type name (Z6)	Conflicting type names
Z545	extension	type ZID (Z6), type name (Z6), existing type ZID (Z6)	Conflicting type ZIDs
Z546	extension	type ZID (Z6), type name (Z6)	Built-in type not found
Z547	global	input (Z99)	Invalid format
Z548	global	error message (Z6), input (Z99)	Invalid JSON
Z549	global	reference value (Z6)	Invalid reference
Z550	global	reference value (Z6)	Unknown reference
Z551	global	key (Z39), expected type (Z6), actual type (Z6)	Schema type mismatch
Z552	global	index of offending element (Z6), expected type (Z4), actual content (Z99)	Array element type mismatch
Z553	global	root zobject (Z99)	Disallowed root type
Z554	extension	clashing ZID (Z6), language (Z6)	Label for a given language clashes with another ZObject's label
Z555	extension	ZID (Z6), page title (Z6)	Unmatching ZID and page title
Z556	extension	title (Z6)	Invalid page title
Z557	extension	message (Z6)	User does not have permission to edit
Z558	global	programming language (Z6)	Invalid programming language
Z559	extension	-	User not permitted to evaluate function
Z560	orchestrator	evaluation result (Z99)	Invalid evaluation result
Z561	evaluator	propagated error (Z5)	Invalid evaluation request
Z562	evaluator	missing property (Z6)	Incomplete evaluation request
Z563	evaluator	call (Z6)	Call by non-reentrant executor
Z564	executor	contents (Z6)	Invalid executor response
Z565	executor	missing property (Z6)	Incomplete executor request
Z566			🆓
Z567			🆓
Z568			🆓
Z569			🆓
Z570	orchestrator	orchestrator rate limit (Z6)	Reached rate limit in orchestrator
Z571	evaluator	evaluator rate limit (Z6)	Reached rate limit in evaluator
Z572	orchestrator	recursion limit (Z6), function name (Z6)	Reached recursion limit in orchestrator
Z573	evaluator	recursion limit (Z6), function name (Z6)	Reached recursion limit in evaluator
Z574	orchestrator	time limit (Z6)	Reached time limit in orchestrator
Z575	evaluator	time limit (Z6)	Reached time limit in evaluator

Making your own Error Type

Users can also define custom error types, by creating a ZObject of type Z50/Error type on the Wikifunctions UI or via the Wikifunctions API.

A Z50/Error type object has a similar shape to a Z4/Type, and defines as its only value (Z50K1) an array of keys that an instance of this error type created on runtime will need to have. Each key is a relevant piece of information with a label that describes it.

Say, for example, that we wish to create the function that formats a date passed as an input. If the date is incorrect (e.g. "32/05/1985"), we want to return a "Incorrect date" error, for which we shall create that particular error type. The type will contain one only key, with the string representation of the erroneous date passed as an input.

Using the API wikilambda_edit and passing the following object as the data to be saved:

{
  "Z1K1": "Z2",            // We create a persisted object
  "Z2K1": {                // With Zid Z0, as it will be automatically assigned
    "Z1K1": "Z6",
    "Z6K1": "Z0"
  },
  "Z2K2": {
    "Z1K1": "Z50",
    "Z50K1": [             // One key in the array under Z50K1
      {
        "Z1K1": "Z3",
        "Z3K1": "Z50",
        "Z3K2": "Z0K1",    // The Zid part of the key also is Z0
        "Z3K3": {          // With the label describing the key
          "Z1K1": "Z12",
          "Z12K1": [
            {
              "Z1K1": "Z11",
              "Z11K1": "Z1002",
              "Z11K2": "erroneous date"
            }
          ]
        }
      }
    ]
  },
  "Z2K3": {
    "Z1K1": "Z12",
    "Z12K1": [
      {
        "Z1K1": "Z11",
        "Z11K1": "Z1002",
        "Z11K2": "Incorrect date"    // And a label describing the error
      }
    ]
  }
}

If the call is successful (the format of the error is correct, the label is unique, etc.), the API will return the Zid assigned to this error type.

{
    "wikilambda_edit": {
        "success": "",
        "articleId": 1095,
        "title": "Z10000",
        "page": "Z10000"
    }
}

How to raise an Error in your Implementation

There are two types of function implementations in WikiFunctions available to users: those specified as programming language code in a supported language, and those specified as a composition of other WikiFunctions functions. Here we show how to raise an error in each of these types of implementations.

Code

In a programming language code implementation, an error can be raised in the normal way provided by that programming language. (For example, in Python your implementation would use the keyword raise followed by the specification of an exception. In JavaScript you would use the keyword throw followed by the specification of an exception.) The WikiFunctions system code, which is responsible for executing your implementation, will catch the exception and package it into an appropriate Z5 / Error object to be returned from the execution. (More particularly, in Python the resulting Z5 / Error object will contain the value of e.args[0] extracted from the caught exception e. In JavaScript, it will contain the value of e.message extracted from e.) Every WikiFunctions function call returns a Z22 / Evaluation result object, and the resulting Z5 / Error object will be returned as the value of the Z22K2 / metadata key.

Composition

In a composition implementation, an error can be raised by specifying a Z7 / Function call to the function Z820 / Trigger metadata, and passing a Z5 / Error object as the value of that function's Z820K1 / error argument. Here is what such a call looks like, assuming an error of type Z502 / not well-formed error:

{ "type": "Function call", "function": "Trigger metadata", "error": { "type": "Error", "error type": "not well-formed error", "error value": { ... } } }

{ "Z1K1": "Z7", "Z7K1": "Z820", "Z820K1": { "Z1K1": "Z5", "Z5K1": "Z502", "Z5K2": { ... } } }

Vaše volání Z820 / metadata spouštěče způsobí, že daný Z5 / Error objekt bude vrácen z provádění kompozice (jako hodnota Z22K2 / metadata klíč objektu Z22 / Výsledek hodnocení).