Metadata & Data Objects

Metadata is the foundation of everything you do in ADL. It’s a structured description of your data solution — what tables exist, what columns they have, where they live, and how they relate to each other.

Think of metadata as a blueprint. Just as an architect draws plans before building a house, you describe your data solution in metadata before generating the code to build it.

Core metadata concepts

Data Connections

A Data Connection represents a place where data lives — a database, a schema, a warehouse. It captures:

• Name — A friendly label for this connection (e.g., “Staging Database”, “Production Warehouse”).
• Connection type — What kind of system this is (SQL Server, Snowflake, PostgreSQL, etc.).
• Location details — The schema, catalog, or other location info needed to qualify objects.

You’ll typically have a handful of connections in a project — one for your source system, one for your staging area, one for your warehouse, and so on.

Data Objects

A Data Object represents a structure in your data solution — usually a table, view, or query. It’s the central building block in ADL.

Each Data Object belongs to a Data Connection (telling ADL where it lives) and contains:

• Data Items — The columns or fields in this object. Each Data Item has a name, data type, nullability, and other properties you’d expect from a column definition.
• Business Key Definitions — Which columns make up the primary or business key for this object.
• Relationships — Links to other Data Objects, similar to foreign key relationships.
• Classifications — Tags like “PII” or “Sensitive” that help you track compliance requirements.
• Extensions — Custom key-value pairs for any additional metadata you need to track.

Data Object Mappings

A Data Object Mapping describes how data flows from one object to another. It connects a source Data Object to a target Data Object, and includes:

• Data Item Mappings — How individual columns map from source to target, including any transformation logic.
• Filter criteria — Conditions that determine which rows are included.
• Business keys — Key definitions used for matching and merging records.

Mappings are essential for generating ETL/ELT code — stored procedures, views, or scripts that move and transform data between layers of your solution.

How metadata is stored

All metadata is saved as JSON files in your project folder. The structure is straightforward:

• Each type of metadata (connections, data objects, mappings, etc.) lives in its own subfolder.
• Each entity is a separate JSON file.
• The JSON format follows the open-source Generation Metadata Schema.

This means your metadata is:

• Readable — Open any file in a text editor and see exactly what’s there.
• Versionable — Track changes in Git just like source code.
• Portable — Move it between projects, share it with colleagues, or process it with your own tools.

Building metadata in ADL

You can create and edit metadata directly in the ADL app:

• Data Objects — Create and manage your tables, views, and queries.
• Connections — Set up your database connections.
• Data Object Mappings — Define how data flows between objects.
• Classifications — Tag objects and items for compliance tracking.
• Conventions — Set up naming standards for consistency.

You can also import metadata from existing databases using the Metadata Importer.

What’s next?

• Templates & Code Generation — Learn how templates turn metadata into real output.
• How ADL Works — Review the big-picture workflow.
• Using the App — Data Objects — Start working with Data Objects in the ADL interface.