/**
 * This is a chatch-all exception for some invalid parameters
 */
Exception InvalidFormat(msg: string);

/**
 * This exception is thrown, when parsing model data. 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 ParsingError(msg: string);

/**
 * This methods subscribes to the 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 InvalidFormat
 * @throws ParsingError
 */
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, leav `values` out (hence the optional parameter).
 *
 * 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?: {
        [field: Field]: GenericRelationFieldDescriptor
            | RelationFieldDescriptor
            | StructuredFieldDescriptor
            | null;
    }
}


/**
 * This structure holds all data given by the called service structured by
 * fqids. Each fqid contains the (partial, restricted) data for the fqid.
 */
Interface ModelData {
    [collection: Collection]: {
        [id: Id]: {
            [field: Field]: Value;
        };
    };
}