Add Fields to an API

Add product fields to demonstrate the simplest and safest schema evolution pattern: additive evolution. When new information can be introduced without changing existing business concepts, the canonical storage model can evolve while existing applications continue using the earlier document shape.

Business Step

Dave’s kiosk is doing well, and the menu is no longer just “lemonade.”

He now wants to know what kind of product was sold. He also wants to attach a simple label to each sale, such as classic, seasonal, or featured.

The original sale document was sufficient for the first version of the business. As the product catalog grows, the API needs to evolve without disrupting existing clients.

Evolution Goal

Two fields are added to the sale document:

product_type
tags

At this point, tags is still one scalar value. That is enough for a small kiosk. Later, as the business moves toward a restaurant model, tags will need a richer shape.

Unlike later topics in this chapter, this evolution does not restructure the business model. The existing sale entity remains the canonical storage model. The evolution simply extends that model with additional product information.

Schema Change

Two new columns are added with default values. The compatibility strategy is intentionally simple: extend the canonical storage model without changing the existing document contract.

ALTER TABLE sales ADD (
    product_type VARCHAR2(40) DEFAULT 'Classic Lemonade' NOT NULL,
    tags         VARCHAR2(40) DEFAULT 'classic' NOT NULL
);

Default values allow the database to accept older documents that do not yet contain the new fields. Existing applications continue working unchanged, while newer applications can immediately begin using the richer document shape.

Compatibility API

This scenario introduces sales_v1, the first published compatibility API. Later scenarios evolve the API further, but sales_v1 becomes the contract that existing applications continue to rely on.

Documentation view	Role
`sales_view`	Introductory view from Create the Initial Sales Duality View.
`sales_v1`	First durable compatibility API. It includes product_type and tags.

New Duality View

sales_v1 keeps the original sale structure and adds product_type and tags.

CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW sales_v1 AS
sales @insert @update @delete
{
    _id: sale_id,
    date: sale_date,
    quantity,
    amount,
    product_type,
    tags,
    customer_name,
    email_address,
    stand_info: stands @insert @update @nodelete
    {
        _id: stand_id,
        location,
        price_per_cup
    }
};

The evolved document now has product context.

{
    "_id": 6,
    "date": "2026-01-16",
    "quantity": 8,
    "amount": 30.00,
    "product_type": "Mint Lemonade",
    "tags": "seasonal",
    "customer_name": "ivan",
    "email_address": "ivan@example.com",
    "stand_info": {
        "_id": 3,
        "location": "HARBOR CART, PIER 4",
        "price_per_cup": 3.75
    }
}

Design Decision

The business model has expanded, but it has not been restructured. Product information still belongs directly to a sale. The canonical storage model simply records more information than before.

API	Document shape
Before this scenario	Sale document without product_type and tags.
`sales_v1`	Sale document with product_type and tags.

Existing applications continue using the earlier document shape because the newly added fields are optional. Newer applications can use the richer API immediately. The compatibility strategy is additive rather than transformational.

Best Practice: Prefer additive evolution whenever new business information can be introduced without changing existing concepts. Nullable columns and columns with default values allow existing clients to continue using the earlier document shape while newer clients benefit from the richer API.

New Behavior Used

This scenario introduces the first compatibility technique used throughout the remainder of the chapter.

Behavior	Why it matters
Default values for added columns	Older clients can continue inserting documents without knowing about the new fields.

The nested stand pattern is reused from Create the Initial Sales Duality View. The meaningful change here is that the sale API now includes product metadata.

Evolution Check

This additive evolution demonstrates the preferred starting point for API evolution:

The earlier sale shape still works without product_type and tags.
sales_v1 exposes the new product fields.
Sale rows written through either shape can participate in the evolved API.

Older and newer applications now operate over the same canonical storage model. The difference is only the amount of business information each API chooses to expose.

Limitation

Additive evolution is safe only when the newly added columns are nullable or have default values. A new NOT NULL column without a default can break the writing capabilities of older clients because those clients do not send the new field.

Topic Takeaway

This scenario demonstrates the preferred starting point for schema evolution. When new business information can be introduced without changing existing business concepts, the canonical storage model can simply be extended.

Existing applications continue using the earlier document shape, while newer applications immediately benefit from the richer API.

The important design principle is to extend an existing model before restructuring it. Additive evolution usually provides the simplest compatibility strategy and the lowest migration cost.

The cost is that optional fields stay optional unless they can have a default value. Because older clients never send them when writing documents, the database cannot require these fields without breaking the compatibility API, so any rule that makes them mandatory has to wait until those older clients have migrated or can be made read-only.