Praxis Metadata Resource Baseline
Use this skill for the resource-oriented backend hierarchy owned by praxis-metadata-starter.
Operating Mode & Source Audit
Determine whether you are operating in Platform Source Mode or Consumer Host Mode:
- Platform Source Mode (
praxis-metadata-starter checkout present in the workspace):
Inspect the starter before editing:
praxis-metadata-starter/AGENTS.md
praxis-metadata-starter/README.md
src/main/java/org/praxisplatform/uischema/annotation/ApiResource.java
src/main/java/org/praxisplatform/uischema/annotation/ApiGroup.java
src/main/java/org/praxisplatform/uischema/controller/base/AbstractResourceQueryController.java
src/main/java/org/praxisplatform/uischema/controller/base/AbstractReadOnlyResourceController.java
src/main/java/org/praxisplatform/uischema/controller/base/AbstractCreateUpdateResourceController.java
src/main/java/org/praxisplatform/uischema/controller/base/AbstractCollectionCommandResourceController.java
src/main/java/org/praxisplatform/uischema/controller/base/AbstractResourceController.java
src/main/java/org/praxisplatform/uischema/service/base/AbstractBaseQueryResourceService.java
src/main/java/org/praxisplatform/uischema/service/base/AbstractReadOnlyResourceService.java
src/main/java/org/praxisplatform/uischema/service/base/AbstractBaseResourceService.java
src/main/java/org/praxisplatform/uischema/mapper/base/ResourceMapper.java
src/main/java/org/praxisplatform/uischema/rest/response/RestApiResponse.java
- Consumer Host / Published Dependency Mode (
io.github.codexrodrigues:praxis-metadata-starter consumed via Maven):
Do not search for src/main/java/org/praxisplatform/uischema/** on disk. Pair with praxis-java-resource-authoring and praxis-java-host-project, inspect the host's pom.xml, controllers, services, mappers, DTOs, and resolved starter classes on the classpath (or via javap when needed), and validate through the host's focused tests and HTTP endpoints.
Canonical Boundary
praxis-metadata-starter owns the canonical resource baseline:
@ApiResource(value = "...", resourceKey = "...", title = "...", description = "...", icon = "...", identity = @ResourceIdentity(...), quickFilters = {...})
BaseCrudRepository<E, ID>
ResourceMapper<E, ResponseDTO, CreateDTO, UpdateDTO, ID> (applyUpdate(E entity, UpdateDTO dto))
AbstractBaseResourceService<E, ResponseDTO, ID, FilterDTO, CreateDTO, UpdateDTO>
AbstractReadOnlyResourceService<E, ResponseDTO, ID, FilterDTO>
AbstractResourceController<ResponseDTO, ID, FilterDTO, CreateDTO, UpdateDTO>
AbstractReadOnlyResourceController<ResponseDTO, ID, FilterDTO>
AbstractCollectionCommandResourceController
RestApiResponse<T> with HATEOAS _links and metadata headers
AbstractCrudController, AbstractReadOnlyController, BaseCrudService, AbstractBaseCrudService, and legacy mapper patterns are migration surfaces only. Do not start new resources on legacy hierarchies unless the task is explicitly maintaining a legacy test or compatibility boundary.
Decision Rules
- Choose
AbstractReadOnlyResourceController and AbstractReadOnlyResourceService for query/read-only resources, projections, views, and analytical datasets.
- Choose
AbstractResourceController and AbstractBaseResourceService for mutable resources with separate ResponseDTO, CreateDTO, UpdateDTO, and FilterDTO.
- Choose
AbstractCreateUpdateResourceController or AbstractUnitDeleteResourceController only when the resource intentionally omits full delete or batch delete semantics.
- Choose
AbstractCollectionCommandResourceController when an @ApiResource exposes only collection-level @WorkflowAction commands and has no query, read-by-id, options, stats, export, or CRUD service. Do not invent an in-memory query service or placeholder CRUD endpoints just to register /actions and /capabilities.
- Keep
resourceKey stable, semantic, and aligned with controller path, surfaces, actions, capabilities, and domain catalog entries.
- Preserve
RestApiResponse, _links, X-Data-Version, ETag, and schema link generation from the base controllers. Do not wrap responses in a host-local envelope.
- Preserve
ResourceMapper as the entity/DTO boundary. Do not leak JPA entities into public responses or OpenAPI schemas.
ResourceMapper.applyUpdate must update the managed entity loaded by the route without overwriting its route-owned technical identity from a missing or divergent payload id. Do not compensate for mapper identity bugs in the controller or in Angular.
- Native Composite Primary Keys (
@EmbeddedId / CompositeResourceId) and @Embedded value objects: praxis-metadata-starter supports @EmbeddedId composite keys (e.g., @Embeddable public record VinculoId(Long numfunc, Integer numvinc) implements CompositeResourceId {}) as the ID type parameter of BaseCrudRepository<E, ID>, ResourceMapper<..., ID>, AbstractBaseResourceService<..., ID, ...>, and AbstractResourceController<..., ID, ...>. On the HTTP/JSON/OpenAPI wire, composite IDs are serialized and deserialized as canonical colon-delimited strings ("1001:1", with %3A/%25 escaping for colons/percents) across @PathVariable, @RequestParam (ids, includeIds), OptionDTO<ID>, RESOURCE_ENTITY option sources, @Filterable(relation = "id.numfunc") / @Filterable(relation = "vinculo.id"), stats (JpaStatsQueryExecutor), HATEOAS _links, ETag, and BulkIdentityCodecs.composite(VinculoId.class). Use @EmbeddedId for immutable natural/composite domain keys (such as VINCULOS (numfunc, numvinc) or DEPENDENTES (numfunc, numdep)), and use a surrogate id BIGINT + UNIQUE business constraint for mutable event tables where the user can edit the date or event code in PUT /{id} (since JPA forbids mutating @EmbeddedId fields on a managed instance).
- Keep ordinary CRUD in the resource baseline; model non-CRUD business transitions with
@WorkflowAction and composed UI journeys with @UiSurface.
- Before persisting a resource write, verify that the persistence context is clean and bound so a mapper lookup or repository query cannot autoflush caller-owned entity mutations ahead of governance or validation.
- Keep controller/base, service/base, mapper, response envelope, and tests aligned in the same change.
- All resource stats endpoints (
groupByStats, timeSeriesStats, distributionStats, comparisonStats) in AbstractBaseQueryResourceService must resolve their base specification via resolveResourceFilterQuery(request.filter(), Pageable.unpaged()).effectiveSpecification() so row-level access scope (resolveResourceFilterAccessScope()) is enforced identically to filter().
- Multidimensional
group-by (dimensions[] with StatsDimensionExtraction, finite-domain fillGaps, and AVG_PER_CYCLE_OCCURRENCE) belongs to the canonical POST /{resource}/stats/group-by contract (GroupByStatsRequest / GroupByStatsResponse); do not create bespoke heatmap or cross-tab endpoints per resource.
- Treat legacy classes as migration surfaces unless the local AGENTS says otherwise.
No Keyword Routing
Do not infer resource operations, CRUD mode, capabilities, or workflow intent from controller names, method words, labels, or route regexes. Resolve behavior from @ApiResource, controller hierarchy, OpenAPI operations, @UiSurface, @WorkflowAction, and capability snapshots.
Adherence Inventory
Before adding a new base controller method, response field, filter endpoint, export mode, or stats hook, classify the need:
ja-suportado-so-ux
ja-suportado-mal-nomeado-ou-mal-materializado
suportado-parcialmente
lacuna-real-de-contrato
Only lacuna-real-de-contrato justifies a new public baseline contract.
Validation
- In Platform Source Mode (
praxis-metadata-starter):
- resource CRUD/query/hypermedia:
mvn "-Dtest=AbstractResourceControllerMappedCrudTest,ResourceControllerStatsAndLocateTest,HypermediaDiscoveryE2ETest,HateoasAndPayloadSizeE2ETest" test
- filters/pagination:
mvn "-Dtest=GenericSpecificationsBuilderTest,FilterRequestBodyAdviceTest,PageableBuilderTest" test
- export:
mvn "-Dtest=CollectionExportControllerTest,AbstractBaseQueryResourceServiceCollectionExportTest,CollectionExportExecutorTest" test
- downstream proof when public contracts change:
QuickstartMetadataMigrationIntegrationTest or EventosFolhaPilotIntegrationTest in praxis-api-quickstart.
- In Consumer Host Mode:
- run the host's focused resource controller/service/MockMvc tests verifying
/filter, CRUD/actions, RestApiResponse._links, /schemas/filtered, and /capabilities.
For public baseline changes, review README, guides, quickstart docs/examples, Angular GenericCrudService, and HTTP examples. Keep the opening and quickstart sections of README.md focused on onboarding and canonical architecture; record incremental RC/candidate checkpoints in docs/technical/BULK-AND-RELEASE-CANDIDATES-STATUS.md or dedicated technical docs. State explicitly when no derived artifact is affected.
Companion Skills
(In external Antigravity workspaces, full companion skills are available under ~/.gemini/praxis-skills/<skill-name>/SKILL.md or $CODEX_HOME/skills/<skill-name>/SKILL.md.)
- Use
praxis-java-resource-authoring and praxis-java-host-project when implementing or scaffolding resources in a Java host.
- Use
praxis-metadata-schema-contracts for /schemas/filtered, x-ui, ETag, and X-Schema-Hash.
- Use
praxis-metadata-discovery-capabilities for @UiSurface, @WorkflowAction, /schemas/surfaces, /schemas/actions, and /capabilities.
- Use
praxis-metadata-domain-option-sources and praxis-dto-annotations for DTO, filter, governance, and option-source contracts.
- Use
praxis-core-resource-runtime when verifying Angular GenericCrudService consumption.
1---2name: praxis-metadata-resource-baseline3description: "Use when working on praxis-metadata-starter resource-oriented backend patterns (either inside the starter or in a consuming Java host): AbstractResourceController, AbstractReadOnlyResourceController, AbstractCollectionCommandResourceController, AbstractResourceQueryController, AbstractBaseResourceService, AbstractReadOnlyResourceService, ResourceMapper, RestApiResponse, HATEOAS links, filters, stats, export, or canonical resource CRUD hierarchy."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-metadata-resource-baseline6---78# Praxis Metadata Resource Baseline910Use this skill for the resource-oriented backend hierarchy owned by `praxis-metadata-starter`.1112## Operating Mode & Source Audit1314Determine whether you are operating in **Platform Source Mode** or **Consumer Host Mode**:1516- **Platform Source Mode (`praxis-metadata-starter` checkout present in the workspace):**17 Inspect the starter before editing:18 - `praxis-metadata-starter/AGENTS.md`19 - `praxis-metadata-starter/README.md`20 - `src/main/java/org/praxisplatform/uischema/annotation/ApiResource.java`21 - `src/main/java/org/praxisplatform/uischema/annotation/ApiGroup.java`22 - `src/main/java/org/praxisplatform/uischema/controller/base/AbstractResourceQueryController.java`23 - `src/main/java/org/praxisplatform/uischema/controller/base/AbstractReadOnlyResourceController.java`24 - `src/main/java/org/praxisplatform/uischema/controller/base/AbstractCreateUpdateResourceController.java`25 - `src/main/java/org/praxisplatform/uischema/controller/base/AbstractCollectionCommandResourceController.java`26 - `src/main/java/org/praxisplatform/uischema/controller/base/AbstractResourceController.java`27 - `src/main/java/org/praxisplatform/uischema/service/base/AbstractBaseQueryResourceService.java`28 - `src/main/java/org/praxisplatform/uischema/service/base/AbstractReadOnlyResourceService.java`29 - `src/main/java/org/praxisplatform/uischema/service/base/AbstractBaseResourceService.java`30 - `src/main/java/org/praxisplatform/uischema/mapper/base/ResourceMapper.java`31 - `src/main/java/org/praxisplatform/uischema/rest/response/RestApiResponse.java`32- **Consumer Host / Published Dependency Mode (`io.github.codexrodrigues:praxis-metadata-starter` consumed via Maven):**33 Do not search for `src/main/java/org/praxisplatform/uischema/**` on disk. Pair with `praxis-java-resource-authoring` and `praxis-java-host-project`, inspect the host's `pom.xml`, controllers, services, mappers, DTOs, and resolved starter classes on the classpath (or via `javap` when needed), and validate through the host's focused tests and HTTP endpoints.3435## Canonical Boundary3637`praxis-metadata-starter` owns the canonical resource baseline:3839```text40@ApiResource(value = "...", resourceKey = "...", title = "...", description = "...", icon = "...", identity = @ResourceIdentity(...), quickFilters = {...})41BaseCrudRepository<E, ID>42ResourceMapper<E, ResponseDTO, CreateDTO, UpdateDTO, ID> (applyUpdate(E entity, UpdateDTO dto))43AbstractBaseResourceService<E, ResponseDTO, ID, FilterDTO, CreateDTO, UpdateDTO>44AbstractReadOnlyResourceService<E, ResponseDTO, ID, FilterDTO>45AbstractResourceController<ResponseDTO, ID, FilterDTO, CreateDTO, UpdateDTO>46AbstractReadOnlyResourceController<ResponseDTO, ID, FilterDTO>47AbstractCollectionCommandResourceController48RestApiResponse<T> with HATEOAS _links and metadata headers49```5051`AbstractCrudController`, `AbstractReadOnlyController`, `BaseCrudService`, `AbstractBaseCrudService`, and legacy mapper patterns are migration surfaces only. Do not start new resources on legacy hierarchies unless the task is explicitly maintaining a legacy test or compatibility boundary.5253## Decision Rules5455- Choose `AbstractReadOnlyResourceController` and `AbstractReadOnlyResourceService` for query/read-only resources, projections, views, and analytical datasets.56- Choose `AbstractResourceController` and `AbstractBaseResourceService` for mutable resources with separate `ResponseDTO`, `CreateDTO`, `UpdateDTO`, and `FilterDTO`.57- Choose `AbstractCreateUpdateResourceController` or `AbstractUnitDeleteResourceController` only when the resource intentionally omits full delete or batch delete semantics.58- Choose `AbstractCollectionCommandResourceController` when an `@ApiResource` exposes only collection-level `@WorkflowAction` commands and has no query, read-by-id, options, stats, export, or CRUD service. Do not invent an in-memory query service or placeholder CRUD endpoints just to register `/actions` and `/capabilities`.59- Keep `resourceKey` stable, semantic, and aligned with controller path, surfaces, actions, capabilities, and domain catalog entries.60- Preserve `RestApiResponse`, `_links`, `X-Data-Version`, ETag, and schema link generation from the base controllers. Do not wrap responses in a host-local envelope.61- Preserve `ResourceMapper` as the entity/DTO boundary. Do not leak JPA entities into public responses or OpenAPI schemas.62- `ResourceMapper.applyUpdate` must update the managed entity loaded by the route without overwriting its route-owned technical identity from a missing or divergent payload id. Do not compensate for mapper identity bugs in the controller or in Angular.63- **Native Composite Primary Keys (`@EmbeddedId` / `CompositeResourceId`) and `@Embedded` value objects:** `praxis-metadata-starter` supports `@EmbeddedId` composite keys (e.g., `@Embeddable public record VinculoId(Long numfunc, Integer numvinc) implements CompositeResourceId {}`) as the `ID` type parameter of `BaseCrudRepository<E, ID>`, `ResourceMapper<..., ID>`, `AbstractBaseResourceService<..., ID, ...>`, and `AbstractResourceController<..., ID, ...>`. On the HTTP/JSON/OpenAPI wire, composite IDs are serialized and deserialized as canonical colon-delimited strings (`"1001:1"`, with `%3A`/`%25` escaping for colons/percents) across `@PathVariable`, `@RequestParam` (`ids`, `includeIds`), `OptionDTO<ID>`, `RESOURCE_ENTITY` option sources, `@Filterable(relation = "id.numfunc")` / `@Filterable(relation = "vinculo.id")`, stats (`JpaStatsQueryExecutor`), HATEOAS `_links`, ETag, and `BulkIdentityCodecs.composite(VinculoId.class)`. Use `@EmbeddedId` for **immutable** natural/composite domain keys (such as `VINCULOS (numfunc, numvinc)` or `DEPENDENTES (numfunc, numdep)`), and use a surrogate `id BIGINT` + `UNIQUE` business constraint for **mutable** event tables where the user can edit the date or event code in `PUT /{id}` (since JPA forbids mutating `@EmbeddedId` fields on a managed instance).64- Keep ordinary CRUD in the resource baseline; model non-CRUD business transitions with `@WorkflowAction` and composed UI journeys with `@UiSurface`.65- Before persisting a resource write, verify that the persistence context is clean and bound so a mapper lookup or repository query cannot autoflush caller-owned entity mutations ahead of governance or validation.66- Keep controller/base, service/base, mapper, response envelope, and tests aligned in the same change.67- All resource stats endpoints (`groupByStats`, `timeSeriesStats`, `distributionStats`, `comparisonStats`) in `AbstractBaseQueryResourceService` must resolve their base specification via `resolveResourceFilterQuery(request.filter(), Pageable.unpaged()).effectiveSpecification()` so row-level access scope (`resolveResourceFilterAccessScope()`) is enforced identically to `filter()`.68- Multidimensional `group-by` (`dimensions[]` with `StatsDimensionExtraction`, finite-domain `fillGaps`, and `AVG_PER_CYCLE_OCCURRENCE`) belongs to the canonical `POST /{resource}/stats/group-by` contract (`GroupByStatsRequest` / `GroupByStatsResponse`); do not create bespoke heatmap or cross-tab endpoints per resource.69- Treat legacy classes as migration surfaces unless the local AGENTS says otherwise.7071## No Keyword Routing7273Do not infer resource operations, CRUD mode, capabilities, or workflow intent from controller names, method words, labels, or route regexes. Resolve behavior from `@ApiResource`, controller hierarchy, OpenAPI operations, `@UiSurface`, `@WorkflowAction`, and capability snapshots.7475## Adherence Inventory7677Before adding a new base controller method, response field, filter endpoint, export mode, or stats hook, classify the need:7879- `ja-suportado-so-ux`80- `ja-suportado-mal-nomeado-ou-mal-materializado`81- `suportado-parcialmente`82- `lacuna-real-de-contrato`8384Only `lacuna-real-de-contrato` justifies a new public baseline contract.8586## Validation8788- **In Platform Source Mode (`praxis-metadata-starter`):**89 - resource CRUD/query/hypermedia: `mvn "-Dtest=AbstractResourceControllerMappedCrudTest,ResourceControllerStatsAndLocateTest,HypermediaDiscoveryE2ETest,HateoasAndPayloadSizeE2ETest" test`90 - filters/pagination: `mvn "-Dtest=GenericSpecificationsBuilderTest,FilterRequestBodyAdviceTest,PageableBuilderTest" test`91 - export: `mvn "-Dtest=CollectionExportControllerTest,AbstractBaseQueryResourceServiceCollectionExportTest,CollectionExportExecutorTest" test`92 - downstream proof when public contracts change: `QuickstartMetadataMigrationIntegrationTest` or `EventosFolhaPilotIntegrationTest` in `praxis-api-quickstart`.93- **In Consumer Host Mode:**94 - run the host's focused resource controller/service/MockMvc tests verifying `/filter`, CRUD/actions, `RestApiResponse._links`, `/schemas/filtered`, and `/capabilities`.9596For public baseline changes, review README, guides, quickstart docs/examples, Angular `GenericCrudService`, and HTTP examples. Keep the opening and quickstart sections of `README.md` focused on onboarding and canonical architecture; record incremental RC/candidate checkpoints in `docs/technical/BULK-AND-RELEASE-CANDIDATES-STATUS.md` or dedicated technical docs. State explicitly when no derived artifact is affected.9798## Companion Skills99100*(In external Antigravity workspaces, full companion skills are available under `~/.gemini/praxis-skills/<skill-name>/SKILL.md` or `$CODEX_HOME/skills/<skill-name>/SKILL.md`.)*101102- Use `praxis-java-resource-authoring` and `praxis-java-host-project` when implementing or scaffolding resources in a Java host.103- Use `praxis-metadata-schema-contracts` for `/schemas/filtered`, `x-ui`, ETag, and `X-Schema-Hash`.104- Use `praxis-metadata-discovery-capabilities` for `@UiSurface`, `@WorkflowAction`, `/schemas/surfaces`, `/schemas/actions`, and `/capabilities`.105- Use `praxis-metadata-domain-option-sources` and `praxis-dto-annotations` for DTO, filter, governance, and option-source contracts.106- Use `praxis-core-resource-runtime` when verifying Angular `GenericCrudService` consumption.