Asterix structure

Basic principles of asterix are described in the part 1 document. This project reuses the definitions and vocabulary to the maximum possible extent.

Example

asterix example

Definition of terms

Abstract structure

Asterix is a structure containing:

Item is a structure containing:

Item can also be empty (occupying defined number of spare bits).

Variation (or ItemType) could be:

Remark:

Item and Variation are defined in terms of mutual recursion.

Content could be:

Remark:

This structure makes distinction between Raw value and Unsigned Integer. A raw value is a content in which bits do not have any particular meaning, other than just representing some identifier (this is true in most cases, for example the SAC/SIC code).

Unsigned Integer is similar to Raw value, however semantically there is a small difference. In strongly typed environments, the compiler can prevent some irregular operations over Raw values. For example: it makes no sense to add/multiply two identifiers, whereas the same arithmetic operations over unsigned integers are well defined. One example on this is a content that represents seconds.

Validation rules

For each defined item or subitem, the following validation rules are enforced by the validator:

Asterix definition in haskell syntax

The essence of asterix definition is recursively encoded in Item and it’s Variation.

newtype CatNum = CatNum Int
newtype BitSize = BitSize Int
newtype ByteSize = ByteSize Int
newtype ItemName = ItemName Text
newtype Title = Title Text
newtype UapName = UapName Text
newtype Unit = Unit Text
newtype ItemPath = ItemPath [ItemName]

data Documentation = Documentation
    { docDefinition  :: Maybe Text
    , docDescription :: Maybe Text
    , docRemark      :: Maybe Text
    }

data Edition = Edition
    { editionMajor :: Int
    , editionMinor :: Int
    }

data Date = Date
    { dateYear  :: Integer
    , dateMonth :: Int
    , dateDay   :: Int
    }

data Number
    = NumInt Integer
    | NumDiv Number Number
    | NumPow Integer Integer

data Constrain
    = EqualTo Number
    | NotEqualTo Number
    | GreaterThan Number
    | GreaterThanOrEqualTo Number
    | LessThan Number
    | LessThanOrEqualTo Number

data Signedness
    = Signed
    | Unsigned

data StringType
    = StringAscii
    | StringICAO
    | StringOctal

newtype BdsAddr = BdsAddr Int

data BdsType
    = BdsWithAddress        -- 64 bit value (address is encoded with data)
    | BdsAt (Maybe BdsAddr) -- 56 bit value (address is maybe a priory known)

data Content
    = ContentRaw
    | ContentTable
        [(Int, Text)]
    | ContentString
        StringType
    | ContentInteger
        Signedness
        [Constrain]
    | ContentQuantity
        Signedness  -- unsigned/signed
        Number      -- lsb
        Unit        -- unit
        [Constrain]
    | ContentBds
        BdsType

data Rule a
    = ContextFree a
    | Dependent
        [ItemPath]   -- items that this rule depends on
        a            -- default value
        [([Int], a)] -- cases

data RepetitiveType
    -- N bytes reserved for REP lengt field
    = RepetitiveRegular ByteSize

    -- Number of repetitions are defined by FX bit value
    | RepetitiveFx

data ExplicitType
    = ReservedExpansion
    | SpecialPurpose

data Variation offset
    -- leaf of the structure
    = Element offset BitSize (Rule Content)

    -- concatinated subitems, example:
    -- item 010 is concatinated list of subitems SAC and SIC
    | Group offset [Item offset]

    -- extended item with FX extension mechanism
    | Extended [Maybe (Item offset)]

    -- repetitive item
    | Repetitive RepetitiveType (Variation offset)

    -- item with explicit size
    | Explicit (Maybe ExplicitType)

    -- list of subitems with FSPEC mechanism
    -- Some subitems may not be defined in which case the respective
    -- presence bit in the first part is always zero
    | Compound [Maybe (NonSpare offset)]

data NonSpare offset = NonSpare ItemName Title (Rule (Variation offset)) Documentation

data Item offset
    = Spare offset BitSize
    | Item (NonSpare offset)

data UapItem a
    = UapItem a
    | UapItemSpare
    | UapItemRFS

data UapSelector = UapSelector
    { selItem  :: ItemPath           -- UAP depends on this item
    , selTable :: [(Int, UapName)]  -- value lookup table
    }

-- User applicaton profile type
data Uap r
    -- single UAP
    = Uap r

    -- multiple UAPs
    | Uaps [(UapName, r)] (Maybe UapSelector)

-- Basic category definition
data Basic = Basic
    { basCategory  :: CatNum
    , basTitle     :: Title
    , basEdition   :: Edition
    , basDate      :: Date
    , basPreamble  :: Maybe Text
    , basCatalogue :: [NonSpare ()]
    , basUap       :: Uap [UapItem ItemName]
    }

-- Expansion category definition
data Expansion = Expansion
    { expCategory  :: CatNum
    , expTitle     :: Title
    , expEdition   :: Edition
    , expDate      :: Date
    , expFspecSize :: ByteSize
    , expItems     :: [Maybe (NonSpare ())]
    }

data Asterix
    = AsterixBasic Basic
    | AsterixExpansion Expansion

See source code for exact definition.

Non-backward compatible changes

2024-07-09 - cleanup

Parent git release: #d3cccd1

2024-02-26 - generalized ‘Rule’

Parent git release: #941f5ce

The Rule type is extended, to support I004/120/CC content cases.

.ast syntax is extended to include ‘default’ value, .json syntax requires minor update (change in field types and names). See changes in:

2023-12-18 - precise numeric expression

Parent git release: #a7c135f

The Number type is simplified and generalized, to allow precise numeric expression, without rounding error. Ast syntax becomes more readable, for example:

See FAQ for expression evaluation details.

2023-09-18 - extended item modification, fx bit is explicit

Parent git release: #53a30f4

Extended item structure is simplified to list of items with possible spare slots (‘fx’ bits).

2023-07-24 - explicit item modification, rfs item added

Parent git release: #5c263cb

Explicit item has optional (RE/SP) type added, such that RE items can be automatically processed.

Rfs item type is introduced.

2023-06-20 - extended/repetitve item modification

Parent git release: #3d75e32

Extended items with a single subitem are not allowed. In those cases, the items are more similar to ‘repetitive’, but with the ‘fx’ extension mechanism.

New ‘RepetitiveType’ data type is introduced to handle the case.