Shiller & Company

Principles of Metadata-First Design

A 3-day, customized, on-site workshop for software developers, engineers, and technical leaders.

This immersive workshop helps your teams integrate metadata-first thinking and systems design into everyday architecture and code decisions. It focuses on making metadata explicit in your models, APIs, and services so it becomes a first-class part of your architecture rather than an afterthought.

Each engagement is tailored to your organization’s systems, constraints, and pain points, so the content feels immediately relevant. Across three days, participants work through focused exercises, quizzes, and hands-on labs that reinforce each concept and ensure they can apply the practices directly to your production environment.

Course Outline

Across three intensive days, your team moves from core concepts to practical application and an actionable roadmap tailored to your environment.

Day 1 — Foundations of Metadata-First Design

  • Clarify the problem: brittle systems, hidden data assumptions, and ad hoc metadata scattered across services.
  • Core concepts: metadata vs data, schemas, contracts, catalogs, and governance.
  • Modeling metadata for key domains (products, customers, events, configurations) and mapping it to your business language.
  • Architectural patterns that support metadata-first design across monoliths, microservices, and event-driven systems.
  • Case studies of systems that succeed or fail based on metadata decisions.
  • Exercise: mapping metadata for one of your current systems and identifying high-risk gaps.

Day 2 — Applying Metadata-First Thinking to Architecture and Code

  • Turning business rules into explicit metadata and configuration that can be safely changed without redeploying code.
  • Designing APIs, services, and data contracts around metadata, including request/response shapes and error handling.
  • Working with schemas: validation, documentation, and negotiation between services and clients.
  • Versioning, evolution, and backward compatibility strategies for metadata and schema changes.
  • Hands-on labs: refactoring an existing feature to be metadata-driven.
  • Quiz: identifying missed metadata opportunities in real-world scenarios.

Day 3 — Operationalizing, Tooling, and Team Practices

  • Observability, monitoring, and debugging in metadata-driven systems, including surfacing metadata in logs and traces.
  • Tooling for defining, validating, and deploying metadata (schemas, registries, linters, and CI gates).
  • Testing strategies for metadata: contract tests, validation rules, and safety checks in pipelines.
  • Collaboration patterns between product, engineering, and data teams when metadata is a shared asset.
  • Building a roadmap to adopt metadata-first design in your organization, including quick wins and longer-term refactors.
  • Capstone exercise: design a metadata-first architecture for a real use case from your organization.

Prerequisites

This workshop is designed for professional developers, engineers, and technical staff who are comfortable working with code and system design, but you do not need to be an expert in metadata or have prior formal training in this area.

  • 2+ years of experience in software development, data engineering, or systems architecture (or equivalent practical experience).
  • Comfort reading and writing code in at least one modern programming language.
  • Basic familiarity with APIs, databases, and event-driven or service-oriented architectures.
  • A concrete system or problem area from your organization to use as a working example during exercises.
  • Access to example data models, API definitions, or service diagrams (sanitized as needed) that we can safely discuss.
  • Willingness to share your current tech stack and constraints in advance so the workshop can be tailored to your languages, frameworks, and tooling.