Praxis Java Option Source Provider Authoring
Use a provider when a governed Praxis option source must execute against an
external catalog, registered query, table function, remote service, or another
host-specific backend. A provider is private execution behind the canonical
option-source contract; it is not a new public lookup endpoint.
Establish The Source Contract First
Inspect the consuming DTO field, OptionSourceDescriptor, option-source
registry/configuration, resource service/controller, schema projection,
authorization/tenant constraints, expected runtime consumer, and focused tests.
Classify whether the need is a reusable RESOURCE_ENTITY, LIGHT_LOOKUP,
DISTINCT_DIMENSION, CATEGORICAL_BUCKET, or an existing static source before
adding a provider.
Classify any new source type, metadata field, endpoint, execution policy,
dependency, or reload behavior as ja-suportado-so-ux,
ja-suportado-mal-nomeado-ou-mal-materializado,
suportado-parcialmente, or lacuna-real-de-contrato. Keep the public
x-ui.optionSource, descriptor, runtime contract, and canonical controller path
in praxis-metadata-starter; host code supplies only execution.
Implement The Provider Path
- Define a stable source key, type, semantic entity identity, display contract,
policy, capabilities, dependencies, and
OptionSourceRuntimeContract. Use
canonical filter and by-ids paths. New reusable sources normally publish
selectedReloadPolicy=required and invalidSortPolicy=reject.
- Set
OptionSourceExecutionMode.PROVIDER_REQUIRED when JPA must never attempt
to execute the descriptor. Leave JPA fallback eligible only when the
descriptor is truly JPA-executable. Do not use a JPA failure, missing table,
or id/label alias as implicit provider selection.
- Implement
OptionSourceProvider.supports, filter, and byIds. Make
supports precise by descriptor, private context, and operation. If more
than one provider can support a source, declare Ordered or @Order; a
host provider precedes JPA fallback, while equal-priority matches are a
configuration error.
- Receive public values through the already validated
OptionSourceExecutionRequest: search, structured filters, sort key,
pageable, include IDs, by-ids IDs, and effective filter payload. Map those
values to a typed backend query; never interpolate them into SQL, Oracle
order clauses, remote URLs, package names, or provider-specific query text.
- Use
OptionSourceContextResolver and OptionSourceExecutionContext for
tenant, user, session, datasource, credential, or host-private execution
attributes. Never publish those attributes in x-ui, OpenAPI, option extras,
logs intended for consumers, examples, or errors. Treat public
filterPayload, structured filters, includeIds, and by-ids IDs only as
query criteria; they are never proof of authorization or row scope.
- Apply each published
dependsOn / dependencyFilterMap value to provider
execution. If a dependency is not executable, remove it from public metadata
or resolve the platform gap. A provider that ignores a declared dependency is
incorrect even when its first-page search looks plausible.
- Implement
byIds as a separate selected-value reload path. Return concrete
options for found IDs; the executor preserves requested order and omits
missing IDs. When reload needs the same public dependencies as filtering,
prove the contextual POST by-ids path carries them into the provider. Resolve
private context and enforce access even when the requested ID list is empty;
an early empty response must not bypass authorization.
- Override source dataset versioning when an external source would otherwise
inherit a resource-level JPA count or timestamp query. A version header may
remain public, but external availability must not depend on a base table.
Read provider-contract-matrix.md when
choosing execution mode, reload policy, dependency behavior, ordering, or proof.
Let Praxis Validate Public Requests
CompositeOptionSourceQueryExecutor resolves context, builds a request,
validates it through OptionSourceRequestValidator, then resolves a provider.
Do not bypass this flow or register a second OptionSourceQueryExecutor bean.
Invalid capability, includeIds, search, page size, structured filter, sort, or
dependency metadata must fail before provider resolution. Provider code may trust
the declared policy but must still keep backend query construction typed and
safe.
For option-source sorting, accept only the published validated sort key. Simple
sources may use the documented legacy id/label aliases; structured sources
must use their declared sort options. Do not copy general resource pagination
rules into a provider.
Preserve Boundaries And Prove Them
praxis-metadata-starter owns the descriptor, provider SPI, composite
executor, registry, public endpoint contract, x-ui.optionSource, runtime
policy, schema projection, and normalization of by-ids output.
- The host owns private catalog access, context resolution, authorization and
typed backend execution. Do not leak its datasource, query language, package,
or credentials through metadata.
- JPA-backed resource owners apply server-resolved row scope through
normalizeOptionSourceFilter(...), which must govern filter, includeIds,
GET by-ids, POST by-ids, and empty-ID requests before the Specification
executes. Provider-backed sources apply the equivalent policy from the
private OptionSourceExecutionContext; do not assume the JPA hook rewrites a
provider-specific public payload.
praxis-ui-angular consumes filter and by-ids endpoints. It must not invent a
fallback reload path or infer dependency semantics from labels.
Prove: descriptor/schema runtime projection; correct provider selection; filter
results; by-ids rehydration in requested order; dependency effect; private
context use without leakage; scoped includeIds; empty-ID authorization; and
rejection of invalid input before supports, filter, or byIds is called.
Add dataset-version proof for external sources.
Run the focused provider/registry/composite/validator tests and a host or
quickstart HTTP integration test for published sources. Review Angular option
consumer tests when public runtime metadata changes.
Companion Skills
praxis-resource-entity-lookup-backend: governed RESOURCE_ENTITY contract
and JPA/provider handoff.
praxis-metadata-domain-option-sources: source taxonomy, domain governance,
descriptors, and schema materialization.
praxis-java-filter-query-authoring: filter payload, query semantics, and
sort boundaries outside option sources.
praxis-java-resource-authoring: resource identity, host integration, and
cross-consumer proof.
Close with source classification, descriptor/runtime contract, execution mode,
provider ordering, dependency/reload evidence, private-context boundary, tests,
and any genuine platform follow-up. A provider is complete only when its source
is indistinguishable from a native Praxis option source to public consumers.
1---2name: praxis-java-option-source-provider-authoring3description: "Use when implementing, auditing, or migrating a non-JPA or host-specific Praxis option source: OptionSourceDescriptor execution mode, OptionSourceProvider and registry resolution, private execution context, external catalogs, provider ordering, filter/by-ids reload, dependency payloads, request policy, dataset versioning, and x-ui runtime proof."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-java-option-source-provider-authoring6---78# Praxis Java Option Source Provider Authoring910Use a provider when a governed Praxis option source must execute against an11external catalog, registered query, table function, remote service, or another12host-specific backend. A provider is private execution behind the canonical13option-source contract; it is not a new public lookup endpoint.1415## Establish The Source Contract First1617Inspect the consuming DTO field, `OptionSourceDescriptor`, option-source18registry/configuration, resource service/controller, schema projection,19authorization/tenant constraints, expected runtime consumer, and focused tests.20Classify whether the need is a reusable `RESOURCE_ENTITY`, `LIGHT_LOOKUP`,21`DISTINCT_DIMENSION`, `CATEGORICAL_BUCKET`, or an existing static source before22adding a provider.2324Classify any new source type, metadata field, endpoint, execution policy,25dependency, or reload behavior as `ja-suportado-so-ux`,26`ja-suportado-mal-nomeado-ou-mal-materializado`,27`suportado-parcialmente`, or `lacuna-real-de-contrato`. Keep the public28`x-ui.optionSource`, descriptor, runtime contract, and canonical controller path29in `praxis-metadata-starter`; host code supplies only execution.3031## Implement The Provider Path32331. Define a stable source key, type, semantic entity identity, display contract,34 policy, capabilities, dependencies, and `OptionSourceRuntimeContract`. Use35 canonical filter and by-ids paths. New reusable sources normally publish36 `selectedReloadPolicy=required` and `invalidSortPolicy=reject`.372. Set `OptionSourceExecutionMode.PROVIDER_REQUIRED` when JPA must never attempt38 to execute the descriptor. Leave JPA fallback eligible only when the39 descriptor is truly JPA-executable. Do not use a JPA failure, missing table,40 or `id`/`label` alias as implicit provider selection.413. Implement `OptionSourceProvider.supports`, `filter`, and `byIds`. Make42 `supports` precise by descriptor, private context, and operation. If more43 than one provider can support a source, declare `Ordered` or `@Order`; a44 host provider precedes JPA fallback, while equal-priority matches are a45 configuration error.464. Receive public values through the already validated47 `OptionSourceExecutionRequest`: search, structured filters, sort key,48 pageable, include IDs, by-ids IDs, and effective filter payload. Map those49 values to a typed backend query; never interpolate them into SQL, Oracle50 order clauses, remote URLs, package names, or provider-specific query text.515. Use `OptionSourceContextResolver` and `OptionSourceExecutionContext` for52 tenant, user, session, datasource, credential, or host-private execution53 attributes. Never publish those attributes in `x-ui`, OpenAPI, option extras,54 logs intended for consumers, examples, or errors. Treat public55 `filterPayload`, structured filters, `includeIds`, and by-ids IDs only as56 query criteria; they are never proof of authorization or row scope.576. Apply each published `dependsOn` / `dependencyFilterMap` value to provider58 execution. If a dependency is not executable, remove it from public metadata59 or resolve the platform gap. A provider that ignores a declared dependency is60 incorrect even when its first-page search looks plausible.617. Implement `byIds` as a separate selected-value reload path. Return concrete62 options for found IDs; the executor preserves requested order and omits63 missing IDs. When reload needs the same public dependencies as filtering,64 prove the contextual POST by-ids path carries them into the provider. Resolve65 private context and enforce access even when the requested ID list is empty;66 an early empty response must not bypass authorization.678. Override source dataset versioning when an external source would otherwise68 inherit a resource-level JPA count or timestamp query. A version header may69 remain public, but external availability must not depend on a base table.7071Read [provider-contract-matrix.md](references/provider-contract-matrix.md) when72choosing execution mode, reload policy, dependency behavior, ordering, or proof.7374## Let Praxis Validate Public Requests7576`CompositeOptionSourceQueryExecutor` resolves context, builds a request,77validates it through `OptionSourceRequestValidator`, then resolves a provider.78Do not bypass this flow or register a second `OptionSourceQueryExecutor` bean.79Invalid capability, includeIds, search, page size, structured filter, sort, or80dependency metadata must fail before provider resolution. Provider code may trust81the declared policy but must still keep backend query construction typed and82safe.8384For option-source sorting, accept only the published validated sort key. Simple85sources may use the documented legacy `id`/`label` aliases; structured sources86must use their declared sort options. Do not copy general resource pagination87rules into a provider.8889## Preserve Boundaries And Prove Them9091- `praxis-metadata-starter` owns the descriptor, provider SPI, composite92 executor, registry, public endpoint contract, `x-ui.optionSource`, runtime93 policy, schema projection, and normalization of by-ids output.94- The host owns private catalog access, context resolution, authorization and95 typed backend execution. Do not leak its datasource, query language, package,96 or credentials through metadata.97- JPA-backed resource owners apply server-resolved row scope through98 `normalizeOptionSourceFilter(...)`, which must govern filter, `includeIds`,99 GET by-ids, POST by-ids, and empty-ID requests before the `Specification`100 executes. Provider-backed sources apply the equivalent policy from the101 private `OptionSourceExecutionContext`; do not assume the JPA hook rewrites a102 provider-specific public payload.103- `praxis-ui-angular` consumes filter and by-ids endpoints. It must not invent a104 fallback reload path or infer dependency semantics from labels.105106Prove: descriptor/schema runtime projection; correct provider selection; filter107results; by-ids rehydration in requested order; dependency effect; private108context use without leakage; scoped `includeIds`; empty-ID authorization; and109rejection of invalid input before `supports`, `filter`, or `byIds` is called.110Add dataset-version proof for external sources.111Run the focused provider/registry/composite/validator tests and a host or112quickstart HTTP integration test for published sources. Review Angular option113consumer tests when public runtime metadata changes.114115## Companion Skills116117- `praxis-resource-entity-lookup-backend`: governed `RESOURCE_ENTITY` contract118 and JPA/provider handoff.119- `praxis-metadata-domain-option-sources`: source taxonomy, domain governance,120 descriptors, and schema materialization.121- `praxis-java-filter-query-authoring`: filter payload, query semantics, and122 sort boundaries outside option sources.123- `praxis-java-resource-authoring`: resource identity, host integration, and124 cross-consumer proof.125126Close with source classification, descriptor/runtime contract, execution mode,127provider ordering, dependency/reload evidence, private-context boundary, tests,128and any genuine platform follow-up. A provider is complete only when its source129is indistinguishable from a native Praxis option source to public consumers.