From a79783c67b90593acadea5025a2fb4fe6cdb49a5 Mon Sep 17 00:00:00 2001 From: "Aaron K. Clark" Date: Tue, 19 May 2026 12:15:19 -0500 Subject: [PATCH] docs(openapi): pin VersionInfo.viVersion length to match the validator versioninfo.schema.js caps `viVersion` at 1..255 chars, but the OpenAPI component schema declared it as a bare `{ type: 'string' }`. SDK generators reading the spec couldn't see the bound, so client- side validation had no way to catch oversized payloads before they round-trip. SemVer is much shorter than 255 in practice, but the cap matches every other free-text "name/identifier" column in the API for consistency. Add `minLength: 1, maxLength: 255` to the component schema and pin the bound with a test in tests/api/openapi.test.js. Co-Authored-By: Claude Opus 4.7 (1M context) --- app/config/openapi.js | 6 +++++- tests/api/openapi.test.js | 11 +++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/app/config/openapi.js b/app/config/openapi.js index f23f08b..15084c2 100644 --- a/app/config/openapi.js +++ b/app/config/openapi.js @@ -200,7 +200,11 @@ const versionInfoSchema = { type: 'object', properties: { viId: { type: 'integer', readOnly: true }, - viVersion: { type: 'string' }, + // viVersion mirrors versioninfo.schema.js: 1..255 chars. SemVer + // is much shorter than 255 in practice, but the cap matches + // every other free-text "name/identifier" column in the API + // for consistency. + viVersion: { type: 'string', minLength: 1, maxLength: 255 }, viDate: { type: 'string', format: 'date-time' }, }, }; diff --git a/tests/api/openapi.test.js b/tests/api/openapi.test.js index d77c889..21f1432 100644 --- a/tests/api/openapi.test.js +++ b/tests/api/openapi.test.js @@ -70,6 +70,17 @@ describe('OpenAPI spec', () => { expect(schemas.TimeEntry.properties.teStartedAt).toBeDefined(); }); + test('VersionInfo.viVersion pins the 1..255 bound from the validator', async () => { + // Mirrors versioninfo.schema.js. SDK generators expose viVersion + // as `string`; without minLength/maxLength they can't catch a + // client sending a 10k-char "version" string before the server + // does. + const res = await request(app).get('/openapi.json'); + const vi = res.body.components.schemas.VersionInfo; + expect(vi.properties.viVersion.minLength).toBe(1); + expect(vi.properties.viVersion.maxLength).toBe(255); + }); + test('PurchaseOrderHeader pins the validator field-length bounds', async () => { // Mirrors purchaseorderheader.schema.js. Without these, SDK // generators expose pohReference/pohTerms as unbounded strings