Praxis Java Contract Conformance
Use this as the final proof gate for an implemented resource. It does not replace
the focused implementation skills; it assembles their evidence and reveals which
contract edge still prevents a migration-ready API.
Build A Resource Evidence Pack
Start with one resource key and canonical path. Inspect its controller, service,
mapper, DTOs, filters, actions, surfaces, option descriptors, errors, tests,
HTTP examples, direct Angular consumers, and any legacy parity artifact. Record
the operation matrix before running tests.
For every failure, classify it as ja-suportado-so-ux,
ja-suportado-mal-nomeado-ou-mal-materializado,
suportado-parcialmente, or lacuna-real-de-contrato. A conformance failure is
not permission to add a frontend alias, duplicate endpoint, second schema, or
host-local metadata map. Locate and fix the canonical owner.
Read conformance-evidence-matrix.md
to select only the evidence required by the resource's actual operations.
Audit In Levels
- Domain Completeness & Anti-Truncation Scorecard (Mandatory First Gate):
Never approve a resource merely because
mvn test or a minimal smoke test passes. Before inspecting schema or HTTP details, compute and report the Domain Completeness Scorecard (and run python scripts/workspace/audit-java-resource-completeness.py <host-path> when auditing a workspace host):
- Entity-to-DTO Column Accounting (
100% business column accountability): Compare every column of the JPA Entity against ResponseDTO, CreateDTO, UpdateDTO, @ResourceIntent DTOs, and @WorkflowAction request DTOs. Every business column must either be:
- Exposed in
ResponseDTO + CreateDTO/UpdateDTO (grouped via @UISchema(group = ...), using tableHidden = true for secondary detail fields so tables remain concise while forms/detail views are complete);
- Exposed as
readOnly = true in ResponseDTO and mutated by a dedicated @WorkflowAction or @ResourceIntent (PATCH); or
- Explicitly justified as internal/technical (
@Version).
If a resource silently drops domain columns (e.g., exposing 9 of 55 entity columns or 15 of 51 columns), mark static as fail immediately (lacuna-de-completude-de-dominio).
- Quick View 360° &
@UISchema Editorial Quality (QuickViewCols >= 4, RichIdentity = YES, EditorialIssues == 0):
- Verify
@ResourceIdentity declares subtitleField and/or metadataFields = {...} in addition to keyField and titleField;
- Verify each
ResponseDTO curates 4 to 8 summary fields with @UISchema(quickViewVisible = true, quickViewOrder = ...);
- Verify
@ResourceReference(resourceKey = ..., valueField = ..., surfaceId = "detail", previewSurfaceId = ..., detailPresentation = "drawer") on the resource's title field and on every foreign-key display projection (orgaoNome, pessoaNome, cargoNome, setorNome, cargoComissaoNome, etc.), backed by @UiSurface(kind = SurfaceKind.READ_PROJECTION | SurfaceKind.VIEW);
- Reject (
fail) any DTO where @UISchema(label = ...) is a pasted sentence/description (> 36 chars or ending with .) or where LocalDate/LocalDateTime fields omit controlType = FieldControlType.DATE_PICKER.
FilterDTO Predicate Density & Variety: Verify that FilterDTO covers all operational search dimensions of the entity across multiple FilterOperation families (LIKE/STARTS_WITH, EQUAL, IN/NOT_IN, BETWEEN/GREATER_OR_EQUAL/LESS_OR_EQUAL, IN_LAST_DAYS/IN_NEXT_DAYS/ON_DATE, IS_NULL/IS_NOT_NULL, IS_TRUE, cross-entity relation = "parent.field", and @CustomFields when JSONB is present). A 2- to 4-field FilterDTO on a rich domain entity is an automatic fail.
- Praxis Capability Density (
@QuickFilter, @ResourceIntent, @WorkflowAction, @ResourceFact, Business Invariants):
- Verify
@QuickFilters on @ApiResource for operational cohorts;
- Verify
@ResourceIntent (PATCH) + @UiSurface(kind = SurfaceKind.PARTIAL_FORM) on wide entities (20+ columns or multiple functional sub-blocks);
- Verify that every lifecycle state transition in the entity (
situacao, dtExtincao, dtHomologEstagio, etc.) has a corresponding @WorkflowAction backed by ResourceStateSnapshotProvider;
- Verify
@ResourceFact annotations for derived domain indicators;
- Verify that real domain invariants (chronological date order, vacancy balance, extinct record guards, constitutional accumulation, cross-tenant FK consistency, uniqueness, conditional requiredness) are enforced in the
Service and covered by negative tests (409/422).
- Static: resource identity, canonical path, selected resource base,
operation-specific DTOs, mapper/service wiring, annotations, governance, and
explicit commands are coherent. A read-only resource must not claim writes;
a mutable resource must not hide workflows in generic updates. For shared bulk
lifecycle handlers, inspect
@BulkResourceOperations and each handler's
@BulkResourceOperation role. The five declared IDs must bind to one real MVC
handler each; do not infer them from Java names, labels, or paths. For a bulk
domain command, also inspect the real @WorkflowAction confirmation handler's
@BulkOperation binding and verify that its distinct evaluation operation is
a body-bearing POST handler in the same resource controller.
- Schema:
/v3/api-docs, /schemas/filtered, /schemas/catalog,
/schemas/domain, /schemas/surfaces, and /schemas/actions agree on
resource key/path/group, operations, schema references, x-ui, option
sources, field access, and discovery. Catalogs and capabilities are never
accepted as alternate structural schemas. For shared bulk lifecycle handlers,
confirm requireResourceOperation(resourceKey, operationId, method) returns
the expected CanonicalOperationRef, the exact named group document preserves
that identity, and every currently published group is inspected for rewrites
or collisions in paths, callbacks, and webhooks.
- HTTP: exercise filter/get/write/action/export/stats operations that exist;
verify
RestApiResponse._links, structured error shape, validation errors,
status semantics, ETag, If-None-Match, and X-Schema-Hash. Capture only
sanitized evidence; never publish database, package, token, session, SQL, or
provider-context details.
- Availability: compare collection and item
/capabilities, action and
surface catalogs, and _links in both allowed and denied states. Verify that
item decisions use the shared resource state snapshot and remain fail-closed
where protected.
- Runtime readiness: trace each published contract to its real Angular
consumer.
GenericCrudService consumes resource/schema/filter/option paths;
SchemaMetadataClient and fetch-with-etag consume ETag/hash semantics;
ResourceDiscoveryService follows _links for surfaces/actions/capabilities;
forms, tables, and analytics consume the matching normalized metadata. Do not
require building a new screen, but do require that an existing official runtime
path can materialize the contract without custom consumer rules.
- Persistence/parity: when the resource is legacy-backed, prove a scoped
development mutation or read path as appropriate, preserve before/after
evidence, cleanup/rollback plan, and parity result. Do not claim parity merely
from a matching DTO name or one happy-path row.
Scope Evidence To Existing Operations
Only audit option-source filter/by-ids, actions, surfaces, stats, export, field
access, related resources, or config materializations when the resource publishes
them. Conversely, every published feature needs its matching proof. Do not mark
a resource conformant because unrelated broad tests are green.
Public contract changes require focused starter tests, quickstart HTTP proof when
available, and affected Angular specs. Use source-local AGENTS.md commands;
prefer focused tests over broad suites. Review docs, corpus, examples, and
playgrounds only when they publish the changed contract.
Bulk Protocol, Artifact Provenance, Strict OpenAPI, And Cold-Start Gates
When auditing org.praxisplatform.uischema.bulk protocol input/results,
BulkConsumerArtifactIntegrationTest git provenance, @BulkEditable compilation,
strict canonical OpenAPI group snapshots (getDocumentForGroupStrict), or
EmbeddedPostgresColdStartTest, read
bulk-and-openapi-conformance-gates.md.
Report Without Ambiguity
Return an evidence pack containing:
- identity and operation matrix;
- status for
static, schema, http, availability, persistence/parity,
and angular-readiness: pass, not-applicable, blocked, or fail;
- source files, endpoints, fixtures, commands, and sanitized outcomes;
- canonical owner and classification for every non-pass result;
- derived-artifact decision, remaining risk, and exact next action.
blocked is only valid when an external prerequisite is unavailable and the
remaining local checks were exhausted. not-applicable must name the absent
published operation. Never use either label to hide an untested public claim.
Preserve Canonical Ownership
praxis-metadata-starter owns resource metadata, schemas, discovery,
capabilities, _links, HTTP metadata headers, and their conformance rules.
praxis-config-starter owns governed config/authoring contracts; a resource
audit may verify materialization but must not redefine config semantics.
praxis-ui-angular owns runtime materialization; conformance checks consumers
rather than creating a competing UI contract.
- Quickstart and HTTP corpus provide operational proof and do not become owners.
Do not decide resource scope, operation, action, surface, or consumer path with
keyword routing, regexes, label matching, or route-string guesses. Ground it in
resource keys, canonical schemas, links, action/surface IDs, capabilities, and
declared runtime contracts.
Companion Skills
praxis-java-resource-authoring: implementation and resource operation matrix.
praxis-java-filter-query-authoring: filter/query proof.
praxis-java-option-source-provider-authoring: external option source proof.
praxis-java-availability-discovery-authoring: action/surface/capability proof.
praxis-metadata-schema-contracts: schema, OpenAPI, ETag, and hash semantics.
praxis-api-quickstart-cockpit-http-validation: HTTP/cockpit evidence.
praxis-core-resource-runtime: Angular runtime materialization.
Close only when the evidence pack shows a resource can be consumed canonically by
the intended runtime, or when every remaining gap has a named owner and an
explicit follow-up. Compilation alone is not conformance.
1---2name: praxis-java-contract-conformance3description: "Use when auditing a Praxis Java resource or host before migration/API handoff: verify OpenAPI, filtered/catalog/domain schemas, x-ui, ETag and X-Schema-Hash, RestApiResponse _links, structured errors, filters, option sources, actions, surfaces, collection/item capabilities, stats/export, sanitized evidence, and Angular runtime readiness through GenericCrudService, SchemaMetadataClient, ResourceDiscoveryService, forms, tables, or analytics consumers."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-java-contract-conformance6---78# Praxis Java Contract Conformance910Use this as the final proof gate for an implemented resource. It does not replace11the focused implementation skills; it assembles their evidence and reveals which12contract edge still prevents a migration-ready API.1314## Build A Resource Evidence Pack1516Start with one resource key and canonical path. Inspect its controller, service,17mapper, DTOs, filters, actions, surfaces, option descriptors, errors, tests,18HTTP examples, direct Angular consumers, and any legacy parity artifact. Record19the operation matrix before running tests.2021For every failure, classify it as `ja-suportado-so-ux`,22`ja-suportado-mal-nomeado-ou-mal-materializado`,23`suportado-parcialmente`, or `lacuna-real-de-contrato`. A conformance failure is24not permission to add a frontend alias, duplicate endpoint, second schema, or25host-local metadata map. Locate and fix the canonical owner.2627Read [conformance-evidence-matrix.md](references/conformance-evidence-matrix.md)28to select only the evidence required by the resource's actual operations.2930## Audit In Levels31320. **Domain Completeness & Anti-Truncation Scorecard (Mandatory First Gate):**33 Never approve a resource merely because `mvn test` or a minimal smoke test passes. Before inspecting schema or HTTP details, compute and report the **Domain Completeness Scorecard** (and run `python scripts/workspace/audit-java-resource-completeness.py <host-path>` when auditing a workspace host):34 - **Entity-to-DTO Column Accounting (`100%` business column accountability):** Compare every column of the JPA Entity against `ResponseDTO`, `CreateDTO`, `UpdateDTO`, `@ResourceIntent` DTOs, and `@WorkflowAction` request DTOs. Every business column must either be:35 1. Exposed in `ResponseDTO` + `CreateDTO`/`UpdateDTO` (grouped via `@UISchema(group = ...)`, using `tableHidden = true` for secondary detail fields so tables remain concise while forms/detail views are complete);36 2. Exposed as `readOnly = true` in `ResponseDTO` and mutated by a dedicated `@WorkflowAction` or `@ResourceIntent` (`PATCH`); or37 3. Explicitly justified as internal/technical (`@Version`).38 If a resource silently drops domain columns (e.g., exposing 9 of 55 entity columns or 15 of 51 columns), mark `static` as **`fail`** immediately (`lacuna-de-completude-de-dominio`).39 - **Quick View 360° & `@UISchema` Editorial Quality (`QuickViewCols >= 4`, `RichIdentity = YES`, `EditorialIssues == 0`):**40 - Verify `@ResourceIdentity` declares `subtitleField` and/or `metadataFields = {...}` in addition to `keyField` and `titleField`;41 - Verify each `ResponseDTO` curates 4 to 8 summary fields with `@UISchema(quickViewVisible = true, quickViewOrder = ...)`;42 - Verify `@ResourceReference(resourceKey = ..., valueField = ..., surfaceId = "detail", previewSurfaceId = ..., detailPresentation = "drawer")` on the resource's title field and on every foreign-key display projection (`orgaoNome`, `pessoaNome`, `cargoNome`, `setorNome`, `cargoComissaoNome`, etc.), backed by `@UiSurface(kind = SurfaceKind.READ_PROJECTION | SurfaceKind.VIEW)`;43 - Reject (`fail`) any DTO where `@UISchema(label = ...)` is a pasted sentence/description (`> 36` chars or ending with `.`) or where `LocalDate`/`LocalDateTime` fields omit `controlType = FieldControlType.DATE_PICKER`.44 - **`FilterDTO` Predicate Density & Variety:** Verify that `FilterDTO` covers all operational search dimensions of the entity across multiple `FilterOperation` families (`LIKE`/`STARTS_WITH`, `EQUAL`, `IN`/`NOT_IN`, `BETWEEN`/`GREATER_OR_EQUAL`/`LESS_OR_EQUAL`, `IN_LAST_DAYS`/`IN_NEXT_DAYS`/`ON_DATE`, `IS_NULL`/`IS_NOT_NULL`, `IS_TRUE`, cross-entity `relation = "parent.field"`, and `@CustomFields` when JSONB is present). A 2- to 4-field `FilterDTO` on a rich domain entity is an automatic **`fail`**.45 - **Praxis Capability Density (`@QuickFilter`, `@ResourceIntent`, `@WorkflowAction`, `@ResourceFact`, Business Invariants):**46 - Verify `@QuickFilter`s on `@ApiResource` for operational cohorts;47 - Verify `@ResourceIntent` (`PATCH`) + `@UiSurface(kind = SurfaceKind.PARTIAL_FORM)` on wide entities (20+ columns or multiple functional sub-blocks);48 - Verify that every lifecycle state transition in the entity (`situacao`, `dtExtincao`, `dtHomologEstagio`, etc.) has a corresponding `@WorkflowAction` backed by `ResourceStateSnapshotProvider`;49 - Verify `@ResourceFact` annotations for derived domain indicators;50 - Verify that real domain invariants (chronological date order, vacancy balance, extinct record guards, constitutional accumulation, cross-tenant FK consistency, uniqueness, conditional requiredness) are enforced in the `Service` and covered by negative tests (`409`/`422`).511. **Static:** resource identity, canonical path, selected resource base,52 operation-specific DTOs, mapper/service wiring, annotations, governance, and53 explicit commands are coherent. A read-only resource must not claim writes;54 a mutable resource must not hide workflows in generic updates. For shared bulk55 lifecycle handlers, inspect `@BulkResourceOperations` and each handler's56 `@BulkResourceOperation` role. The five declared IDs must bind to one real MVC57 handler each; do not infer them from Java names, labels, or paths. For a bulk58 domain command, also inspect the real `@WorkflowAction` confirmation handler's59 `@BulkOperation` binding and verify that its distinct evaluation operation is60 a body-bearing POST handler in the same resource controller.612. **Schema:** `/v3/api-docs`, `/schemas/filtered`, `/schemas/catalog`,62 `/schemas/domain`, `/schemas/surfaces`, and `/schemas/actions` agree on63 resource key/path/group, operations, schema references, `x-ui`, option64 sources, field access, and discovery. Catalogs and capabilities are never65 accepted as alternate structural schemas. For shared bulk lifecycle handlers,66 confirm `requireResourceOperation(resourceKey, operationId, method)` returns67 the expected `CanonicalOperationRef`, the exact named group document preserves68 that identity, and every currently published group is inspected for rewrites69 or collisions in paths, callbacks, and webhooks.703. **HTTP:** exercise filter/get/write/action/export/stats operations that exist;71 verify `RestApiResponse._links`, structured error shape, validation errors,72 status semantics, ETag, `If-None-Match`, and `X-Schema-Hash`. Capture only73 sanitized evidence; never publish database, package, token, session, SQL, or74 provider-context details.754. **Availability:** compare collection and item `/capabilities`, action and76 surface catalogs, and `_links` in both allowed and denied states. Verify that77 item decisions use the shared resource state snapshot and remain fail-closed78 where protected.795. **Runtime readiness:** trace each published contract to its real Angular80 consumer. `GenericCrudService` consumes resource/schema/filter/option paths;81 `SchemaMetadataClient` and `fetch-with-etag` consume ETag/hash semantics;82 `ResourceDiscoveryService` follows `_links` for surfaces/actions/capabilities;83 forms, tables, and analytics consume the matching normalized metadata. Do not84 require building a new screen, but do require that an existing official runtime85 path can materialize the contract without custom consumer rules.866. **Persistence/parity:** when the resource is legacy-backed, prove a scoped87 development mutation or read path as appropriate, preserve before/after88 evidence, cleanup/rollback plan, and parity result. Do not claim parity merely89 from a matching DTO name or one happy-path row.9091## Scope Evidence To Existing Operations9293Only audit option-source filter/by-ids, actions, surfaces, stats, export, field94access, related resources, or config materializations when the resource publishes95them. Conversely, every published feature needs its matching proof. Do not mark96a resource conformant because unrelated broad tests are green.9798Public contract changes require focused starter tests, quickstart HTTP proof when99available, and affected Angular specs. Use source-local `AGENTS.md` commands;100prefer focused tests over broad suites. Review docs, corpus, examples, and101playgrounds only when they publish the changed contract.102103## Bulk Protocol, Artifact Provenance, Strict OpenAPI, And Cold-Start Gates104105When auditing `org.praxisplatform.uischema.bulk` protocol input/results,106`BulkConsumerArtifactIntegrationTest` git provenance, `@BulkEditable` compilation,107strict canonical OpenAPI group snapshots (`getDocumentForGroupStrict`), or108`EmbeddedPostgresColdStartTest`, read109[bulk-and-openapi-conformance-gates.md](references/bulk-and-openapi-conformance-gates.md).110111## Report Without Ambiguity112113Return an evidence pack containing:114115- identity and operation matrix;116- status for `static`, `schema`, `http`, `availability`, `persistence/parity`,117 and `angular-readiness`: `pass`, `not-applicable`, `blocked`, or `fail`;118- source files, endpoints, fixtures, commands, and sanitized outcomes;119- canonical owner and classification for every non-pass result;120- derived-artifact decision, remaining risk, and exact next action.121122`blocked` is only valid when an external prerequisite is unavailable and the123remaining local checks were exhausted. `not-applicable` must name the absent124published operation. Never use either label to hide an untested public claim.125126## Preserve Canonical Ownership127128- `praxis-metadata-starter` owns resource metadata, schemas, discovery,129 capabilities, `_links`, HTTP metadata headers, and their conformance rules.130- `praxis-config-starter` owns governed config/authoring contracts; a resource131 audit may verify materialization but must not redefine config semantics.132- `praxis-ui-angular` owns runtime materialization; conformance checks consumers133 rather than creating a competing UI contract.134- Quickstart and HTTP corpus provide operational proof and do not become owners.135136Do not decide resource scope, operation, action, surface, or consumer path with137keyword routing, regexes, label matching, or route-string guesses. Ground it in138resource keys, canonical schemas, links, action/surface IDs, capabilities, and139declared runtime contracts.140141## Companion Skills142143- `praxis-java-resource-authoring`: implementation and resource operation matrix.144- `praxis-java-filter-query-authoring`: filter/query proof.145- `praxis-java-option-source-provider-authoring`: external option source proof.146- `praxis-java-availability-discovery-authoring`: action/surface/capability proof.147- `praxis-metadata-schema-contracts`: schema, OpenAPI, ETag, and hash semantics.148- `praxis-api-quickstart-cockpit-http-validation`: HTTP/cockpit evidence.149- `praxis-core-resource-runtime`: Angular runtime materialization.150151Close only when the evidence pack shows a resource can be consumed canonically by152the intended runtime, or when every remaining gap has a named owner and an153explicit follow-up. Compilation alone is not conformance.