One of the hardest parts of developing a product is the coordination of so many teams and moving parts. Ensuring that everyone is moving in the same direction, towards the same goal, and in a way that is complimentary is the single most important – but also the single hardest – element of any collaborative project. Failure to properly align your resources could slow development, make for repeated effort across multiple domains, and in some cases, even end projects entirely.

What’s the solution, then? Establishing a single source of truth through the use of schema-first design can help align software development. Identifying a common goal, and establishing a source for teams and processes to align themselves with is incredibly important, and in this piece, we’ll give you the understanding, and some tools, to do exactly that.

The Problems With Traditional Development

When defining why schema-first is necessary, we first need to look at what is wrong with the traditional development process. When developing an application in the traditional sense, development is often split between multiple teams, and sometimes between multiple departments. There is a stated common goal, but it is typically somewhat broad-based, such as “we need to create an application that leverages Python to process consumer numerical requests.” Setting goals like these are necessary but leave development specifics vague.

The idea is to have these teams on the same page, developing separately but collaboratively towards the stated end goal. The actuality of the situation is often the inverse, however, due to the inherent variety of development paradigms. Development teams do not always clearly communicate, and as such, they are often at different stages in their development cycle.

The situation becomes worse when teams are combative with one another. A team may have to wait for the other to create their module, and then the other team may de-prioritize that request for their own work path. Over time, these subtle, indirect competitive projects have the cumulative effect of decreasing the success of the project. Add on to this the standard practice of changing feature sets, scope shifts, etc., and you’ve got a formula for disaster.

The issue is not just between teams, either. Matching API and application development with developer needs is one thing, but having to also then match to business purposes and stakeholder expectations is quite troublesome. Lacking a strict limitation on what is possible and what is expected only amplifies these issues.

Later on, once the API and application are complete and documentation is generated, more issues crop up. Matching documentation to actual functionality, ensuring up to date contents and references, and other such issues of joining actuality with expected functionality can quickly kill adoption or make further iteration that much harder.

That is exactly what a schema creates — a contract, a plan, and a detailed agreement. When we discuss the concept of the “schema,” what we’re really discussing is a code-defined organizational structure, a system that defines and constrains the design and function of a given codebase within a specified “blueprint.” A schema often defines data types and their specific interactions, and can take many forms.

What is Schema-First Development

Perhaps the best solution to this problem is the adoption of a schema-first development practice. Schema-first development establishes a contract between developers and the operational expectations from project managers. A schema is foundationally an agreed upon set of standards and approaches – and in establishing the schema as a constrained contract, you can ensure that no matter what comes out of development, it will align with the stated overall goals.

By doing so, teams don’t even necessarily have to communicate – their systems will work with one another as long as they adhere to the contract. By the time you’re done, everything will work the way it is supposed to, without the need to have massive scrums or pause development while waiting for modules or parts of the codebase to be finished.

Consider a basic JSON example:

{
    "title": "Person",
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string"
        },
        "lastName": {
            "type": "string"
        },
        "age": {
            "description": "Age in years",
            "type": "integer",
            "minimum": 0
        }
    },
    "required": ["firstName", "lastName"]
}

In such a schema, we can see the exact function of each piece of data, and how that data interacts with others. We know that the firstName is a string property, that age is an integer type with a minimum value, and that both are elements of the object Person. From here, with additional objects, functions, types, and endpoints, we can form a range of specific objects and entities, and define their function in context with one another, rather than define their function esoterically.

5 Benefits of Schema-First Design

So what are some benefits of adopting a schema-first design? In addition to collaboration improvement and platform consistency, there are other actional benefits that can be garnered through adoption.

1: Constrained Development

Choosing a constrained schema forces teams to communicate to one another. This communication may not be explicit, but as their functions are limited by stated constraints, they are always passively adhering to the communicated intent of the agreed upon contract.

While actual, direct communication is at times preferable, adopting a schema-first concept forces teams to work more efficiently by staying “on spec.” This passive aligning with the stated goal means that teams can develop without having to wait for new modules, as they expect certain functionality from the core and the stated alignment. All work is synchronized in concert with one another.

Takeaway:

Schema-first design establishes a constrained development process that prevents development and scope drift.

2: Faster Development

A huge benefit of having a common, accepted specification is that development is much faster than traditional methods would allow. Frontend teams can immediately start building components regardless of whether or not such backend components actually exist, because they don’t have to wait to see what hook needs to be called and how it will function. While the endpoints and internal elements will likely change, the way they function will not – teams broadly know what is to be built because they know the constraints upon which it will be built.

The same is true of the backend team. Their work does not need to be translated to the frontend team, as everything is designed in a standardized way, and as such, is very predictable. If planning was done correctly before development, and both timelines and goals are well-stated, this development can be even faster due to gains in efficiency by coordinated efforts.

Takeaway:

Schema-first design reduces many of the elements that result in development lag and slowing of processes.

3: Cleaner Development

Somewhat tertiary to efficient development is the fact that development is much cleaner. Adopting a schema-first approach has the effect of lowering issues of uncooperating codebase functions, errors between misstated endpoints and handlers, etc. By having teams agree on a schema, errors are drastically reduced, as are bugs for unintended functionality – the functionality is known and expected, so when a bug does occur, it can be identified quickly.

This approach also can also reduce duplication. Without a stated contract of what is what and how we expect it done, backend teams can build hooks the frontend team doesn’t need, frontend can replicate functionality that may not be necessarily front-facing, or entire functions could be crafted for purposes that no longer exist. Defining the expected code-base and what it should do alleviates many of these issues.

Takeaway:

Schema-first design results in a cleaner codebase, in which expected functionality is presented in a clean manner without duplication of code and effort.

4: Generation of Resources

A massive benefit that can’t be overlooked is the fact that adopting a schema-first approach creates material that can be used to generate additional resources. Having the codebase adhere to a strict schema is just like a language or math – with a common set of rules, anything can be ported or translated between multiple forms.

Well-defined schema-driven codebase contents can be used to automatically generate an API, its documentation, and even the CLI that drives the functions. Additionally, a base schema and API can be leveraged to generate or render a hypermedia API with very little additional overhead.

It should also be noted that a well-defined schema-based API lends itself really well to iteration, as such iterations are based on known elements and constraints, and therefore can be pushed without breaking functionality for clients or forks of the main codebase.

Takeaway:

Schema-first design allows for automated generation of key resources to API and application adoptees, and reduces time-to-market in turn.

Single Source of Truth

All of these benefits come together to form the meat of why schema-first is so effective – it crafts a single source of truth. The concept of a single source of truth can roughly be summarized as forming a structured information model and schema approach that defines data elements singularly. In other words, there should be an agreed upon schema that defines functionality and the data that it handles, rather than using different sources from different teams, who may not even agree on the stated goal of the project.

A single source of truth is essentially a “lingua franca” of goals; it provides direction for every decision that is made, and a single reference point. In this case, there is no “desktop” specific data, “mobile” specific data, or “deprecated design” – everything is based upon a single source, a single reference point, and thereby, there is little duplicated or confused content.

Final Thoughts

Schema-first design takes an unspoken agreement about purpose and plan, and converts it into a stated, accepted, and shared guideline for development. Without such a stated, singular goal, any development project is going to be largely unguided, and due to this, will suffer many of the woes we’ve discussed today.

The simple fact is that adopting schema-first design is not difficult, and the benefits gleaned from its adoption are so massive that it can’t be ignored. Leveraging a single source of truth is extremely powerful, and should be done as soon as possible in a development process – and adopting schema-first design is the easiest way to establish such a source.

What do you think about schema-first design? Is a single source of truth truly that important, or are other methodologies acceptable in certain applications? Let us know in the comments below.