Praxis Java Availability Discovery Authoring
Author discovery from executable resource operations. A surface describes a composed business experience; an action describes an explicit command; capabilities aggregate availability over those contracts. None of them is a second schema, a button registry, or a frontend visibility workaround.
Establish The Executable Operation
Inspect the resource key/path, controller method, request/response schema, service state transition, authorization, entity/view state, existing actions and surfaces, capabilities snapshot, direct runtime consumer, and focused tests. Decide whether the need is collection or item scoped, ordinary CRUD, explicit business command, composed journey, related-resource navigation, stats, export, or only a runtime materialization gap.
Classify every proposed surface, action, availability input, capability field,
related resource, or catalog shape as ja-suportado-so-ux,
ja-suportado-mal-nomeado-ou-mal-materializado,
suportado-parcialmente, or lacuna-real-de-contrato. Do not add discovery
metadata until an actual operation and its canonical schema exist.
Author Discovery And Availability
- Keep ordinary create/read/update/delete on the resource baseline. Model a
stateful or consequential business command as
@WorkflowAction, with stable action ID, scope, input/output schemas, side effect, state and authorization conditions, HTTP outcome, and negative path. Do not conceal it in a generic PATCH/PUT or infer it from a method name. - Model a composed journey as
@UiSurfaceover real operations and canonical schemas. State its scope, target resource/child binding, supported operations, and materialization purpose. Do not use a surface merely to name a route, drawer, tab, or button. - Keep
@UiSurfaceand@WorkflowActionseparate. Combining them on one method enters an explicit conflict-validation zone and requires a documented reason plus validation ofpraxis.metadata.validation.*behavior. - Define availability from a shared
ResourceStateSnapshotand contextual availability resolvers/evaluators.DefaultCapabilityServiceopens aResourceStateSnapshotScopeper item capability projection so surface, action, and capability resolvers share a singleResourceStateSnapshotProvider.resolve(resourceKey, resourceId)lookup. Whenever a controller declaresallowedStateson@WorkflowActionor@UiSurface, register that@ApiResource(resourceKey = ...)in the host'sResourceStateSnapshotProvider(e.g.QuickstartResourceStateSnapshotProvider) and cover it with an architectural test so item/capabilitiesnever degrades toSNAPSHOT_UNAVAILABLE. Do not add repeated N+1 loads or duplicate state predicates in controllers and Angular. - Preserve the distinction between absent catalog entry and unavailable
capability. Catalogs report definitions;
GET /{resource}/capabilitiesandGET /{resource}/{id}/capabilitiespublish aggregate collection/item snapshots. They do not redefine request payloads, schemas, or business rules. - Add related-resource surfaces only when child binding and child operations are
backed by canonical child capabilities (
SurfaceCatalogServicememoizes child capability lookups per normalizedchildResourcePathwithin each catalog pass). Add stats/export only when actualStatsFieldRegistry/StatsSupportModeor collection export support exists. - Keep
RestApiResponse._linksaligned with available operations. Do not replace HATEOAS with host-local link fields or force the UI to rebuild URLs from labels.
Read discovery-decision-matrix.md when selecting discovery type, scope, availability evidence, or focused proof.
Bind An Explicit Operation Safely
When a contract references an operation by ID, inspect the exact Metadata version's
CanonicalOperationResolver and docs/spec/CANONICAL-OPERATION-BINDING.md first.
Where available, requireResourceOperation(resourceKey, operationId, method) checks
an explicit @Operation against the real MVC registration and matching @ApiResource.
Use it after handler initialization; do not reconstruct this proof in the host or
choose a handler by path fragments. Custom resolvers must implement the strict
method; its default throws rather than falling back to permissive lookup.
Global uniqueness is checked before resource/method filtering, including collisions
with effective legacy Java method IDs. resolveByOperationId rejects duplicate IDs;
its legacy single-handler fallback is not a strict binding. Require one path and
method; reject an address shared by another mapping even with a different ID or
media type. Reject hidden or unrepresentable conditional routing, and do not silently
normalize a different registered path.
For a governed bulk business action, keep the confirmation as a real
@WorkflowAction and bind it with @BulkOperation on that same handler. The
controller must also declare @BulkResourceOperations; its five IDs bind only
the shared lifecycle handlers, while @BulkOperation binds the business
confirmation/evaluation pair. The method annotation names the bulk mode, the
distinct evaluation operationId, and the collection atomicity. Both confirmation
and evaluation must be explicit POST operations in the same @ApiResource controller,
with request bodies and globally unique operation IDs; the declared atomicity must
agree with the workflow action. An action annotation without the class-level
lifecycle declaration is orphaned: the binding diagnostic must reserve its IDs and
strict operation resolution must fail closed. Do not treat evaluation or
confirmation as a bodyless lifecycle operation.
The binding proves identity between real MVC handlers; it does not prove complete
OpenAPI schema content, evaluation-provider wiring, authorization, descriptor
fingerprint, durable lifecycle control, readiness, or execution. A missing or
ambiguous pair must fail closed as a whole. For the structural composition step,
the five lifecycle operations must also prove absence of OpenAPI requestBody in
the captured group snapshot with snapshot.requireNoRequestBody(operation).
Bind The Actual MVC Request DTO
Where available, use requireResourceRequestBody(resourceKey, operationId, method, mapper.getTypeFactory()) and read docs/spec/CANONICAL-OPERATION-BINDING.md first.
It shares the strict MVC entry with operation resolution and returns operation plus
JavaType from the actual required @RequestBody, resolving controller/interface
generics. Do not pass an independently guessed DTO or perform another handler lookup
in the host.
Only the documented concrete DTO subset is supported. Reject optional/multiple bodies,
transport wrappers, scalar/container roots, raw/unbound/wildcard types, non-static member
classes and unresolved generic ancestors. Pass the returned operation to
documents.requireRequestSchema and the returned bodyType to BulkEditableFields
with the same configured mapper and trusted protected wire names.
Preserve The Platform Boundary
praxis-metadata-starterowns annotations, catalogs, availability contexts/evaluators, resource state snapshots, capabilities, HATEOAS, and stats/export discovery.- The host owns verified domain state, command implementation, authorization, and snapshot provider inputs. It must not create a separate action catalog or availability vocabulary.
praxis-ui-angularconsumes catalog/capability projections. It must not decide availability from labels, role-name strings, local regexes, or copied states.
Do not resolve primary user intent or choose an action/surface from keywords, aliases, fuzzy matching, or route fragments. Use resource keys, action IDs, surface IDs, schemas, capabilities, and governed context; text can only rank already scoped candidates.
Prove The Full Discovery Path
Prove definition, scope, positive availability, negative availability, correct schemas, capability projection, and direct consumer materialization. For an item decision, prove the state snapshot is shared instead of repeatedly loaded. For a workflow action, prove execution and rejection in invalid state or authorization. For related resources, prove binding and child capability alignment.
Use focused action, surface, capability, HATEOAS, stats/export, and cockpit tests from the starter. Add quickstart HTTP/cockpit proof for public contracts and review Angular action/surface/resource runtime tests. Review docs or HTTP examples only when their published catalog/capability claim changes.
Companion Skills
praxis-java-resource-authoring: operations, resource hierarchy, DTOs, and proof.praxis-metadata-discovery-capabilities: canonical discovery, availability, capabilities, cockpit, stats, and export behavior.praxis-metadata-schema-contracts: operation schemas and filtered schema.praxis-metadata-resource-baseline: resource base,_links, query, export, and stats foundations.praxis-api-quickstart-cockpit-http-validation: published HTTP/cockpit proof.
Close with the operation-to-discovery matrix, snapshot inputs, availability decisions, positive/negative evidence, consumer proof, and any platform gap. Discovery is ready when the runtime can determine what is possible and why, without reconstructing business semantics locally.