What does Include mean in API Blueprint files?

Question

I can't see any mention of it in the API Blueprint spec, although there was a feature request to add an include directive for including other files.

Answer 1

Include is not to be confused with the non-standard directive of the same name for including other files (although the aglio tool for API Blueprint does support the latter).

Include is defined in the MSON specification, which is referred to by the API Blueprint spec. For example, in the Data Structures section of an API Blueprint file, the named types defined therein are defined using MSON.

Include is like extends in Java - it makes the type that is currently being defined inherit all the fields of the specified "supertype". The keyword Include may be followed by the name of a named type (its usual usage) or, somewhat strangely, by an inline type definition:

MSON defines a Mixin Type that supports multiple inheritance from another Named Type. The Named Type being inherited MUST be a Structure Type or its sub-type.

Nested Member Types defined in and inherited from the mixed-in Named Type are added at the same indentation level of the Mixin Type.

Mixin Type → - Include Type Name | - Include Type Definition