Skip to content

Commit e39b18e

Browse files
committed
Merge remote-tracking branch 'origin/main' into claude/project-thread-25g3fn
2 parents 73dc5b1 + 14e7239 commit e39b18e

46 files changed

Lines changed: 1392 additions & 404 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
'@objectstack/spec': minor
3+
'@objectstack/lint': patch
4+
---
5+
6+
feat(spec)!: a `controlled_by_parent` object whose one required `master_detail` is marked `readonly: true` or `system: true` is refused at parse
7+
8+
Clause-②: no (narrowing)
9+
10+
Metadata-protocol: narrowed
11+
12+
<!-- adr-0087: not-required (already-registered cbp-master-relation-tiers-retired) registered before this change, amended in this diff: the parse's one-master entry now carries this narrowing, and the stored-row listing reports it under that id -->
13+
14+
**BREAKING** (a declaration the parse accepted is now refused), shipped as `minor` under the 18.x convention for breaking changes, with no retirement stage.
15+
16+
ADR-0055 §1: a `controlled_by_parent` object derives its record access from exactly one required `master_detail` field. That one master must be a reference every write of a detail supplies, and a field declared `readonly: true` or `system: true` is not one an author's write supplies, so it cannot be that master. `os lint` already reported it at `error` under `relationship/master-detail-required`, but `os lint` is not a publishing door: `os validate`, `os build`, `ObjectSchema.create()`, `defineStack` and the metadata save door accepted it.
17+
18+
- **FROM:** `sharingModel: 'controlled_by_parent'` with one required `master_detail` declared `readonly: true` and/or `system: true` parses, builds and saves.
19+
- **TO:** the parse refuses it at `fields`, naming the object, the field and each flag (the message opens with "Object 'OBJECT' declares sharingModel 'controlled_by_parent' with its one required master_detail, FIELD, marked readonly: true", with each name and flag in a code span). The save door answers `422 INVALID_METADATA` with that issue and stores nothing. `ObjectSchema.create()` refuses it too, because the parse it ends in is the same rule. An objectExtensions entry that leaves the merged master flagged is refused at the extension, as before for the other shapes.
20+
- **The fix:** remove `readonly: true` and `system: true` from the master reference and declare it as an ordinary required field. If the rows must outlive their parent, the object is not a detail: give it its own `sharingModel` (`private`, `public_read` or `public_read_write`).
21+
- **Unchanged:** the runtime. The flags do not change which field the runtime resolves as the master. A flag on a second, non-required `master_detail` beside the master is still reported by `os lint` alone.
22+
23+
Data at rest still loads. A stored object in this shape registers under its `[metadata_spec_invalid]` diagnostic, and `os migrate meta --stored` lists it as a TODO under `cbp-master-relation-tiers-retired`. No conversion rewrites it: dropping the flag changes who may write the reference, which is the owner's decision.
24+
25+
`@objectstack/spec/data`: `controlledByParentMasterRefusal` returns the new shape `master-not-writable` for this object, so a producer that asks it before writing `controlled_by_parent` gets the parse's verdict. `ControlledByParentMasterShape` gains that member. `isControlledByParentMasterField` is unchanged: a flagged required `master_detail` still counts as the master, so beside a second required one the object is still refused as having two.
26+
27+
`@objectstack/lint`: the `relationship/master-detail-required` explanation (`os explain`) now says that the parse refuses every shape that leaves the object without exactly one writable required master, and that a shape on a second, non-required `master_detail` is this rule's report alone.
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@objectstack/spec': patch
3+
'@objectstack/skills': patch
4+
---
5+
6+
docs(spec, skills): the `titleFormat` description and the objectstack-data skill no longer steer a composite record title that must be queried into a formula field
7+
8+
Clause-②: no
9+
Metadata-protocol: none
10+
11+
The `titleFormat` description (and its generated copies on the object, metadata and migration reference pages) and the `objectstack-data` skill's `nameField` and `titleFormat` rows told an author to migrate a composite record title to a `formula` field with `returnType: 'text'` designated as `nameField`. A formula value is computed on read and stored nowhere, so a sort by it is refused, search never reaches it, and an import cannot match a lookup cell against it. Both now say what the record-title lint and ADR-0079 D3 already say: a composite title that import, sort or search must match is a stored computed field, a non-`formula` field that declares an `expression`, which the engine computes and stores on every write, designated as `nameField`; a text formula designated as `nameField` stays legal for a title shown for display only.
12+
13+
The same skill's "Computed column" bullet (`rules/relationships.md`) said a stored field's `expression` is a client compute hint and the sent value is stored verbatim. The engine computes the expression from the row the write stores and stores the result, so a client-sent value never stands; the bullet now says so.
14+
15+
No key, type, default or accepted value changes; only the text an author reads changes.
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
feat(spec)!: the docs-viewer keys are retired — `ApiDocumentationConfig.ui` (with `ApiTestingUiConfigSchema` / `ApiTestingUiType`) and the REST API plugin config's `openApi.uiPath` / `openApi.uiFramework` are refused with a prescription naming the OpenAPI document (ADR-0049)
6+
7+
Clause-②: no (narrowing)
8+
Metadata-protocol: narrowed
9+
10+
<!-- adr-0087: registered api-docs-viewer-keys-retired -->
11+
12+
**BREAKING** — an accept-set narrowing on a published authoring surface, shipped as `minor` under the repo's launch-window convention for accept-set narrowings.
13+
14+
Three keys declared an HTML API documentation viewer, and nothing ever read any of them: `ApiDocumentationConfig.ui` (a viewer type such as `swagger-ui`, `redoc` or `scalar`, served at `ui.path`, default `/api-docs`), and on the REST API plugin config `openApi.uiPath` (default `/api/docs`) with its viewer selector `openApi.uiFramework` (default `swagger-ui`). Since the docs viewer page was taken offline, the API origin serves no HTML viewer at all, only the machine-readable OpenAPI document, so none of the three could be honoured. They are retired under ADR-0049 enforce-or-remove, with no staged window.
15+
16+
**What is refused:** each key is a `retiredKey()` tombstone. Authoring it is a `tsc` error at the site, and a parse error at the key's path whose message is the prescription, for every former value including the old defaults. The value schemas `ApiTestingUiConfigSchema` and `ApiTestingUiType`, with the `ApiTestingUiConfig`, `ApiTestingUiConfigParsed` and `ApiTestingUiType` types, are no longer exported: they had no consumer once `ui` was gone.
17+
18+
**What stays accepted:** every other key of `ApiDocumentationConfigSchema`, `OpenApiGenerationConfigSchema` and `RestApiPluginConfigSchema`, byte-identically, defaults included. The mounted REST surface is unchanged: none of the three keys ever reached it.
19+
20+
## FROM → TO
21+
22+
| you wrote | write instead |
23+
|:--|:--|
24+
| `ui: { type: 'swagger-ui', … }` on an `ApiDocumentationConfig` | nothing: delete the key |
25+
| `openApi: { uiPath: '/api/docs' }` on a REST API plugin config | nothing: delete the key |
26+
| `openApi: { uiFramework: 'redoc' }` on a REST API plugin config | nothing: delete the key |
27+
| `import { ApiTestingUiConfigSchema, ApiTestingUiType } from '@objectstack/spec/api'` | nothing: no replacement exists |
28+
29+
The one-line fix: delete `ui`, `uiPath` and `uiFramework`, and point any viewer or client generator you run yourself at the OpenAPI document, `GET /api/v1/openapi.json` under the REST server's default `api.basePath` and `api.version` (the path follows both), mounted while `api.enableOpenApi` is on.
30+
31+
## Who is affected, measured
32+
33+
- **objectstack** at `b93c750c7`: zero readers and zero authorings outside `packages/spec`. The only identifier hits were a local `uiPath` variable for the unrelated `/ui/view` route in `packages/rest`; nothing in the tree parses the three schemas outside their own unit tests. A tree-scoped absence pin now holds that zero.
34+
- **objectui** at the console pin `.objectui-sha` `56cf4d8e89`: zero hits for any of the keys or exported names, so the console build at the pin is unaffected.
35+
- **Deployed configuration** was not measured.
36+
37+
## The ADR-0087 disposition
38+
39+
- `RETIRED_KEYS_BY_MAJOR[18]` gains `api/ApiDocumentationConfig:ui`, `api/OpenApiGenerationConfig:uiPath` and `api/OpenApiGenerationConfig:uiFramework`; `RETIRED_DEFS_BY_MAJOR[18]` gains `api/ApiTestingUiConfig` and `api/ApiTestingUiType`.
40+
- The D3 semantic entry `api-docs-viewer-keys-retired` and its step-18 rationale fragment carry the prescription to `os migrate meta`, the upgrade guide and `spec-changes.json`.
41+
- No D2 conversion: neither config is a stack collection member or a stored row, so no conversion seam would ever see one. `uiPath` and `uiFramework` carried Zod defaults, but nothing parses the REST API plugin config into a stored or built artifact, so no emitted default needs tolerating.
42+
43+
The retirement kit:
44+
45+
- the three tombstones and their retirement records (`packages/spec/src/api/documentation.zod.ts`, `packages/spec/src/api/plugin-rest-api.zod.ts`); the two value defs deleted; `REST_API_PLUGIN.md`'s example and feature list no longer name a viewer
46+
- pin test `docs-viewer-keys-retirement.test.ts`: `code`, `path` and the prescription at each door (each schema and `RestApiPluginConfigSchema.openApi`), the `tsc` channel, the live controls, zero holders for the retired names, the ADR-0087 registration, and a tree-scoped absence walk
47+
- generated artifacts follow the schema: `authorable-surface/`, `authorable-defaults/`, `json-schema.manifest/`, `api-surface/`, `export-origins/`, `declaration-map/`, the strictness-ledger counts and the reference pages for `api/documentation` and `api/plugin-rest-api`

‎content/docs/references/api/documentation.mdx‎

Lines changed: 12 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,30 @@
11
---
22
title: Documentation schema — API Protocol reference
33
navTitle: Documentation
4-
description: "Provides schemas for generating interactive API documentation and testing interfaces similar to Swagger UI, Postman, etc."
4+
description: "Provides schemas for describing API documentation and test collections."
55
---
66

77
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
88

99
API Documentation & Testing Interface Protocol
1010

11-
Provides schemas for generating interactive API documentation and testing
12-
interfaces similar to Swagger UI, Postman, etc.
11+
Provides schemas for describing API documentation and test collections.
1312

1413
Features:
1514
- OpenAPI/Swagger specification generation
16-
- Interactive API testing playground
15+
- API test requests and collections
1716
- API versioning and changelog
1817
- Code generation templates
1918
- Mock server configuration
2019

2120
Architecture Alignment:
22-
- Swagger UI: Interactive API documentation
21+
- OpenAPI: the machine-readable API description
2322
- Postman: API testing collections
24-
- Redoc: Documentation rendering
23+
24+
The platform serves no HTML documentation viewer: the API origin publishes
25+
the OpenAPI document (`GET {basePath}/openapi.json`) and nothing else, so
26+
this module declares no viewer — the retired `ui` key is refused at parse
27+
with that prescription.
2528

2629
**Documentation Config**
2730
```typescript
@@ -30,11 +33,6 @@ const docConfig: ApiDocumentationConfig = {
3033
title: 'ObjectStack API',
3134
version: '1.0.0',
3235
servers: [{ url: 'https://api.example.com', description: 'Production' }],
33-
ui: {
34-
type: 'swagger-ui',
35-
theme: 'light',
36-
enableTryItOut: true
37-
}
3836
}
3937
```
4038

@@ -45,8 +43,8 @@ const docConfig: ApiDocumentationConfig = {
4543
## TypeScript Usage
4644

4745
```typescript
48-
import { ApiChangelogEntrySchema, ApiDocumentationConfigSchema, ApiTestCollectionSchema, ApiTestRequestSchema, ApiTestingUiConfigSchema, ApiTestingUiType, CodeGenerationTemplateSchema, GeneratedApiDocumentationSchema, OpenApiSecuritySchemeSchema, OpenApiServerSchema, OpenApiSpecSchema } from '@objectstack/spec/api';
49-
import type { ApiChangelogEntry, ApiDocumentationConfig, ApiTestCollection, ApiTestRequest, ApiTestingUiConfig, ApiTestingUiType, CodeGenerationTemplate, GeneratedApiDocumentation, OpenApiSecurityScheme, OpenApiServer, OpenApiSpec } from '@objectstack/spec/api';
46+
import { ApiChangelogEntrySchema, ApiDocumentationConfigSchema, ApiTestCollectionSchema, ApiTestRequestSchema, CodeGenerationTemplateSchema, GeneratedApiDocumentationSchema, OpenApiSecuritySchemeSchema, OpenApiServerSchema, OpenApiSpecSchema } from '@objectstack/spec/api';
47+
import type { ApiChangelogEntry, ApiDocumentationConfig, ApiTestCollection, ApiTestRequest, CodeGenerationTemplate, GeneratedApiDocumentation, OpenApiSecurityScheme, OpenApiServer, OpenApiSpec } from '@objectstack/spec/api';
5048

5149
// Validate data
5250
const result = ApiChangelogEntrySchema.parse(data);
@@ -90,7 +88,7 @@ const result = ApiChangelogEntrySchema.parse(data);
9088
| **version** | `string` | ✅ | API version |
9189
| **description** | `string` | optional | API description |
9290
| **servers** | `{ url: string; description?: string; variables?: Record<string, object> }[]` | optional (default: `[]`) | API server URLs |
93-
| **ui** | `{ type: Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphiql' \| 'postman' \| 'custom'>; path?: string; theme?: Enum<'light' \| 'dark' \| 'auto'>; enableTryItOut?: boolean; … }` | optional | Testing UI configuration |
91+
| **ui** | `never` | optional | [REMOVED] `ApiDocumentationConfig.ui` was removed in @objectstack/spec 18.1.0 (ADR-0049 enforce-or-remove) — nothing ever read it: no viewer was ever mounted from it, and the platform serves no HTML API documentation viewer at all, only the machine-readable OpenAPI document. Delete the key. The OpenAPI document is served at `GET /api/v1/openapi.json` under the REST server's default `api.basePath` and `api.version` (the path follows both) while `api.enableOpenApi` is on; point any viewer or client generator you run yourself at that document. |
9492
| **generateOpenApi** | `boolean` | optional (default: `true`) | Generate OpenAPI 3.0 specification |
9593
| **generateTestCollections** | `boolean` | optional (default: `true`) | Generate API test collections |
9694
| **testCollections** | `{ name: string; description?: string; variables?: Record<string, any>; requests: object[]; … }[]` | optional (default: `[]`) | Predefined test collections |
@@ -111,23 +109,6 @@ const result = ApiChangelogEntrySchema.parse(data);
111109
| **description** | `string` | optional | Server description |
112110
| **variables** | `Record<string, { default: string; description?: string; enum?: string[] }>` | optional | URL template variables |
113111

114-
### Nested Shape: `ApiDocumentationConfig.ui`
115-
116-
| Property | Type | Required | Description |
117-
| :--- | :--- | :--- | :--- |
118-
| **type** | `Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphiql' \| 'postman' \| 'custom'>` | ✅ | Testing UI implementation |
119-
| **path** | `string` | optional (default: `"/api-docs"`) | URL path for documentation UI |
120-
| **theme** | `Enum<'light' \| 'dark' \| 'auto'>` | optional (default: `"light"`) | UI color theme |
121-
| **enableTryItOut** | `boolean` | optional (default: `true`) | Enable interactive API testing |
122-
| **enableFilter** | `boolean` | optional (default: `true`) | Enable endpoint filtering |
123-
| **enableCors** | `boolean` | optional (default: `true`) | Enable CORS for browser testing |
124-
| **defaultModelsExpandDepth** | `integer` | optional (default: `1`) | Default expand depth for schemas (-1 = fully expand) |
125-
| **displayRequestDuration** | `boolean` | optional (default: `true`) | Show request duration |
126-
| **syntaxHighlighting** | `boolean` | optional (default: `true`) | Enable syntax highlighting |
127-
| **customCssUrl** | `string` | optional | Custom CSS stylesheet URL |
128-
| **customJsUrl** | `string` | optional | Custom JavaScript URL |
129-
| **layout** | `{ showExtensions?: boolean; showCommonExtensions?: boolean; deepLinking?: boolean; displayOperationId?: boolean; … }` | optional | Layout configuration |
130-
131112
### Nested Shape: `ApiDocumentationConfig.testCollections[number]`
132113

133114
| Property | Type | Required | Description |
@@ -218,57 +199,6 @@ const result = ApiChangelogEntrySchema.parse(data);
218199
| **expectedResponse** | `{ statusCode: integer; body?: any }` | optional | Expected response for validation |
219200

220201

221-
---
222-
223-
## ApiTestingUiConfig
224-
225-
### Properties
226-
227-
| Property | Type | Required | Description |
228-
| :--- | :--- | :--- | :--- |
229-
| **type** | `Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphiql' \| 'postman' \| 'custom'>` | ✅ | Testing UI implementation |
230-
| **path** | `string` | optional (default: `"/api-docs"`) | URL path for documentation UI |
231-
| **theme** | `Enum<'light' \| 'dark' \| 'auto'>` | optional (default: `"light"`) | UI color theme |
232-
| **enableTryItOut** | `boolean` | optional (default: `true`) | Enable interactive API testing |
233-
| **enableFilter** | `boolean` | optional (default: `true`) | Enable endpoint filtering |
234-
| **enableCors** | `boolean` | optional (default: `true`) | Enable CORS for browser testing |
235-
| **defaultModelsExpandDepth** | `integer` | optional (default: `1`) | Default expand depth for schemas (-1 = fully expand) |
236-
| **displayRequestDuration** | `boolean` | optional (default: `true`) | Show request duration |
237-
| **syntaxHighlighting** | `boolean` | optional (default: `true`) | Enable syntax highlighting |
238-
| **customCssUrl** | `string` | optional | Custom CSS stylesheet URL |
239-
| **customJsUrl** | `string` | optional | Custom JavaScript URL |
240-
| **layout** | `{ showExtensions?: boolean; showCommonExtensions?: boolean; deepLinking?: boolean; displayOperationId?: boolean; … }` | optional | Layout configuration |
241-
242-
### Nested Shape: `ApiTestingUiConfig.layout`
243-
244-
| Property | Type | Required | Description |
245-
| :--- | :--- | :--- | :--- |
246-
| **showExtensions** | `boolean` | optional (default: `false`) | Show vendor extensions |
247-
| **showCommonExtensions** | `boolean` | optional (default: `false`) | Show common extensions |
248-
| **deepLinking** | `boolean` | optional (default: `true`) | Enable deep linking |
249-
| **displayOperationId** | `boolean` | optional (default: `false`) | Display operation IDs |
250-
| **defaultModelRendering** | `Enum<'example' \| 'model'>` | optional (default: `"example"`) | Default model rendering mode |
251-
| **defaultModelsExpandDepth** | `integer` | optional (default: `1`) | Models expand depth |
252-
| **defaultModelExpandDepth** | `integer` | optional (default: `1`) | Single model expand depth |
253-
| **docExpansion** | `Enum<'list' \| 'full' \| 'none'>` | optional (default: `"list"`) | Documentation expansion mode |
254-
255-
256-
---
257-
258-
## ApiTestingUiType
259-
260-
### Allowed Values
261-
262-
* `swagger-ui`
263-
* `redoc`
264-
* `rapidoc`
265-
* `stoplight`
266-
* `scalar`
267-
* `graphiql`
268-
* `postman`
269-
* `custom`
270-
271-
272202
---
273203

274204
## CodeGenerationTemplate

0 commit comments

Comments
 (0)