Behaviors

Some APIs needs to be handled differently based on the output language, while others share many common parameters. This document contains the list of this special interfaces and where those should be used. Behaviors should be used via implements in the specification.

You can find all the special classes and aliases in in the modeling guide.

AdditionalProperties & AdditionalProperty

In some places in the specification an object consists of the union of a set of known properties and a set of runtime injected properties. Meaning that object should theoretically extend Dictionary but expose a set of known keys. The object might also be part of an object graph and have a parent class. This puts it into a bin that needs a client specific solution. We therefore document the requirement to behave like a dictionary for unknown properties with this interface.

/**
 * @behavior_meta AdditionalProperties fieldname=sub_aggregations
 */
class IpRangeBucket implements AdditionalProperties<AggregateName, Aggregate> {}

There are also many places where we expect only one runtime-defined property, such as in field-related queries. To capture that uniqueness constraint, we can use the AdditionalProperty (singular) behavior.

/**
 * @behavior_meta AdditionalProperty key=field value=bounding_box
 */
class GeoBoundingBoxQuery extends QueryBase
  implements AdditionalProperty<Field, BoundingBox>

CommonQueryParameters

Implements a set of common query parameters all API's support. Since these can break the request structure these are listed explicitly as a behavior. Its up to individual clients to define support although error_trace and pretty are recommended as a minimum.

class RequestBase implements CommonQueryParameters {}

CommonCatQueryParameters

Implements a set of common query parameters all Cat API's support. Since these can break the request structure these are listed explicitly as a behavior.

class CatRequestBase extends RequestBase implements CommonCatQueryParameters {}

OverloadOf

Defines a class that is the "overload" version of a definition used when writing a property. A class that implements OverloadOf only needs to declare properties that differ from the overloaded type. Properties not explicitly listed are inherited as-is from the parent. For declared properties, you can change whether a property is required or not as well as its type. Same for the descriptions and js doc tags, if not specified, the parent ones will be used.

// only the changed property needs to be declared,
// unchanged properties are inherited from the parent
export class Foo {
  bar?: string
  baz?: integer
}

export class FooRead implements OverloadOf<Foo> {
  bar: string
}

// the type of a property can be changed freely
export class Config {
  foo: Foo
}

export class ConfigRead implements OverloadOf<Config> {
  foo: FooRead
}