Team Collaboration FAQ: Contracts, Config, and Fixtures

Bottom line: settle these once in a team convention — a {"data":…,"meta":…} envelope with HTTP status codes, one naming style site-wide, RFC 3339 timestamps with a time zone, and string enums — then evolve every new API against the same contract by adding fields only, never changing or deleting them.

There is no single correct answer to these questions, but a team must have a single answer — otherwise every new API restarts the same argument.

1. API contracts

What structure should an API return?

Three common shapes, each with a cost:

For internal business APIs, prefer "resource envelope + HTTP status codes that express the outcome":

复制{
  "data": [{ "id": "1", "name": "示例" }],
  "meta": { "total": 128, "page": 2, "pageSize": 20 }
}

For errors, use an HTTP status code plus a structured error body instead of nesting another code:

复制{
  "error": {
    "type": "validation_failed",
    "message": "请求参数校验失败",
    "details": [
      { "path": "/email", "reason": "格式不正确" }
    ]
  }
}

Key point: HTTP status codes already express success or failure, so a business code is redundant. When the two systems coexist, inconsistencies such as "201 but code is 500" are almost inevitable.

Avoid bare arrays. With an array at the top level you cannot attach pagination, totals, or cursors, and adding them later means changing every caller.

Should field names use snake_case or camelCase?

Pick one, apply it site-wide, and never mix them within one JSON document.

Criteria:

1. Who consumes this JSON: choose camelCase when the frontend dominates, snake_case when data pipelines and Python services dominate;
2. Does it map directly to database columns: snake_case saves a conversion layer when passing table structures straight through;
3. Continuity of existing systems: keep whatever the existing API uses; consistency beats correctness.

If you really must convert, do it at the boundary (gateway or frontend request layer) rather than scattering toCamelCase calls through business code.

What format should time fields use?

Use RFC 3339 / ISO 8601 strings with a time zone offset:

复制{
  "createdAt": "2026-10-30T11:37:57+08:00",
  "updatedAt": "2026-10-30T03:37:57Z"
}

Key points:

• Include the time zone: 2026-10-30 11:37:57 without a zone will inevitably break in cross-time-zone scenarios;
• Use Z or an offset consistently: both are correct, but do not mix them within one API;
• Avoid numeric timestamps: whether it is seconds or milliseconds, and whether leap seconds are included, every team has to reinterpret it. When compactness is required, use a millisecond integer, but pin the unit in the documentation.

Prefer field names with an At suffix such as createdAt / updatedAt / deletedAt, so it is obvious at a glance that the value is a point in time rather than a duration. For durations use timeoutMs, ttlSeconds — put the unit in the name.

Should nulls be null or an omitted field?

It depends on whether "this field is meaningful":

The third case is the most commonly overlooked. In a PATCH request:

复制{ "nickname": null }

this means "clear the nickname", whereas leaving nickname out of the request body means "do not touch the nickname". If you treat both as "clear", a user changing their email will wipe their nickname.

Once more: do not use undefined. It is not a valid JSON value, and JSON.stringify drops the key entirely, so the behavior matches "omit" while the code looks like "an empty value was passed explicitly".

How should boolean fields be named?

Use the is / has / can / should prefixes and avoid negations.

复制{
  "isActive": true,
  "hasPassword": false,
  "canEdit": true
}

Three lessons:

1. No negations: isDisabled: false forces the reader to invert it once; isEnabled: true is more direct. Double negation (isNotDisabled) is a disaster;
2. Do not use numbers for booleans: "enabled": 1 makes every consumer write === 1 once;
3. Do not use strings: "enable": "true" is truthy in JavaScript, and if (data.enable) is also true for "false"; such bugs are extremely hard to trace.

Should enum fields use numbers or strings?

Use strings unless there is a clear storage or bandwidth constraint.

复制{ "status": "active" }

Compared with { "status": 1 }, strings win because:

• Logs, packet captures, and databases are directly readable without looking up a mapping table;
• Adding an enum value does not change the meaning of existing values (inserting a value in the middle of a numeric enum shifts everything);
• The frontend does not need to maintain a 1 → 'active' mapping in sync.

The cost is a few extra bytes, which is almost negligible after compression.

Companion practice: use lowercase + underscores for string enum values (pending_review), and constrain them with enum in the Schema so invalid values are rejected at the validation stage.

2. Configuration and fixtures

Should config be JSON, YAML, or TOML?

Choose by purpose, not by preference:

A common mistake in teams is storing business config in YAML — YAML's implicit type conversion (1.0 becomes a number, NO becomes a boolean, 2026-10-30 becomes a date) produces different results across parsers.

If the config must be strictly validated by a program, choose JSON + Schema, and document comments through a _comment field or separate docs.

How should test fixtures be organized?

Organize by "one baseline + minimal diffs", not by copying a huge JSON for every test case.

复制fixtures/
├─ users/
│  ├─ base.json              # Baseline user object
│  ├─ no-email.json          # Only email is missing
│  └─ invalid-age.json       # Only age is out of range
└─ fixtures.ts               # Utility functions for loading and shallow merging

复制import baseUser from './users/base.json';

export function makeUser(overrides: Partial<User> = {}): User {
  return { ...baseUser, ...overrides };
}

That way a new test case only needs to write the differing fields, and changing a baseline field updates every case automatically.

Three rules:

1. Fixtures must pass Schema validation: the baseline fixture itself should be valid data;
2. Do not export real data from production: phone numbers, ID numbers, and addresses are all personal information;
3. Fixtures belong in version control but must stay small: a single file beyond a few tens of KB deserves pruning or generation.

How do I reduce merge conflicts in JSON files?

JSON conflicts easily: a formatter reflows the whole file at once, so two people each changing one line conflict on the entire file.

Four tactics:

1. Unify formatting and add it to .editorconfig: consistent indentation, line endings, and trailing newline avoid unrelated diffs;
2. Sort keys: agree on alphabetical ordering so a new field does not collide with someone else's insertion point;
3. Split files: break one giant config.json into several files by domain, and the conflict surface shrinks naturally;
4. Avoid "reformat everything" commits: separate formatting from business changes into two commits so the review stays readable.

If the team uses lock files (pnpm-lock.yaml, package-lock.json), do not merge them by hand; regenerate them instead:

复制git checkout --theirs pnpm-lock.yaml
pnpm install

How do I maintain version compatibility?

The principle is "add, do not change, do not remove".

Supporting mechanisms:

• Consumers use "lenient parsing": ignore unknown fields and supply defaults for missing ones;
• The server keeps old fields for a while and returns a Deprecation header in the response as a hint;
• In the Schema, do not mark new fields as required, and tag deprecated fields with deprecated: true.

How do I validate contracts in CI?

Treat the Schema as part of the code and validate it on every commit.

复制# Validate sample data against the Schema (using ajv-cli)
npx ajv-cli validate -s schemas/user.json -d "fixtures/users/*.json" --strict=false

Run three things in CI:

1. Validity of the Schema itself: whether the $schema declaration is valid and whether $ref resolves;
2. Whether the fixtures match the Schema: ensures test data does not drift;
3. Whether the contract is backward compatible: compare against the previous version and check for removed fields or changed types.

The third item needs tooling support (such as openapi-diff or json-schema-diff); without it, at least compare changes in the required arrays and the properties key sets with a script.

3. Quick reference