@voxgig/apidef 8.3.0 → 8.5.0

package/dist/transform/field.js

@@ -7,7 +7,7 @@ const jostraca_1 = require("jostraca");
 const utility_1 = require("../utility");
 const types_1 = require("../types");
 const fieldTransform = async function (ctx) {
-    const { apimodel, def } = ctx;
+    const { apimodel, def, guide, model } = ctx;
     const kit = apimodel.main[types_1.KIT];
     let msg = 'field ';
     const opFieldPrecedence = ['load', 'create', 'update', 'patch', 'list'];
@@ -39,9 +39,88 @@ const fieldTransform = async function (ctx) {
         // Downstream (test generators, fixture builders) gate id-specific code on
         // this presence so that public read-only APIs without ids don't get
         // bogus id assertions.
+        // COMPOSITE FIRST, because a compound key need not come with an `id`.
+        //
+        // An entity addressed by `{owner}/{repo}` whose response carries only
+        // `owner` and `name` has no field literally named `id`, and its adjacent
+        // placeholders are left unrenamed so `addressedById` is false too.
+        // Neither branch below then ran, so the entity got NO id descriptor and
+        // even an explicit `guide.entity.<name>.id.parts` was silently ignored —
+        // while the Go port, which initialises a descriptor unconditionally,
+        // emitted the composite. The ports disagreed on exactly the shape this
+        // feature exists for.
+        const gent = guide?.entity?.[ment.name];
+        const composite = compositeId(ment, gent, def);
         const idField = fields.find((f) => 'id' === f.name);
-        if (idField) {
-            ment.id = { name: 'id', field: 'id' };
+        // A COMPOSITE ID IS A STRING, whatever the API's own `id` field is —
+        // AND THE API'S OWN id IS KEPT.
+        //
+        // github's repo declares `id` as an integer, its global database id,
+        // while the composite identity is `owner/repo`. Two facts have to
+        // survive: `id` must hold a string, because that is what the joined
+        // value is and what every generated type has to store; and the spec's
+        // numeric property must not be silently reinterpreted, because a
+        // consumer that wants the database id is entitled to it with its own
+        // type and format intact.
+        //
+        // So the API's field MOVES to `<api>_id` rather than being rewritten in
+        // place, carrying its type, format and per-op overrides with it, and the
+        // entity's `alias.field` map records where it went. Retyping in place
+        // (the first attempt) claimed the server's numeric id was a string;
+        // leaving it alone made `id.field` name a declaration the runtime value
+        // cannot satisfy. Moving it is the only option that lies about neither.
+        if (null != composite.parts && null != idField && !scalarStringField(idField)) {
+            const idf = idField;
+            const apiname = String(model?.name || 'api');
+            const keep = apiname + '_id';
+            if (!fields.some((f) => f.name === keep)) {
+                // A DEEP COPY, because the move is followed by deletions on the
+                // original. A spread shares the `op` object, so clearing the stale
+                // per-op `type` off `id` cleared it off the preserved field too —
+                // the preservation preserved nothing for exactly the key it was
+                // added to keep.
+                fields.push(JSON.parse(JSON.stringify({ ...idf, name: keep })));
+                const alias = (ment.alias = ment.alias || {});
+                alias.field = alias.field || {};
+                alias.field[keep] = 'id';
+            }
+            idf.type = '`$STRING`';
+            // The facts that described the moved type go with it: `format: int64`
+            // beside a string, or a per-op `type` override still saying integer,
+            // is a model contradicting itself — and the op override is what a
+            // generator reads for that op.
+            delete idf.format;
+            for (const opname of Object.keys(idf.op || {})) {
+                delete idf.op[opname].type;
+            }
+            fields.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        }
+        if (null != composite.parts && null == idField) {
+            // The FIELD as well as the descriptor, for the reason the branch below
+            // documents: a model that declares the descriptor without the field
+            // makes the generated type disagree with the generated test.
+            fields.push({
+                name: 'id',
+                type: '`$STRING`',
+                req: false,
+            });
+            fields.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        }
+        const singleKey = composite.single;
+        delete composite.single;
+        if (null == idField && null != singleKey && null == composite.parts) {
+            // The guide disabled composite; the terminal parameter is the key, and
+            // the entity needs the field to carry it for the same reason the
+            // composite branch above does.
+            fields.push({
+                name: 'id',
+                type: '`$STRING`',
+                req: false,
+            });
+            fields.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        }
+        if (idField || null != composite.parts || null != singleKey) {
+            ment.id = { name: 'id', field: 'id', ...composite };
         }
         else if (addressedById(ment)) {
             // The FIELD as well as the descriptor. An entity addressed by id has an
@@ -76,13 +155,493 @@ const fieldTransform = async function (ctx) {
             // with neither a field nor an id param — the read-only public APIs the
             // rule above was written for — still get no descriptor, so they still
             // get no id assertions.
-            ment.id = { name: 'id', field: 'id' };
+            ment.id = { name: 'id', field: 'id', ...composite };
         }
         msg += ment.name + ' ';
     });
     return { ok: true, msg };
 };
 exports.fieldTransform = fieldTransform;
+// The separator that joins a composite id into one string.
+//
+// A forward slash cannot occur inside a single path segment — a raw `/`
+// would end the segment, and a value that legitimately contains one arrives
+// percent-encoded as `%2F` — so joining on it can never be ambiguous, and
+// splitting on it can never over-split. That is what makes the composite id
+// safe to carry as a single opaque string, which is the property the SDK and
+// Seneca entities are built on.
+const ID_SEP = '/';
+// Subfields that conventionally carry the identifying value of a nested
+// object, in preference order. github's repo `owner` is a user object whose
+// identifier is `login`; other specs use `name`, `slug` or `key`. `id` is
+// last: it is the most common name and the least likely to be the value a
+// PATH parameter takes (a path that wanted an id would say so).
+const NESTED_ID_KEYS = ['login', 'slug', 'name', 'key', 'id'];
+// The ops that address ONE record, most authoritative first. Only a
+// tie-break: identityParams compares candidates from all of them.
+const ID_OPS = ['load', 'update', 'patch', 'remove'];
+// The parameters that TOGETHER name one record: the trailing run of
+// ADJACENT variable segments on the addressing route.
+//
+// ADJACENCY IS THE WHOLE TEST, and it is what separates a compound key from
+// ordinary parent/child nesting:
+//
+//   /repos/{owner}/{repo}                     -> owner, repo   COMPOSITE
+//   /api/planet/{planet_id}/moon/{moon_id}    -> moon_id       single
+//   /repos/{owner}/{repo}/pulls/{pull_number} -> pull_number   single
+//
+// A literal segment between two variables names a SUB-COLLECTION, so the
+// earlier variable scopes the later one — `planet_id` says which planet's
+// moons, and `moon_id` alone identifies the moon. Two variables with nothing
+// between them address no sub-collection: neither value names anything on
+// its own, and only the pair identifies a repository.
+//
+// Taking every variable on the path instead was tried first and is wrong on
+// most real specs — it made `moon` (planet_id + moon_id), petstore's `order`,
+// `pet` and `user`, and taxonomy's `domain` and `kingdom` all falsely
+// composite, which the apidef-validate goldens caught immediately. Nested
+// resources are the common shape; compound keys are the exception, and
+// adjacency is the thing that actually distinguishes them.
+//
+// Read from the op that names a single record, never from `list`: a
+// collection route's path params are the entity's parents. A point ending in
+// a literal is a verb ON the record (`.../{number}/merge`) and carries the
+// same variables, so it is a fallback rather than a different answer.
+// Walk back from a point's end, collecting variables until a literal stops
+// the run. That literal is the sub-collection boundary; anything before it
+// scopes this record rather than naming it.
+function trailingVars(point) {
+    const segs = (point?.segments || []).filter((s) => null != s);
+    const run = [];
+    for (let i = segs.length - 1; 0 <= i; i--) {
+        if (null == segs[i].var) {
+            break;
+        }
+        run.unshift(String(segs[i].var));
+    }
+    return run;
+}
+function identityParams(ment) {
+    // EVERY ID-BEARING OP AT ONCE, not the first one that offers a candidate.
+    //
+    // These four ops all address a single record, so all four describe the
+    // same identity — but they do not all carry the same routes. gitlab's
+    // `project` has `/api/v4/projects/{id}` under `remove` alone, while its
+    // `load` carries only sub-resources like
+    // `/api/v4/projects/{id}/uploads/{secret}/{filename}`. Returning on the
+    // first op with any candidate therefore made a PROJECT identified by
+    // `secret/filename`. The op order is now only a tie-break.
+    const cands = [];
+    for (let o = 0; o < ID_OPS.length; o++) {
+        const mop = ment.op?.[ID_OPS[o]];
+        if (null == mop) {
+            continue;
+        }
+        // Action points are verbs dispatched by `$action`, not addresses.
+        for (const pt of (mop.points || [])) {
+            if (null != pt?.select?.['$action']) {
+                continue;
+            }
+            const run = trailingVars(pt);
+            if (0 === run.length) {
+                continue;
+            }
+            cands.push({
+                run,
+                // Segments BEFORE the run: how much parent scope the route needs.
+                scope: ((pt.segments || []).length - run.length),
+                // DOES THE RUN END IN THE RECORD'S OWN KEY? Then it is the
+                // record's address and nothing further is needed.
+                //
+                // This transform RENAMES that parameter to `id`, so a run ending in
+                // it is this port's own statement of what identifies the record —
+                // and the composite inference must not contradict it.
+                // `/gists/{gist_id}` becomes `/gists/{id}` and is a gist;
+                // `/gists/{gist_id}/{sha}` is a REVISION of one, and won on key
+                // length alone, so a gist came out keyed `gist_id/sha` while the
+                // generated SDK's own load match takes the single parameter. The
+                // same contradiction gave cloudsmith's repo and vulnerability
+                // compound keys their SDKs never address them by.
+                //
+                // Deliberately narrow: exactly `id` or an unrenamed `<entity>_id`,
+                // never any `*_id`. `actor_type/actor_id` IS a compound key, and a
+                // looser test breaks it.
+                own: 'id' === run[run.length - 1] ||
+                    ment.name + '_id' === run[run.length - 1],
+                order: o,
+            });
+        }
+    }
+    // WHICH ROUTE IS THE RECORD'S OWN ADDRESS.
+    //
+    // An entity gathers every route that reads it, and in a large
+    // specification most of those are sub-resources. Three earlier rules were
+    // measured against the validation corpus, and each is wrong:
+    //
+    //   The FIRST route listed gave github's `repo` the single part
+    //   `subject_digest`, from
+    //   `/repos/{owner}/{repo}/attestations/{subject_digest}` — no compound
+    //   key at all, for the entity this feature exists for. Invisible on a
+    //   small spec, where the first item route IS the record's own.
+    //
+    //   The SHORTEST route ending in a variable took cloudsmith's
+    //   `/vulnerabilities/{owner}/` — a LIST of an owner's vulnerabilities —
+    //   and cut a four-part key down to `owner`, dropping three more
+    //   composites. Ending in a variable does not make a route an address.
+    //
+    //   The LONGEST trailing run took
+    //   `/orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}` and made a TEAM
+    //   identified by `owner/repo`. A deep sub-resource can carry more
+    //   adjacent variables than the record's own route does.
+    //
+    // What separates them is PARENT SCOPE: the record's own route is the
+    // least-qualified one that names it, and among equally-qualified routes
+    // the one carrying the fullest key. `/repos/{owner}/{repo}` is qualified
+    // by one segment and the attestations route by four; `/teams/{team_id}`
+    // by one and the org-team-repo route by five; cloudsmith's vulnerability
+    // routes are all qualified by one, so the fullest of them wins.
+    const best = cands.reduce((b, c) => {
+        if (null == b) {
+            return c;
+        }
+        if (c.scope !== b.scope) {
+            return c.scope < b.scope ? c : b;
+        }
+        if (c.own !== b.own) {
+            return c.own ? c : b;
+        }
+        if (c.run.length !== b.run.length) {
+            return b.run.length < c.run.length ? c : b;
+        }
+        return c.order < b.order ? c : b;
+    }, null);
+    return null == best ? [] : best.run;
+}
+// THE PROPERTY MAPS A RESPONSE COULD BE DESCRIBING, best first.
+//
+// BOTH SPEC DIALECTS. An OpenAPI 3 response carries its schema under
+// `content['application/json']`; a SWAGGER 2 response carries it directly as
+// `schema`. Reading only the first resolved nothing for every Swagger 2 spec
+// in the validation corpus.
+//
+// JSON ONLY, where there is a choice. An operation may declare several media
+// types with different schemas, and field extraction uses the JSON one — so
+// picking whichever came first in source order could infer a path from an XML
+// or binary schema that the actual JSON record does not have.
+//
+// `allOf` IS EXPANDED, because a response that composes its entity that way
+// has neither `properties` nor `items` of its own. field extraction expands
+// it; not doing so here meant the fields were present while the id could not
+// be reconstructed.
+//
+// ONLY THE ENVELOPE IS DESCENDED, via the same `envelopeProp` rule field
+// extraction uses. Descending every object-valued property instead treats an
+// ordinary nested object as a whole record: for `{ slug, metadata: { tenant } }`
+// addressed by `{tenant}/{slug}`, `tenant` resolved to `tenant` rather than
+// `metadata.tenant` — a confidently wrong path, which is worse than no
+// mapping at all.
+//
+// ACTION POINTS ARE SKIPPED, as `identityParams` skips them: an action's
+// response is a verb's result, not a representation of the entity, so a field
+// that happens to appear there says nothing about what a returned record
+// carries.
+function responseCandidates(ment, def) {
+    const out = [];
+    const seen = new Set();
+    // Every property map this schema describes, expanding allOf.
+    const propsOf = (schema) => {
+        const node = resolveRef(schema, def);
+        if (null == node || seen.has(node)) {
+            return [];
+        }
+        seen.add(node);
+        if (Array.isArray(node.allOf)) {
+            return node.allOf.flatMap((member) => propsOf(member));
+        }
+        if (null != node.properties) {
+            return [node.properties];
+        }
+        // A bare array response: the record is the item.
+        const items = resolveRef(node.items, def);
+        if (null != items) {
+            return propsOf(items);
+        }
+        return [];
+    };
+    const add = (schema, opname) => {
+        for (const props of propsOf(schema)) {
+            out.push(props);
+            // One level in, but ONLY through the envelope property.
+            const envelope = (0, utility_1.envelopeProp)(props, opname);
+            if (null == envelope) {
+                continue;
+            }
+            const inner = resolveRef(props[envelope], def);
+            if (null == inner) {
+                continue;
+            }
+            for (const innerProps of propsOf(inner)) {
+                out.push(innerProps);
+            }
+        }
+    };
+    for (const opname of ['load', 'list', 'update', 'create']) {
+        const mop = ment.op?.[opname];
+        for (const mpoint of (mop?.points || [])) {
+            // An action point's response is not the entity.
+            if (null != mpoint?.select?.['$action']) {
+                continue;
+            }
+            const path = (def?.paths || {})[mpoint?.orig];
+            const method = String(mpoint?.method || '').toLowerCase();
+            const responses = path?.[method]?.responses || {};
+            for (const code of Object.keys(responses)) {
+                if (!/^2/.test(code)) {
+                    continue;
+                }
+                const resdef = responses[code] || {};
+                const content = resdef.content || {};
+                const ctypes = Object.keys(content);
+                // Prefer JSON; fall back to whatever single type is offered.
+                const json = ctypes.find((c) => c.includes('json'));
+                if (null != json) {
+                    add(content[json]?.schema, opname);
+                }
+                else {
+                    for (const ctype of ctypes) {
+                        add(content[ctype]?.schema, opname);
+                    }
+                }
+                // Swagger 2 puts it here.
+                add(resdef.schema, opname);
+            }
+        }
+    }
+    return out;
+}
+// A `$ref` followed one hop, or the schema itself. apidef resolves most refs
+// before this stage; this covers the ones that survive on a nested property.
+function resolveRef(schema, def) {
+    if (null == schema) {
+        return null;
+    }
+    const ref = schema.$ref;
+    if ('string' !== typeof ref || !ref.startsWith('#/')) {
+        return schema;
+    }
+    let node = def;
+    for (const seg of ref.slice(2).split('/')) {
+        node = node?.[seg];
+        if (null == node) {
+            return null;
+        }
+    }
+    return node;
+}
+// The conventional identifying subfield of a property map, or null.
+function conventionalIdKey(props) {
+    for (const key of NESTED_ID_KEYS) {
+        const p = props[key];
+        if (null == p) {
+            continue;
+        }
+        const t = String(p.type || '');
+        if ('object' !== t && 'array' !== t) {
+            return key;
+        }
+    }
+    return null;
+}
+// Every name a part might be carried under: the model's name for it, plus the
+// original wire names of any path parameter that was renamed to it.
+function partAliases(ment, part) {
+    const names = new Set([part]);
+    (0, jostraca_1.each)(ment.op, (mop) => {
+        (0, jostraca_1.each)(mop?.points, (mpoint) => {
+            const rename = mpoint?.rename?.param || {};
+            for (const orig of Object.keys(rename)) {
+                if (String(rename[orig]) === part) {
+                    names.add(orig);
+                }
+            }
+            for (const arg of (mpoint?.args?.params || [])) {
+                if (null != arg && arg.name === part && null != arg.orig) {
+                    names.add(String(arg.orig));
+                }
+            }
+        });
+    });
+    return [...names];
+}
+// Where one part is carried in a given property map, or null.
+//
+// The four rules, in order, each a fact the spec states: a scalar property of
+// that name; the part naming this entity, resolved to `name`; a scalar
+// `<part>_name` / `_login` / `_slug`; or an object property's conventional
+// identifying subfield.
+function resolvePart(ment, part, aliases, props, def) {
+    if (null == props) {
+        return null;
+    }
+    const prop = (name) => resolveRef(props[name], def);
+    const scalar = (p) => null != p && 'object' !== String(p.type) && 'array' !== String(p.type) &&
+        null == p.properties && null == p.items;
+    for (const name of aliases) {
+        if (scalar(prop(name))) {
+            return name;
+        }
+    }
+    if (part === ment.name && scalar(prop('name'))) {
+        return 'name';
+    }
+    for (const name of aliases) {
+        for (const suffix of ['_name', '_login', '_slug']) {
+            if (scalar(prop(name + suffix))) {
+                return name + suffix;
+            }
+        }
+    }
+    for (const name of aliases) {
+        const nested = prop(name);
+        if (null != nested?.properties) {
+            const sub = conventionalIdKey(nested.properties);
+            if (null != sub) {
+                return name + '.' + sub;
+            }
+        }
+    }
+    return null;
+}
+// WHERE EACH COMPOSITE PART'S VALUE LIVES IN A RESPONSE.
+//
+// The parts are PATH PARAMETER names; a response names its fields whatever it
+// likes. Resolving one to the other is what lets an SDK put an id on a record
+// the API returned, rather than only address a record whose id it was given.
+//
+// The rules, in order, and each of them is a fact about the spec rather than
+// a guess:
+//
+//   1. a scalar field of exactly that name             -> itself
+//   2. the part names this entity, and there is a `name` -> `name`
+//      (`/repos/{owner}/{repo}` on entity `repo`, whose response calls the
+//      repository `name`)
+//   3. a scalar `<part>_name` / `<part>_login` / `<part>_slug`
+//   4. an OBJECT field of that name         -> `<part>.<conventional key>`
+//      (`owner` is a user object; the value is `owner.login`)
+//
+// A part none of these resolve is left OUT. Downstream then knows the id
+// cannot be rebuilt for that entity and can say so, which is better than a
+// confidently wrong id on a real record. guide.aon can state it instead.
+function identityFrom(ment, parts, def) {
+    // THE RESPONSE SCHEMA IS THE AUTHORITY, not `ment.fields`.
+    //
+    // `ment.fields` is merged across load, create, update and list, so a part
+    // that exists only in a REQUEST BODY appears there too. Resolving against
+    // it recorded such a part in `from` as though a returned record carried it,
+    // and a consumer then rebuilt an id from a property the response never
+    // sends — worse than leaving the part unresolved, which at least says so.
+    //
+    // Candidate property maps, in order: the response's own properties, then
+    // one level into an envelope. A response that wraps the record
+    // (`{ item: {...} }`, `{ data: [ {...} ] }`) states the record's fields one
+    // level in, and searching only the wrapper found nothing.
+    const candidates = responseCandidates(ment, def);
+    const out = {};
+    for (const part of parts) {
+        // THE WIRE NAME AS WELL AS THE MODEL NAME. `identityParams` reads the
+        // RENAMED parameter off the path segments, while a response keeps its own
+        // casing — so a `tenantKey` renamed to `tenant_key` was looked up under a
+        // name the response does not use, and the mapping was dropped for every
+        // camel-cased or depluralized parameter.
+        const aliases = partAliases(ment, part);
+        let found = null;
+        for (const props of candidates) {
+            found = resolvePart(ment, part, aliases, props, def);
+            if (null != found) {
+                break;
+            }
+        }
+        if (null != found) {
+            out[part] = found;
+        }
+    }
+    return out;
+}
+// Is this model field declared as a string? A composite id is the parts
+// joined, so the field that holds it has to be one.
+function scalarStringField(f) {
+    return String(f?.type || '').toUpperCase().includes('STRING');
+}
+// WHICH PARAMETER IS THE RECORD'S OWN KEY, among several that looked
+// adjacent. The same shape apidef's id handling recognises everywhere else:
+//
+//   1. one named exactly `id`
+//   2. `<entity>_id` — the entity's own id, however the path spells it
+//   3. any `*_id` — an id by name
+//   4. failing all that, the terminal parameter
+//
+// Position is the LAST resort, not the first.
+function singleKeyOf(ment, parts) {
+    if (0 === parts.length) {
+        return undefined;
+    }
+    return parts.find((p) => 'id' === p)
+        ?? parts.find((p) => p === ment.name + '_id')
+        ?? parts.find((p) => p.endsWith('_id'))
+        ?? parts[parts.length - 1];
+}
+// The composite half of the id descriptor, or `{}` for the ordinary case.
+//
+// Emitted ONLY for a genuinely composite id (two or more addressing
+// parameters). A single-parameter entity already round-trips through one
+// `id` and gains nothing from carrying a one-element `parts`, so its
+// descriptor is left exactly as it was — no existing model output moves.
+function compositeId(ment, gent, def) {
+    const gid = gent?.id;
+    const sep = null != gid?.sep && '' !== String(gid.sep) ? String(gid.sep) : ID_SEP;
+    // `composite: false` turns the inference off. A boolean rather than an
+    // empty `parts`, because aontu resolves an empty list to nothing and the
+    // key would arrive absent — indistinguishable from never having been set.
+    if (null != gid && false === gid.composite) {
+        // DISABLING COMPOSITE MUST NOT DISABLE THE ID. The correction says these
+        // adjacent parameters are not a compound key; it does not say the record
+        // has no key. Returning a bare `{}` left an entity whose response has no
+        // literal `id` with no descriptor at all — the false positive removed and
+        // nothing identifying the real key.
+        //
+        // WHICH of the adjacent parameters is that key is decided by the same
+        // id-finding rules apidef uses elsewhere, not by position. Taking the
+        // terminal one picked `archive_format` for
+        // `/artifacts/{artifact_id}/{archive_format}` — the modifier, precisely
+        // the false positive the correction exists to undo.
+        return { single: singleKeyOf(ment, identityParams(ment)) };
+    }
+    // `from` STATED IN guide.aon WINS PER PART, so a spec can correct one
+    // mapping without restating the others — which matters because the
+    // heuristic gets most of them right and the odd one wrong.
+    const withFrom = (parts, usesep) => {
+        const derived = identityFrom(ment, parts, def);
+        const stated = null != gid?.from && 'object' === typeof gid.from ? gid.from : {};
+        const from = {};
+        for (const part of parts) {
+            const say = stated[part];
+            const use = null != say && '' !== String(say) ? String(say) : derived[part];
+            if (null != use) {
+                from[part] = use;
+            }
+        }
+        return 0 === Object.keys(from).length ?
+            { parts, sep: usesep } : { parts, sep: usesep, from };
+    };
+    if (null != gid && null != gid.parts) {
+        const given = gid.parts
+            .filter((p) => null != p && '' !== String(p))
+            .map((p) => String(p));
+        return 1 < given.length ? withFrom(given, sep) : {};
+    }
+    const parts = identityParams(ment);
+    return 1 < parts.length ? withFrom(parts, sep) : {};
+}
 // True when any of the entity's own operation points declares an `id`
 // parameter — i.e. the API addresses this entity by id, whether or not its
 // response schema declares an id field.