Add Fields to an API

Add product fields to show additive schema evolution across compatibility and evolved APIs.

Addition of a new field to the API.

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 first sale document was useful for opening day. It is no longer enough for the next version of the business.

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.

Schema Change

The schema adds the new columns with defaults.

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

The defaults are what allow the older document shape to keep working.

Older clients do not send product_type or tags. The database can still accept those older documents because it knows what values to use when the new fields are missing.

Compatibility API

This scenario creates sales_v1.

From this point forward, sales_v1 is the older compatibility API. Future scenarios can introduce sales_v2, but sales_v1 represents the document shape that existing systems must still be able to use.

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
    }
}

API Shift

Dave now has a durable sales API.

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

The older shape can still be inserted because the database supplies defaults. The evolved shape works because sales_v1 exposes the new fields directly.

This is the first real evolution pattern. The business API grows without abandoning existing clients.

New Behavior Used

This scenario introduces one practical behavior that will matter throughout the evolution.

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

By the end of this scenario, the script proves three things:

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 API reads are not broken just because the evolved data contains additional fields. As long as the fields required by the older API specification are still available, the older API can ignore newer fields that it does not understand.

The important result is interoperability. Old-style and new-style sale documents can live over the same evolved schema.

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 older clients because those clients do not send the new field.

Topic Takeaway

This is where the evolution really begins.

sales_v1 becomes the durable older API. It knows about products, but it still has the simple sale shape. Later scenarios will move beyond this shape, but they must keep it usable so older systems can continue operating while the business grows.