Keep the meaning beside the model
A field’s type tells a developer what it can hold. It does not explain why the field exists, what “urgent” means or how a record moves through the business.
Wildo gives that meaning a structured home beside the resource. Specifications describe the object’s purpose, its lifecycle and its fields, while referring to the actual model rather than a disconnected document.
People and development tools can use those explanations to understand the application. You author the meaning; the framework connects it to the thing being described.
Example — Make priority mean something useful
A task’s priority has a defined set of values. Its specification explains that “urgent” requires immediate action, while “high” needs attention soon. That distinction gives an assistant or a documentation generator more to work with than the enum names alone.
For engineers
Start from the actual factory and schema
resourceSpecification receives the resource factory and schema, then exposes their fields to the specification callback. The declaration describes purpose, business role, lifecycle and audience as separate facts.
Selected lines from Wonder Todos’ todos.resource.specification.ts show that binding and the beginning of its code metadata. The intervening source comment and later metadata fields are omitted; this is an excerpt of the specification object:
export const todosResourceSpecification = resourceSpecification(
todosFactory,
Todos_Schema,
({ schemaShape }) => ({
purpose: 'Represent a todo — a unit of work that a team wants to track, assign, and complete.',
businessRole: 'Primary actionable work item inside a todo list.',
lifecycleRole: 'Moves from planning to assignment to completion or cancellation.',
audience: LabelAudience.END_USER,
codeHandling: {
mainSchema: {
packageName: '@wonder-todos/shared-lib',
exportName: 'Todos_Schema',
symbolKind: CodeSymbolKind.SCHEMA,
declarationKind: CodeDeclarationKind.ZOD_SCHEMA,
},
resourceFactory: {
packageName: '@wonder-todos/shared-lib',
exportName: 'todos_ResourceConfiguration_InitializationFactory',
symbolKind: CodeSymbolKind.FACTORY,
declarationKind: CodeDeclarationKind.FUNCTION,
},
The purpose names the object as a todo as well as describing it. businessRole explains where it fits, and lifecycleRole describes its progression. Code metadata identifies the actual package and export a tool should resolve, instead of relying on a filename guessed from the prose.
Explain fields through their own schema identity
The same file describes priority through schemaShape.priority:
priority: schemaShape.priority.enumSpec({
meaning: 'Expresses urgency and ordering pressure among open todos.',
whyItMatters: 'It helps the application decide what should visually stand out or be treated first.',
enumDeclaration: {
packageName: '@wonder-todos/shared-lib',
exportName: 'Todos_Priority',
symbolKind: CodeSymbolKind.ENUM,
declarationKind: CodeDeclarationKind.TYPESCRIPT_ENUM,
},
values: {
[Todos_Priority.LOW]: { meaning: 'Can wait — no time pressure.' },
[Todos_Priority.MEDIUM]: { meaning: 'Normal urgency — should be handled in due course.' },
[Todos_Priority.HIGH]: { meaning: 'Needs attention soon — may block other work.' },
[Todos_Priority.URGENT]: { meaning: 'Immediate action required — top of the queue.' },
},
}),
meaning explains what priority represents and whyItMatters explains its use. The value descriptions distinguish the members of the named enum. This adds semantic information without creating another list of allowed field values.
Connect the explanation to its consumers
The specification supplies context for development tools, documentation and label generation. Its frontend section can describe the sections and views the interface actually declares. Structural checks compare that description with the frontend configuration so renamed or missing elements can be detected.
Keep presentation in UI behavior and field shape in the shared schema. When a field’s meaning or lifecycle changes, revise its specification as part of that change. The framework can check structural agreement; the author still supplies a clear and accurate account of the business.
Describe what an operation means to its caller
Fields explain the record. Operation semantics explain why to call it, what comes back, and which failures an integration should handle. This READ entry is from Wonder Todos’ specification; Op is its alias for CoreResourceOperation. It sits inside the specification’s operations object:
[Op.READ]: {
operationId: Op.READ,
purpose: 'Read one todo with every field, for a detail view or an integration that needs the full record. Also available to AI assistants through the read-only support MCP server.',
outcome: 'The full todo document is returned; a support agent driving the read-only MCP surface can look a work item up by id.',
whenToUse: 'Use to hydrate the todo detail screen, or from an agent that needs the current state of one known todo.',
responseStatuses: [
{ code: HttpResponseStatusCode.OK_200, meaning: 'The todo visible in the caller\'s organization is returned.' },
],
errorScenarios: [
{ code: HttpResponseStatusCode.FORBIDDEN_403, when: 'The caller does not hold the organization-member access required to read todos.' },
{ code: HttpResponseStatusCode.NOT_FOUND_404, when: 'No todo with this id is visible in the caller\'s organization.' },
],
idempotent: true,
},
purpose and whenToUse help a reader choose the operation; outcome explains its result. The OpenAPI generator turns responseStatuses[].meaning into response descriptions and errorScenarios[].when into error descriptions, using the operation’s actual response schema for the successful body. idempotent documents the operation’s semantics; it does not install retries or make an implementation idempotent.
A statement about permissions or not-found behavior is documentation of the configured operation. It does not create an access rule, a status handler or an MCP exposure. Keep those statements aligned with the resource configuration and implementation that enforce them.
Catch a stale interface description at its source
The backend operation and its frontend presentation are separate declarations. resourceSpecificationFromFrontendConfiguration checks the documented frontend semantics against the merged frontend configuration, including overlays.
For example, if the specification still documents the admin variant of change-status after that frontend variant has been removed, loading it throws this diagnostic:
resourceSpecificationFromFrontendConfiguration(): operation "change-status" documents variant "admin" that is not surfaced by the merged frontend configuration.
The identifiers here are illustrative. The check compares exact operation and variant keys; it does not infer that a newly named variant is equivalent to the old one.
| Structural change | What must agree |
|---|---|
| A field is added, renamed or changes meaning. | The schema-bound field specification and its explanation. |
| A relationship changes ownership or context. | The relationship description and the actual declared edge. |
| An operation changes its result or access contract. | Its operation semantics and the implementation’s behavior. |
| A documented frontend operation disappears. | Remove or correct the frontend semantics; the loader refuses the missing operation. |
| Its default variant disappears. | Remove or correct the documented default; a keyed variant does not substitute for it. |
| A keyed variant is renamed or removed. | Update the same key in the frontend semantics and merged configuration. |
Structural validation can identify a missing declared surface. It cannot prove that business prose is true. Review the meaning against source behavior, then regenerate the consuming documentation or labels when that meaning changes.