/**
 * SyntaxError is returned, when the syntax of the request body is wrong.
 * This error is returned on the beginning of a request with http-status-code
 * 400.
 */
Exception SyntaxError(msg: string);

/**
 * JsonError is returned, when the body does not contain valid json. This error
 * is returned on the beginning of a request with http-status-code 400.
 */
Exception JsonError(msg: string);

/**
 * ValueError is returned, when the value of a field does not have the expected
 * format. E.g. there is an indicated relation to a key, but the data are no
 * foreign ids/fqids. The exception may happen, if the stream is used at
 * runtime, because this cannot be detected when the caller makes the request.
 */
Exception ValueError(msg: string);

/**
 * InternalError is an unexpected error on the server side. When it happens at
 * the beginning of a request, an http-status-code 500 is used. But it can also
 * happen after the first data have been streamed to the client. The error does
 * not contain any useful information. More information can be found in the
 * server log. This is the only error that generates a server log message.
 */
 Expection InternalError(msg: string);

/**
 * This methods subscribes to a list of given request. The response is a stream
 * (language dependent) updating all models according to the ModelRequest if new
 * data is available. On subscription, initial data must be pushed to the caller
 * as soon as possible. The stream can be closed by closing the stream (e.g. the
 * underlying network connection).
 *
 * @throws SyntaxError
 * @throws JsonError
 * @throws ValueError
 * @throws InternalError
 */
subscribe(request: ModelRequest[]): stream<ModelData>;

/**
 * This is the main interface for requesting models in a structured, nested way.
 * The initial request targets some models as the root models of one collection
 * with all the same fields. This build a tree of dependencies, because the
 * value of some fields may be a GenericRelationFieldDescriptor again.
 *
 * For a description of `fields` and `collection`, see
* GenericRelationFieldDescriptor and RelationFieldDescriptor.
 *
 * `ids`: This is a list of ids for a collection, that should be provided. All
 * models, that the user can see, must be included in the response. The model
 * fields are handled according to `GenericRelationFieldDescriptor`.
 */
Interface ModelRequest extends Fields {
    ids: ID[];
    collection: Collection;
}

Interface Fields {
    fields: {
        [field: Field]: GenericRelationFieldDescriptor
            | RelationFieldDescriptor
            | StructuredFieldDescriptor
            | null;
    }
}

/**
 * For an overview, see `ModelRequest`.
 *
 * `fields` (inherited from `Fields`, see above):
 * Regardless of the value of a field, the restricted values are given in the
 * response (multiple for structured fields). If the restricted value is null,
 * the field must be included here.
 *
 * If the value is not null, it is indicated, that there is a reference to
 * follow. There are three types of values:
 * - GenericRelationFieldDescriptor: The reference is a generic one. This means,
 *   that the actual value from the model is a fqid or an array of fqids.
 * - RelationFieldDescriptor: A collection is given, so it can be expected, that
 *  the actual model value is an id or an array of ids.
 * - StructuredFieldDescriptor: The field is a template field and should be
 *   handled in this way.
 */
Interface GenericRelationFieldDecriptor extends Fields {
    type: 'generic-relation' | 'generic-relation-list';
}

/**
 * For an overview, see `ModelRequest`. For `fields`, see
 * GenericRelationFieldDescriptor.
 *
 * `collection`:
 * This is the collection, the ids are associated to. The ids are provided with
 * two different ways:
 * - In a ModelRequest, the ids are given.
 * - If this interface is used in a field indication a relation, the id(s) are
 *   given by the actual model data.
 */
Interface RelationFieldDescriptor extends Fields {
    type: 'relation' | 'relation-list';
    collection: Collection;
}

/**
 * Structured Fields: A field with `$` as a placeholder can be structured. The
 * `$` is a template placeholder. The `template field` holds a list of strings
 * with options to insert into `$`. All these fields are the `structured
 * fields`. Example:
 * B_$_ids is the template field. Its value may be `["1", "test"]`, so the
 * structured fields are B_1_ids and B_test_ids.
 *
 * This interface indicates, that there are structured fields related to the
 * given template field, that should be resolved. If one would give `B_$_ids:
 * null` without using this interface, the response would be just the template
 * field `B_$_ids` and no structured fields.
 *
 * For just resolving values, leave `values` out (hence the optional parameter).
 *
 * For retrieveing a single structured field, use `RelationFieldDescriptor`. E.g.
 * when trying to get the groups for a user from meeting 2, use `group_2_ids`
 * directly and do not bother with structured fields. The terminology is a
 * `specific structured field`.
 *
 * If the values of all structured fields are references, use the `values`
 * parameter analog to the `fields` paramter as documented in
 * `GenericRelationFieldDescriptor`.
 */
Interface StructuredFieldDecriptor {
    type: 'template',
    values?: GenericRelationFieldDescriptor | RelationFieldDescriptor;
}


/**
 * This structure holds all data given by the called service as a map of
 * fqfields to the fields values.
 */
Interface ModelData {
    [fqfield: Fqfield]: Value;
}