Overview

What is ADL?

The AOP Definition Language (ADL) is first of all the interface definition language of AOP. An ADL file declares the contract an AOP skill exposes - its data types, errors, functions, and notifications - in a compact, human-readable text syntax.

ADL does this in a similar way to how, for example, a .proto file declares a Protocol Buffers schema or a .fbs file declares a FlatBuffers schema.

In addition we use ADL also for other definitions. For example, the entire Ontology is defined using ADL. Further uses are planned, as described in the Outlook section.

For a comprehensive description of the ADL syntax see the Specification. In addition, the Example section provides an overview of a practical skill definition.

Along with ADL comes the ADL compiler (ADLC). It is to ADL what protoc is to Protocol uffers: it parses and validates ADL files and may generate different types of output from them:

• Client and provider code (C#, Go, TypeScript)
• Documentation (such as the API Reference)
• Basically, anything generated from a user-supplied template

ADL files are not read by AOP applications at run time; everything an application needs is generated from them at build time.

Definition structure

An ADL contract is organized around skills. A skill is the namespace and versioning unit of AOP (section 4), and every declaration belongs to exactly one skill. Within a skill, ADL declares:

• constrained scalar type aliases, enums, objects (with structural inheritance), and tagged unions (section 7);
• errors — structured failure responses (section 9);
• services grouping functions and notifications (section 10);
• concepts — ontological contracts describing what an entity is and can do, independent of how it is implemented (section 11);
• annotations carrying wire semantics such as read-only or sparse transmission (section 8), and since/until markers for evolving a skill across versions (section 12).

Skills reference each other’s types through versioned use imports (section 5), so a set of ADL files is the single source of truth for code generation (SDK models, serialization, tests), documentation, and protocol capability negotiation.

Design Principles

• Conciseness: Minimize syntactic noise. A property is name type — nothing more unless it carries information.
• Readability: A developer should be able to read an IDL file and understand the API surface without consulting external docs.
• Single source of truth: Types are defined once; skills bundle them at build time.
• Familiar syntax: Draws from protobuf (compact type definitions), HCL (block structure), and Go (declaration style).

Outlook

The following sections are planned but not yet specified:

• Forms — UI layout definitions for editing objects
• Lists — Tabular list/grid definitions for objects (unrelated to view projections, section 7.5)
• Settings — Application configuration parameters
• Storage — Persistence mapping definitions
• Object instances — Predefined object data