Ergon FieldSpec UI Contract
Use this skill to close the contract between migrated Java APIs and the Angular dynamic UI. It is a gate skill: it verifies that DTO/FilterDTO annotations, OpenAPI x-ui, resource endpoints, and Angular controls match before frontend work starts.
This skill is versioned from codex-skills/ergon-fieldspec-ui-contract. If the installed copy under $CODEX_HOME/skills diverges, update this canonical source first and then sync it to the local installation.
Core Rule
Do not assume a control is supported because it exists in one layer. A field contract is valid only when the backend emits the intended x-ui and the Angular library can normalize and render it.
Do not close this gate using only static code inspection. When endpoints already exist, execute the schema/options endpoints the frontend will call and record the actual metadata and response wrappers. Static OpenAPI assertions are useful, but they are not proof that Angular can consume the running backend.
For published examples, demos, and corporate-facing surfaces, validate both contract and presentation. A filter is not ready if it works technically but exposes implementation suffixes, ambiguous labels, missing tooltips, duplicate selected values, or labels that hide the business effect of the predicate.
Treat FieldSpec as a public Praxis semantic contract, not as a DTO decoration pass. Before adding fields, filters, actions, x-ui, option sources, or command DTOs, inventory what the platform already knows from legacy runtime evidence, XML, Oracle lineage, docs-legado, existing DTOs/services, /schemas/filtered, /schemas/domain, capabilities, actions, surfaces, and option-source descriptors. Classify each gap as ja-suportado-so-ux, ja-suportado-mal-nomeado-ou-mal-materializado, suportado-parcialmente, or lacuna-real-de-contrato; only the last category justifies a new public contract.
/schemas/filtered is the structural schema source for Angular runtime. /schemas/catalog, /schemas/domain, actions, surfaces, capabilities, HATEOAS, and /api/praxis/config/** are discovery, grounding, availability, or materialization surfaces. Do not publish Ergon-specific aliases, command words, routine flags, package state, or UI-only fields as semantic shortcuts when the correct fix is a canonical DTO, metadata starter, config starter, option-source, or Angular runtime contract.
When a field represents a real selectable business entity or relationship, prefer a governed RESOURCE_ENTITY option source over a local select endpoint or DTO-level extraProperties workaround. Use praxis-resource-entity-lookup-backend to validate x-ui.optionSource, dependencies, selected-value reload, public display metadata, and by-ids behavior.
When To Run
Run this skill:
- during Phase 2 when designing
filter, detail, by-ids, and options contracts;
- during Phase 3 when adding OpenAPI/schema/x-ui tests;
- during Phase 5 when creating command DTOs for create, update, delete, duplicate, legal documents, publications, or pending flows;
- during Phase 6 when implementation may change DTOs or inherited FieldSpec endpoints;
- during Phase 6.5 when Angular wiring consumes schemas, HATEOAS/actions, options, selected reload, filters, forms, or write metadata;
- before frontend handoff.
Required Inputs
- Screen operation inventory and API contract candidates.
- DTO, FilterDTO, command DTO, option DTO, controller, service, and OpenAPI paths.
- Legacy field evidence: label, component type, bind, null/default behavior, validation message, and business semantics.
- For Ergon domain documentation,
D:\Developer\Techne\ErgonX\migracao\docs-legado is the primary source of truth when available. Use it before writing or approving @Schema.description, @UISchema.helpText, filter semantics, option labels, command DTO text, governance notes, or AI-facing metadata.
- Target local code for
praxis-metadata-starter, praxis-ui-angular, and the application module.
Workflow
- Classify each field role: grid, detail, filter, form, options source, hidden/internal, action state, or related resource.
- Choose DTO and FilterDTO shape from behavior, not only database type.
- Add or review
@Schema, @UISchema, validation annotations, and @Filterable where applicable. Treat this as public product documentation, not only UI metadata: descriptions must explain the business role of each field, filter, option, command, and relationship using legacy evidence and docs-legado where available.
- Validate the backend contract:
FieldControlType contains the serialized value;
CustomOpenApiResolver / OpenApiUiUtils preserves it in x-ui;
- resource endpoints expose
filter, detail, by-ids, options/filter, options/by-ids, and schemas when needed;
/schemas/filtered can resolve response and request schemas for the exact resource path, operation, and schema type that Angular will request;
- enum arrays and collection fields expose options on the parent field
x-ui shape consumed by Angular, not only on an item schema that the normalizer cannot see;
- plain non-enum arrays do not receive empty or misleading
x-ui select metadata merely because they are arrays;
/schemas/flex?entity=... returns a non-error response when Angular dynamic forms or flexible-field metadata request it, or the absence of flexible fields is explicitly documented as a non-blocking residual, classified as accepted-gap with owner and next action;
- resource
filter endpoints follow their resource response contract, while generic options endpoints follow the current Praxis options contract consumed by GenericCrudService: bare Page<OptionDTO> for POST /options/filter and bare List<OptionDTO> for GET /options/by-ids;
- option-source endpoints follow the same no-envelope options convention: bare
Page<OptionDTO<Object>> for POST /option-sources/{sourceKey}/options/filter and bare List<OptionDTO<Object>> for GET /option-sources/{sourceKey}/options/by-ids or its contextual POST variant;
- dependent option sources prove selected-value reload separately from filtering:
GET .../by-ids is enough only when the public ID is self-contained, otherwise POST .../by-ids must carry the required public filter/dependency context through the current backend and Angular path;
- command DTOs hide derived/internal fields and use
copyOnDuplicate deliberately.
- when the API is implemented, execute the running endpoints that provide this contract and record payload/response evidence, not only generated OpenAPI.
- Validate the Angular contract:
FieldMetadata accepts the metadata;
schema-normalizer.service.ts propagates the x-ui keys;
praxis-dynamic-fields has a renderable component for the control; treat ComponentRegistryService.getRegisteredTypes() and direct inspection of the current component registry as the renderability source of truth, not the Java enum or TypeScript union;
- naming mismatches and aliases are resolved deliberately through the current Praxis selector/control-type mapping, not by inventing host-local aliases;
- field configurator support exists when authoring is required;
- list/select components can call the expected endpoints;
- selected-value reload uses an ID shape that the current Angular code will actually pass to
/options/by-ids, including explicit evidence for composite IDs or option-source contextual reload; if Angular cannot send required context yet, downgrade the handoff to a platform follow-up instead of declaring the source reusable.
- HATEOAS/action metadata or equivalent action state exposes only operations implemented with parity evidence; blocked/deferred operations must be omitted, hidden, disabled, or blocked deliberately.
- Verify service semantics:
- JPA filters may use
@Filterable;
- JPA FilterDTO aliases such as
statusIn, statusNotIn, periodoBetween, criadoEmOn, inicioPrevLastDays, and other operator-specific fields must declare relation when the DTO property name is not the entity/view attribute name;
- every
IN and NOT_IN filter with an alias-like property must be checked against the actual entity/view field, because otherwise the specification builder can target the DTO field name instead of the persistent attribute;
- legacy SQL/PLSQL services must translate each FilterDTO field manually to the proven legacy predicate;
- options endpoints must support filtering, paging, sorting, selected-value reload, and dependency filters.
- Add or update tests and artifacts:
- OpenAPI/schema assertions for
x-ui;
- controller/service tests for options and filter payloads;
- parity cases for each visible filter/control;
- reflective or schema contract tests that fail when
IN/NOT_IN filter aliases omit relation;
ui-contract-checklist.md or equivalent section in the screen docs. In this workspace, use docs/migracao/ui-contract-checklist-template.md when available.
Semantic Documentation And Future Consumers
For Ergon migrations, rich DTO/OpenAPI annotations are part of the platform contract. They feed not only Angular runtime rendering, but also OpenAPI, /schemas/filtered, /schemas/domain, catalogs, AI/RAG flows, authoring tools, and future praxis-config-starter consumers such as governed metadata, templates, registry/config surfaces, and AI-assisted configuration.
Apply these rules before closing the FieldSpec gate:
- Consult
D:\Developer\Techne\ErgonX\migracao\docs-legado and the local screen evidence before describing business fields, filters, commands, states, relationships, or option semantics.
- Write
@Schema.description property by property with the field's business meaning, operational impact, source of truth, relationships, constraints, and misuse risk when relevant. Do not derive descriptions from camelCase, database names, enum constants, or @UISchema.label.
- Use
@UISchema.label for short UI copy and helpText for operator-facing interpretation; do not let UI labels substitute for domain documentation.
- Record the legacy source used when the annotation changes sensitive business meaning, such as HR/employment data, payroll/financial behavior, legal documents, authorization, HADES/session scope, write side effects, or AI-visible metadata.
- If docs-legado is missing or inconclusive, say so in the migration artifact and limit the annotation to behavior proven by XML, runtime evidence, Oracle probes, services, and tests.
- Pair this skill with
praxis-dto-annotations whenever the work creates or changes DTO descriptions, governance, AI policy, @Operation, @ResourceIntent, @UiSurface, @WorkflowAction, or other metadata that will be consumed beyond Angular rendering.
Angular Host Handoff
Before handing a FieldSpec contract to Angular implementation, classify host/runtime fit with the same vocabulary used by praxis-angular-host-project: already-supported, supported-partially, platform-gap, or migration-skill-gap.
Apply native Praxis first for frontend consumption. Confirm the intended table, form, CRUD, surface, option, action, and capability behavior can be consumed through official Praxis components, services, outputs, adapters, tokens, and metadata-driven paths before accepting host-owned launchers, local schema projection, CSS selectors, manual related-resource tables, or local event bridges.
If the backend emits a technically valid schema but Angular needs local FormConfig, local labels, DOM selectors, or manual actions to achieve the target UX, do not silently approve the handoff as canonical. Either return to DTO/schema/platform contract hardening or record a traceable Praxis platform follow-up with the smallest temporary host bridge and its removal trigger.
For Angular host implementation details, use praxis-angular-host-project; keep this skill focused on proving that DTO, OpenAPI, options, schemas, and action metadata are renderable without frontend semantic compensation.
Handoff Evidence
Before declaring the contract frontend-ready, produce or update the screen's ui-contract-checklist.md with:
- field matrix: DTO/FilterDTO/command field, legacy evidence,
@Schema.description, @UISchema/x-ui, visibility, internal/public decision, and Angular control proof;
- filter matrix: operator,
@Filterable.relation, backend predicate, null/default behavior, label/help text, schema request path, and executed filter payload;
- option matrix: static options,
/options/*, or x-ui.optionSource; filter endpoint, by-ids endpoint, dependency context, selected reload proof, and Angular component evidence;
- action/command matrix: implemented, blocked, deferred, hidden, disabled, or 501, with parity evidence and write-risk dependency when applicable;
- renderability matrix: backend enum/resolver,
/schemas/filtered payload, FieldMetadata normalization, ComponentRegistryService registration or canonical alias, and authoring/configurator support when required.
A handoff can be Ready, Ready with accepted residual, Blocked, or Deferred. Do not use Ready while business descriptions are label-derived, option rehydration is unproven, specialized controls lack registry evidence, @Filterable aliases miss relation, or Angular would need host-owned semantic compensation.
Standard Mapping
| Legacy need |
New contract |
| Consultar/listar |
POST /<resource>/filter, FilterDTO, filterable=true, OpenAPI request/response schemas. |
| Ler detalhe |
GET /<resource>/{id}, stable public ID, hidden technical keys. |
| Schemas |
Global /schemas/filtered?path=...&operation=...&schemaType=... metadata resolution for list/detail/filter/options/write schemas consumed by Angular. |
| Options/lookups |
POST /<resource>/options/filter, GET /<resource>/options/by-ids, bare Page<OptionDTO>/List<OptionDTO> responses, OptionDTO(valueField, displayField), select @UISchema(endpoint, displayField, filterField, sortField, sortOrder, optionsPageSize). |
| Periodo |
Date array/list field, controlType = DATE_RANGE, ISO dates, service predicate matching legacy interval semantics. |
| Incluir/excluir valores |
Alias FilterDTO with IN/NOT_IN, relation pointing to the persistent field, business label such as "Mostrar status" or "Ocultar status", and tooltip explaining inclusion/exclusion. |
| Novo/Editar |
Command DTO or write DTO when read DTO has derived/internal fields; validation and schema request tests. |
| Apagar |
Delete endpoint only after write audit; no accidental inherited delete if operation is blocked. |
| Duplicar |
duplicate-draft, DuplicateDraftResourceService, DuplicateDraftUtils, deliberate copyOnDuplicate and unique annotations. |
| Cancelar |
Frontend no-op/reset; no backend mutation endpoint. |
| Documentos legais/Publicacoes/Pendencias |
Related resource contract unless evidence proves they belong to the same resource. |
Filter DTO Review
For FilterDTO classes, review both machine semantics and human-facing metadata.
- Treat operator suffixes (
In, NotIn, Between, On, Before, After, LastDays, Ids) as implementation details, not publication labels.
- Prefer labels that describe the user decision:
Mostrar status, Ocultar status, Periodo previsto, Criadas em, Ultimos dias, Responsaveis, or the domain equivalent backed by evidence.
- Use
helpText or tooltip metadata to explain the effect, especially for exclusion filters. Example: "Remove do resultado as missoes nos status selecionados."
- Avoid raw technical names such as
Ameacas ID, Fim Prev Between, Fim previsto na data (Excluir), or labels that mix operation and field mechanically.
- For
IN and NOT_IN, prove the selected values map to valid enum/option values and that invalid values fail as validation, not as a broken business predicate.
- For enum/list inline filters, execute the running schema endpoint and one browser interaction: open the dropdown, select one option, verify the selected chip/text appears once, and verify the paired include/exclude filters remain visually distinct.
- For corporate scenarios, validate labels and tooltips with the same standard as product documentation. They should tell a developer what the platform can express and tell an operator what the filter will do.
Hard Gates
- No DTO, FilterDTO, command DTO, option DTO, action, or surface handoff with empty, generic, label-derived, camelCase-derived, or purely technical
@Schema.description when the contract is public.
- No Ergon business annotation handoff without consulting
docs-legado where relevant and recording a source/evidence note for sensitive or domain-critical semantics.
- No select-like field without either small static
options or a real endpoint with /options/filter and /options/by-ids.
- No remote select without
filterField, sortField, sortOrder, and a deliberate optionsPageSize.
- No static
options handoff unless the option shape is compatible with the current Angular normalizer. Prefer [{ "valueField": "...", "displayField": "..." }] or [{ "key": "...", "value": "..." }]; do not assume backend enum output shaped as { "value": "...", "label": "..." } renders correctly without evidence.
- No enum array or list handoff when options exist only on the item schema and the parent property lacks the
x-ui.options shape Angular will render.
- No plain array field should be promoted to select-like
x-ui metadata without enum/options evidence.
- No schema assertion for remote selects that expects the final
x-ui.displayField to remain the business DTO field. The resolver normalizes select-like controls to OptionDTO (valueField/displayField); assert the business search/sort fields through filterField and sortField.
- No selected-value reload handoff for composite IDs unless the current Angular component has evidence that it calls
/options/by-ids or the contextual option-source by-ids endpoint for that ID shape. Do not use old BaseDynamicListComponent behavior as current evidence; inspect the active praxis-dynamic-fields component and GenericCrudService. A passing POST /option-sources/{sourceKey}/options/filter smoke does not prove reopen/edit hydration.
- No
/schemas handoff without proving the exact /schemas/filtered query Angular uses, including path, operation, and schemaType.
- No dynamic-form handoff when Angular requests
/schemas/flex?entity=... and that endpoint returns 500. Absence of flexible fields should return an empty successful result or be formally accepted as a non-blocking residual with owner and next action.
- No
rangeSlider or specialized control unless it is emitted in x-ui, accepted by FieldMetadata, and registered in the current ComponentRegistryService.
- No use of Java enum values or TypeScript
FieldMetadata union values as proof of renderability. Controls such as rangeSlider, currency, toggle, phone, arrayInput, autoComplete, multiColumnComboBox, and timePicker require explicit current Angular registry evidence, documented alias support, or a safer mapped control.
- No alias mismatch handoff without an approved platform mapping. Prefer correcting the canonical Praxis metadata/runtime contract over creating host-local control aliases.
- No
@Filterable(IN) or @Filterable(NOT_IN) alias without relation when the property name is not the real entity/view attribute. This includes paired fields such as statusIn and statusNotIn.
- No
@Filterable(BETWEEN) as proof of legacy SQL semantics; services must implement the actual predicate.
- No public demo or landing-page example should expose raw FilterDTO/operator labels when deliberate business labels and tooltips can be provided.
- No public
ROWID or routine flag in UI DTOs unless explicitly accepted and documented.
- No frontend handoff while OpenAPI/x-ui assertions are missing for controls that drive filters or forms.
- No frontend handoff while the running
/schemas/filtered, options, selected reload, or HATEOAS/action metadata was not executed and compared with the Angular consumption path.
References
For detailed local evidence and examples, read fieldspec-angular-contract.md.
1---2name: ergon-fieldspec-ui-contract3description: Validate and design Praxis metadata DTO, FilterDTO, option, OpenAPI x-ui, and Angular dynamic-field control contracts for Ergon/Archon migrations. Use when mapping @UISchema, @Filterable, schemas, filters, selects/options, date ranges, duplicate drafts, command DTOs, or when checking whether @praxisui Angular can render fields generated from Java annotations.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/ergon-fieldspec-ui-contract6---78# Ergon FieldSpec UI Contract910Use this skill to close the contract between migrated Java APIs and the Angular dynamic UI. It is a gate skill: it verifies that DTO/FilterDTO annotations, OpenAPI `x-ui`, resource endpoints, and Angular controls match before frontend work starts.1112This skill is versioned from `codex-skills/ergon-fieldspec-ui-contract`. If the installed copy under `$CODEX_HOME/skills` diverges, update this canonical source first and then sync it to the local installation.1314## Core Rule1516Do not assume a control is supported because it exists in one layer. A field contract is valid only when the backend emits the intended `x-ui` and the Angular library can normalize and render it.1718Do not close this gate using only static code inspection. When endpoints already exist, execute the schema/options endpoints the frontend will call and record the actual metadata and response wrappers. Static OpenAPI assertions are useful, but they are not proof that Angular can consume the running backend.1920For published examples, demos, and corporate-facing surfaces, validate both contract and presentation. A filter is not ready if it works technically but exposes implementation suffixes, ambiguous labels, missing tooltips, duplicate selected values, or labels that hide the business effect of the predicate.2122Treat FieldSpec as a public Praxis semantic contract, not as a DTO decoration pass. Before adding fields, filters, actions, `x-ui`, option sources, or command DTOs, inventory what the platform already knows from legacy runtime evidence, XML, Oracle lineage, `docs-legado`, existing DTOs/services, `/schemas/filtered`, `/schemas/domain`, capabilities, actions, surfaces, and option-source descriptors. Classify each gap as `ja-suportado-so-ux`, `ja-suportado-mal-nomeado-ou-mal-materializado`, `suportado-parcialmente`, or `lacuna-real-de-contrato`; only the last category justifies a new public contract.2324`/schemas/filtered` is the structural schema source for Angular runtime. `/schemas/catalog`, `/schemas/domain`, actions, surfaces, capabilities, HATEOAS, and `/api/praxis/config/**` are discovery, grounding, availability, or materialization surfaces. Do not publish Ergon-specific aliases, command words, routine flags, package state, or UI-only fields as semantic shortcuts when the correct fix is a canonical DTO, metadata starter, config starter, option-source, or Angular runtime contract.2526When a field represents a real selectable business entity or relationship, prefer a governed `RESOURCE_ENTITY` option source over a local select endpoint or DTO-level `extraProperties` workaround. Use `praxis-resource-entity-lookup-backend` to validate `x-ui.optionSource`, dependencies, selected-value reload, public display metadata, and by-ids behavior.2728## When To Run2930Run this skill:3132- during Phase 2 when designing `filter`, detail, `by-ids`, and options contracts;33- during Phase 3 when adding OpenAPI/schema/x-ui tests;34- during Phase 5 when creating command DTOs for create, update, delete, duplicate, legal documents, publications, or pending flows;35- during Phase 6 when implementation may change DTOs or inherited FieldSpec endpoints;36- during Phase 6.5 when Angular wiring consumes schemas, HATEOAS/actions, options, selected reload, filters, forms, or write metadata;37- before frontend handoff.3839## Required Inputs4041- Screen operation inventory and API contract candidates.42- DTO, FilterDTO, command DTO, option DTO, controller, service, and OpenAPI paths.43- Legacy field evidence: label, component type, bind, null/default behavior, validation message, and business semantics.44- For Ergon domain documentation, `D:\Developer\Techne\ErgonX\migracao\docs-legado` is the primary source of truth when available. Use it before writing or approving `@Schema.description`, `@UISchema.helpText`, filter semantics, option labels, command DTO text, governance notes, or AI-facing metadata.45- Target local code for `praxis-metadata-starter`, `praxis-ui-angular`, and the application module.4647## Workflow48491. Classify each field role: grid, detail, filter, form, options source, hidden/internal, action state, or related resource.502. Choose DTO and FilterDTO shape from behavior, not only database type.513. Add or review `@Schema`, `@UISchema`, validation annotations, and `@Filterable` where applicable. Treat this as public product documentation, not only UI metadata: descriptions must explain the business role of each field, filter, option, command, and relationship using legacy evidence and docs-legado where available.524. Validate the backend contract:53 - `FieldControlType` contains the serialized value;54 - `CustomOpenApiResolver` / `OpenApiUiUtils` preserves it in `x-ui`;55 - resource endpoints expose `filter`, detail, `by-ids`, `options/filter`, `options/by-ids`, and schemas when needed;56 - `/schemas/filtered` can resolve response and request schemas for the exact resource path, operation, and schema type that Angular will request;57 - enum arrays and collection fields expose options on the parent field `x-ui` shape consumed by Angular, not only on an item schema that the normalizer cannot see;58 - plain non-enum arrays do not receive empty or misleading `x-ui` select metadata merely because they are arrays;59 - `/schemas/flex?entity=...` returns a non-error response when Angular dynamic forms or flexible-field metadata request it, or the absence of flexible fields is explicitly documented as a non-blocking residual, classified as accepted-gap with owner and next action;60 - resource `filter` endpoints follow their resource response contract, while generic options endpoints follow the current Praxis options contract consumed by `GenericCrudService`: bare `Page<OptionDTO>` for `POST /options/filter` and bare `List<OptionDTO>` for `GET /options/by-ids`;61 - option-source endpoints follow the same no-envelope options convention: bare `Page<OptionDTO<Object>>` for `POST /option-sources/{sourceKey}/options/filter` and bare `List<OptionDTO<Object>>` for `GET /option-sources/{sourceKey}/options/by-ids` or its contextual POST variant;62 - dependent option sources prove selected-value reload separately from filtering: `GET .../by-ids` is enough only when the public ID is self-contained, otherwise `POST .../by-ids` must carry the required public filter/dependency context through the current backend and Angular path;63 - command DTOs hide derived/internal fields and use `copyOnDuplicate` deliberately.64 - when the API is implemented, execute the running endpoints that provide this contract and record payload/response evidence, not only generated OpenAPI.655. Validate the Angular contract:66 - `FieldMetadata` accepts the metadata;67 - `schema-normalizer.service.ts` propagates the `x-ui` keys;68 - `praxis-dynamic-fields` has a renderable component for the control; treat `ComponentRegistryService.getRegisteredTypes()` and direct inspection of the current component registry as the renderability source of truth, not the Java enum or TypeScript union;69 - naming mismatches and aliases are resolved deliberately through the current Praxis selector/control-type mapping, not by inventing host-local aliases;70 - field configurator support exists when authoring is required;71 - list/select components can call the expected endpoints;72 - selected-value reload uses an ID shape that the current Angular code will actually pass to `/options/by-ids`, including explicit evidence for composite IDs or option-source contextual reload; if Angular cannot send required context yet, downgrade the handoff to a platform follow-up instead of declaring the source reusable.73 - HATEOAS/action metadata or equivalent action state exposes only operations implemented with parity evidence; blocked/deferred operations must be omitted, hidden, disabled, or blocked deliberately.746. Verify service semantics:75 - JPA filters may use `@Filterable`;76 - JPA FilterDTO aliases such as `statusIn`, `statusNotIn`, `periodoBetween`, `criadoEmOn`, `inicioPrevLastDays`, and other operator-specific fields must declare `relation` when the DTO property name is not the entity/view attribute name;77 - every `IN` and `NOT_IN` filter with an alias-like property must be checked against the actual entity/view field, because otherwise the specification builder can target the DTO field name instead of the persistent attribute;78 - legacy SQL/PLSQL services must translate each FilterDTO field manually to the proven legacy predicate;79 - options endpoints must support filtering, paging, sorting, selected-value reload, and dependency filters.807. Add or update tests and artifacts:81 - OpenAPI/schema assertions for `x-ui`;82 - controller/service tests for options and filter payloads;83 - parity cases for each visible filter/control;84 - reflective or schema contract tests that fail when `IN`/`NOT_IN` filter aliases omit `relation`;85 - `ui-contract-checklist.md` or equivalent section in the screen docs. In this workspace, use `docs/migracao/ui-contract-checklist-template.md` when available.8687## Semantic Documentation And Future Consumers8889For Ergon migrations, rich DTO/OpenAPI annotations are part of the platform contract. They feed not only Angular runtime rendering, but also OpenAPI, `/schemas/filtered`, `/schemas/domain`, catalogs, AI/RAG flows, authoring tools, and future `praxis-config-starter` consumers such as governed metadata, templates, registry/config surfaces, and AI-assisted configuration.9091Apply these rules before closing the FieldSpec gate:9293- Consult `D:\Developer\Techne\ErgonX\migracao\docs-legado` and the local screen evidence before describing business fields, filters, commands, states, relationships, or option semantics.94- Write `@Schema.description` property by property with the field's business meaning, operational impact, source of truth, relationships, constraints, and misuse risk when relevant. Do not derive descriptions from camelCase, database names, enum constants, or `@UISchema.label`.95- Use `@UISchema.label` for short UI copy and `helpText` for operator-facing interpretation; do not let UI labels substitute for domain documentation.96- Record the legacy source used when the annotation changes sensitive business meaning, such as HR/employment data, payroll/financial behavior, legal documents, authorization, HADES/session scope, write side effects, or AI-visible metadata.97- If docs-legado is missing or inconclusive, say so in the migration artifact and limit the annotation to behavior proven by XML, runtime evidence, Oracle probes, services, and tests.98- Pair this skill with `praxis-dto-annotations` whenever the work creates or changes DTO descriptions, governance, AI policy, `@Operation`, `@ResourceIntent`, `@UiSurface`, `@WorkflowAction`, or other metadata that will be consumed beyond Angular rendering.99100## Angular Host Handoff101102Before handing a FieldSpec contract to Angular implementation, classify host/runtime fit with the same vocabulary used by `praxis-angular-host-project`: `already-supported`, `supported-partially`, `platform-gap`, or `migration-skill-gap`.103104Apply native Praxis first for frontend consumption. Confirm the intended table, form, CRUD, surface, option, action, and capability behavior can be consumed through official Praxis components, services, outputs, adapters, tokens, and metadata-driven paths before accepting host-owned launchers, local schema projection, CSS selectors, manual related-resource tables, or local event bridges.105106If the backend emits a technically valid schema but Angular needs local `FormConfig`, local labels, DOM selectors, or manual actions to achieve the target UX, do not silently approve the handoff as canonical. Either return to DTO/schema/platform contract hardening or record a traceable Praxis platform follow-up with the smallest temporary host bridge and its removal trigger.107108For Angular host implementation details, use `praxis-angular-host-project`; keep this skill focused on proving that DTO, OpenAPI, options, schemas, and action metadata are renderable without frontend semantic compensation.109110## Handoff Evidence111112Before declaring the contract frontend-ready, produce or update the screen's `ui-contract-checklist.md` with:113114- field matrix: DTO/FilterDTO/command field, legacy evidence, `@Schema.description`, `@UISchema`/`x-ui`, visibility, internal/public decision, and Angular control proof;115- filter matrix: operator, `@Filterable.relation`, backend predicate, null/default behavior, label/help text, schema request path, and executed filter payload;116- option matrix: static options, `/options/*`, or `x-ui.optionSource`; filter endpoint, by-ids endpoint, dependency context, selected reload proof, and Angular component evidence;117- action/command matrix: implemented, blocked, deferred, hidden, disabled, or 501, with parity evidence and write-risk dependency when applicable;118- renderability matrix: backend enum/resolver, `/schemas/filtered` payload, `FieldMetadata` normalization, `ComponentRegistryService` registration or canonical alias, and authoring/configurator support when required.119120A handoff can be `Ready`, `Ready with accepted residual`, `Blocked`, or `Deferred`. Do not use `Ready` while business descriptions are label-derived, option rehydration is unproven, specialized controls lack registry evidence, `@Filterable` aliases miss `relation`, or Angular would need host-owned semantic compensation.121122## Standard Mapping123124| Legacy need | New contract |125| --- | --- |126| Consultar/listar | `POST /<resource>/filter`, FilterDTO, `filterable=true`, OpenAPI request/response schemas. |127| Ler detalhe | `GET /<resource>/{id}`, stable public ID, hidden technical keys. |128| Schemas | Global `/schemas/filtered?path=...&operation=...&schemaType=...` metadata resolution for list/detail/filter/options/write schemas consumed by Angular. |129| Options/lookups | `POST /<resource>/options/filter`, `GET /<resource>/options/by-ids`, bare `Page<OptionDTO>`/`List<OptionDTO>` responses, `OptionDTO(valueField, displayField)`, select `@UISchema(endpoint, displayField, filterField, sortField, sortOrder, optionsPageSize)`. |130| Periodo | Date array/list field, `controlType = DATE_RANGE`, ISO dates, service predicate matching legacy interval semantics. |131| Incluir/excluir valores | Alias FilterDTO with `IN`/`NOT_IN`, `relation` pointing to the persistent field, business label such as "Mostrar status" or "Ocultar status", and tooltip explaining inclusion/exclusion. |132| Novo/Editar | Command DTO or write DTO when read DTO has derived/internal fields; validation and schema request tests. |133| Apagar | Delete endpoint only after write audit; no accidental inherited delete if operation is blocked. |134| Duplicar | `duplicate-draft`, `DuplicateDraftResourceService`, `DuplicateDraftUtils`, deliberate `copyOnDuplicate` and `unique` annotations. |135| Cancelar | Frontend no-op/reset; no backend mutation endpoint. |136| Documentos legais/Publicacoes/Pendencias | Related resource contract unless evidence proves they belong to the same resource. |137138## Filter DTO Review139140For `FilterDTO` classes, review both machine semantics and human-facing metadata.141142- Treat operator suffixes (`In`, `NotIn`, `Between`, `On`, `Before`, `After`, `LastDays`, `Ids`) as implementation details, not publication labels.143- Prefer labels that describe the user decision: `Mostrar status`, `Ocultar status`, `Periodo previsto`, `Criadas em`, `Ultimos dias`, `Responsaveis`, or the domain equivalent backed by evidence.144- Use `helpText` or tooltip metadata to explain the effect, especially for exclusion filters. Example: "Remove do resultado as missoes nos status selecionados."145- Avoid raw technical names such as `Ameacas ID`, `Fim Prev Between`, `Fim previsto na data (Excluir)`, or labels that mix operation and field mechanically.146- For `IN` and `NOT_IN`, prove the selected values map to valid enum/option values and that invalid values fail as validation, not as a broken business predicate.147- For enum/list inline filters, execute the running schema endpoint and one browser interaction: open the dropdown, select one option, verify the selected chip/text appears once, and verify the paired include/exclude filters remain visually distinct.148- For corporate scenarios, validate labels and tooltips with the same standard as product documentation. They should tell a developer what the platform can express and tell an operator what the filter will do.149150## Hard Gates151152- No DTO, FilterDTO, command DTO, option DTO, action, or surface handoff with empty, generic, label-derived, camelCase-derived, or purely technical `@Schema.description` when the contract is public.153- No Ergon business annotation handoff without consulting `docs-legado` where relevant and recording a source/evidence note for sensitive or domain-critical semantics.154- No select-like field without either small static `options` or a real `endpoint` with `/options/filter` and `/options/by-ids`.155- No remote select without `filterField`, `sortField`, `sortOrder`, and a deliberate `optionsPageSize`.156- No static `options` handoff unless the option shape is compatible with the current Angular normalizer. Prefer `[{ "valueField": "...", "displayField": "..." }]` or `[{ "key": "...", "value": "..." }]`; do not assume backend enum output shaped as `{ "value": "...", "label": "..." }` renders correctly without evidence.157- No enum array or list handoff when options exist only on the item schema and the parent property lacks the `x-ui.options` shape Angular will render.158- No plain array field should be promoted to select-like `x-ui` metadata without enum/options evidence.159- No schema assertion for remote selects that expects the final `x-ui.displayField` to remain the business DTO field. The resolver normalizes select-like controls to `OptionDTO` (`valueField`/`displayField`); assert the business search/sort fields through `filterField` and `sortField`.160- No selected-value reload handoff for composite IDs unless the current Angular component has evidence that it calls `/options/by-ids` or the contextual option-source by-ids endpoint for that ID shape. Do not use old `BaseDynamicListComponent` behavior as current evidence; inspect the active `praxis-dynamic-fields` component and `GenericCrudService`. A passing `POST /option-sources/{sourceKey}/options/filter` smoke does not prove reopen/edit hydration.161- No `/schemas` handoff without proving the exact `/schemas/filtered` query Angular uses, including `path`, `operation`, and `schemaType`.162- No dynamic-form handoff when Angular requests `/schemas/flex?entity=...` and that endpoint returns `500`. Absence of flexible fields should return an empty successful result or be formally accepted as a non-blocking residual with owner and next action.163- No `rangeSlider` or specialized control unless it is emitted in `x-ui`, accepted by `FieldMetadata`, and registered in the current `ComponentRegistryService`.164- No use of Java enum values or TypeScript `FieldMetadata` union values as proof of renderability. Controls such as `rangeSlider`, `currency`, `toggle`, `phone`, `arrayInput`, `autoComplete`, `multiColumnComboBox`, and `timePicker` require explicit current Angular registry evidence, documented alias support, or a safer mapped control.165- No alias mismatch handoff without an approved platform mapping. Prefer correcting the canonical Praxis metadata/runtime contract over creating host-local control aliases.166- No `@Filterable(IN)` or `@Filterable(NOT_IN)` alias without `relation` when the property name is not the real entity/view attribute. This includes paired fields such as `statusIn` and `statusNotIn`.167- No `@Filterable(BETWEEN)` as proof of legacy SQL semantics; services must implement the actual predicate.168- No public demo or landing-page example should expose raw FilterDTO/operator labels when deliberate business labels and tooltips can be provided.169- No public `ROWID` or routine flag in UI DTOs unless explicitly accepted and documented.170- No frontend handoff while OpenAPI/x-ui assertions are missing for controls that drive filters or forms.171- No frontend handoff while the running `/schemas/filtered`, options, selected reload, or HATEOAS/action metadata was not executed and compared with the Angular consumption path.172173## References174175For detailed local evidence and examples, read [fieldspec-angular-contract.md](references/fieldspec-angular-contract.md).