Praxis Metadata Schema Contracts
Use this skill for the canonical structural schema surface of praxis-metadata-starter. This starter publishes backend semantic grounding for Praxis runtimes and AI authoring; it is not merely a JSON-schema generator for Angular components.
Source Audit
Inspect the owner before editing:
praxis-metadata-starter/AGENTS.mdpraxis-metadata-starter/README.mdsrc/main/java/org/praxisplatform/uischema/controller/docs/ApiDocsController.javasrc/main/java/org/praxisplatform/uischema/controller/docs/DomainCatalogController.javasrc/main/java/org/praxisplatform/uischema/controller/docs/SemanticDomainCatalogController.javasrc/main/java/org/praxisplatform/uischema/openapi/OpenApiDocumentService.javasrc/main/java/org/praxisplatform/uischema/openapi/GenerationScopedGenericResponseService.javasrc/main/java/org/praxisplatform/uischema/configuration/OpenApiResponseGenerationAutoConfiguration.javasrc/main/java/org/praxisplatform/uischema/openapi/CanonicalOperationResolver.javasrc/main/java/org/praxisplatform/uischema/schema/SchemaReferenceResolver.javasrc/main/java/org/praxisplatform/uischema/schema/FilteredSchemaReferenceResolver.javasrc/main/java/org/praxisplatform/uischema/hash/**src/main/java/org/praxisplatform/uischema/http/IfNoneMatchUtils.javadocs/spec/**anddocs/guides/**when public contract or narrative changes
Canonical Boundary
/schemas/filtered is the structural source of truth. It owns operation-specific schema shape, properties.*.x-ui, x-ui.resource.idField, x-ui.resource.capabilities, schemaId, schemaUrl, ETag, and X-Schema-Hash.
/schemas/catalog is a derived documentary/discovery projection over OpenAPI. It enumerates candidate endpoints and publishes group/resource presentation, operation summaries/examples, and request/response schema links. Its resourceKey, path, and method can scope subsequent discovery, but catalog presence is not structural schema truth, authorization, or current capability proof.
Capabilities are a contextual availability snapshot. They aggregate canonical operation flags, stats field eligibility/metrics, actions, surfaces, and stable resourceKey plus operational resourcePath; they do not redefine property structure. /schemas/domain, /schemas/surfaces, /schemas/actions, and capabilities may reference schemas, but none may replace or inline a second version of the filtered schema payload.
Use canonical operation resolution from OpenAPI before inventing endpoint maps. path + operation + schemaType should resolve through CanonicalOperationResolver, OpenApiDocumentService, and SchemaReferenceResolver.
For /schemas/filtered, schemaId, schemaUrl, ETag, and X-Schema-Hash are one structural evidence chain. Any new structural dimension such as includeInternalSchemas, idField, readOnly, operation, or schemaType must be reflected consistently in FilteredSchemaReferenceResolver, ApiDocsController, schema hash calculation, conditional request handling, docs/spec examples, and Angular cache consumption.
Do not transfer that conditional-cache contract to /schemas/catalog, capabilities, surfaces, actions, or domain catalogs by association. A consumer must use If-None-Match, 304 handling, or a schema hash only when the exact endpoint independently publishes those headers and semantics. Where an endpoint does not, a bounded consumer TTL is an operational policy, not inherited structural evidence and not a substitute for capability refresh.
Surfaces/actions/capabilities should reference canonical schemaUrl/requestSchemaUrl/responseSchemaUrl values produced by the resolver. They must not reconstruct schema URLs by concatenating paths, copy inline schema fragments, or treat a schemaId from another structural variant as equivalent.
The convenience SchemaReferenceResolver.resolve(CanonicalOperationRef, schemaType)
does not itself infer the idField or readOnly values that /schemas/filtered
derives from the selected UI schema and operation. For a published descriptor that
embeds a CanonicalSchemaRef, do not assume this syntactic default resolves to the
same identity variant the endpoint serves. Derive the selected component, idField,
and readOnly from the same immutable OpenAPI snapshot used to compose the descriptor,
share that projection rule with /schemas/filtered, and call the resolver with those
explicit dimensions. Validate the complete schemaId/type/URL tuple by fetching the
published URL and comparing it with the returned UI variant; include ETag/hash checks
when the endpoint publishes them. Derive these values per operation role: a workflow
confirmation schema does not supply the identity defaults for its evaluation, proposal,
execution, or result DTOs. Keep the raw HTTP response schema as a separate transport
contract and fingerprint input. If the same selector/default derivation cannot be
shared faithfully, do not publish the embedded reference until the contract is redesigned.
When a consumer receives schemaUrl, requestSchemaUrl, or responseSchemaUrl
from surfaces/actions/capabilities, treat that URL as the canonical structural
reference for the already-resolved operation variant. Consumers may resolve the
href against their configured API origin, but must not rebuild the query string,
swap schemaType, reuse a response schemaId as a request schema, or infer a
different operation from resourcePath. If the published URL is missing or
wrong, repair SchemaReferenceResolver/FilteredSchemaReferenceResolver or the
metadata publication that produced it.
For durable bulk-operation composition, the action registry's references are
canonical projections of its CanonicalOperationRef: they include the resource
idField and readOnly=false, so they are intentionally not byte-equal to the
generic OpenAPI operation references. Validate the action references by resolving
the full schemaId/type/URL tuple through the same SchemaReferenceResolver for
that exact action operation and variant. Do not loosen operation, resource,
workflow, group-snapshot, or seven-binding identity checks to accommodate the
projection.
The canonical OpenAPI response reader may preserve a bounded, non-empty oneOf
only on response schemas when a real wire response has object-or-array shape
(such as repeated HATEOAS links). Resolve each variant recursively from the same
strict group snapshot and preserve the oneOf operator in structural evidence.
Request schemas remain composition-free; empty/malformed variants, cycles,
external references, and exceeded depth/node/byte budgets fail closed. When an
action schema reference or response schema enters a durable structural
descriptor, include it in the versioned digest. Changing digest inputs requires
a new framing version and focused sensitivity tests; the durable lifecycle must
suspend/recompose and pass its current CAS fence before readiness can be
republished.
Strict Canonical OpenAPI Reading
When repeated Springdoc generations accumulate generic-response advice, inspect
the generation-scoped response builder before changing freshness or schema
semantics. GenerationScopedGenericResponseService uses a fresh upstream
GenericResponseService delegate for each generation. Generic preparation and
operation builds require the same Components object identity and thread;
equal JSON is not a generation identity. The explicitly disabled-generic path
uses an empty delegate and needs no prepared frame. Preserve full success/error
responses and their component schemas instead of suppressing advice.
Check OpenApiResponseGenerationAutoConfiguration and its auto-configuration
imports registration: servlet only, API docs enabled by default, core
SpringDocConfiguration bean required, and ordering before
SpringDocWebMvcConfiguration. A host GenericResponseService override must
prevent adapter installation. The concrete bean also supplies the global
customizer; prove that the actual grouped resources receive that same adapter.
Servlet frames are retained per request until their global cleanup callback after paths or request completion, without a fixed frame-count cap. Group customizers can run after the globals and must not reinvoke the builder after release. Direct non-servlet calls retain at most one frame per thread; observable build failures or the callback release it, while an external failure may retain it until the next generation replaces it. That bounded direct-call behavior does not certify the complete preload flow, arbitrary nested generations, or cross-thread continuation.
Use GenerationScopedGenericResponseServiceTest for serial/concurrent isolation
and full ApiResponses plus Components parity with the original Springdoc
builder, including referenced success and global/local error schemas. Use
OpenApiResponseGenerationAutoConfigurationTest for installation and override
conditions. Keep fixtures faithful to MVC media-type resolution; the
context runner must include real MVC infrastructure, and operation fixtures
must calculate MethodAttributes consumes/produces before building responses. Then compare the identified candidate artifact in the
real host. Advice-list growth alone does not quantify a timeout campaign's cause;
unit parity does not establish HTTP group coverage, bulk readiness, or release
adoption. Do not disable springdoc.cache.disabled=true to mask retained state
when the governed lifecycle requires fresh generation.
Preserve the explicit @Order(Ordered.HIGHEST_PRECEDENCE) on
OpenApiUiSchemaAutoConfiguration.modelResolver. Springdoc registers the injected
converter list through Swagger's prepend operation: the canonical resolver must
be registered first so it executes after Springdoc's response/file/additional
model decorators and before the plain ModelResolver. Moving the terminal
CustomOpenApiResolver ahead of those decorators can expose transport wrappers
as schemas; do not remove converters or UI enrichment to recover performance.
Use OpenApiModelConverterOrderingTest to exercise two real bean-definition
orders with the canonical bean and its annotations. Check the effective chain,
DTO unwrapping from ResponseEntity<DTO>, preserved x-ui and error-schema refs,
and parity with the original response builder. The focused Metadata classpath
does not include Reactor; absence of WebFluxSupportConverter there is not proof
of its order. In a Reactor-enabled host, verify it also precedes the custom
resolver, and compare the actual generated document with the identified baseline.
Read Metadata docs/spec/CANONICAL-REQUEST-SCHEMA.md before composing a
resource operation. For the S4c composition path, obtain the named group only
through OpenApiDocumentService.getDocumentForGroupStrict(group). Never call
getDocumentForGroup here: its ungrouped fallback cannot prove that the named
group exists. Resolve each declared operation explicitly by resource, operation
ID and method against that exact document.
Capture one immutable exact-group document snapshot for a descriptor and pass it
to every request and response reader used for its operations. Do not refetch the
seven operations independently, and do not treat a cache entry or a later cache
lookup as that snapshot. Cache invalidation, group replacement, or publication
failure requires rejecting or suspending composition until one complete snapshot
can be captured again. /schemas/filtered remains the UI projection and
SchemaReferenceResolver remains its identity/URL owner; neither replaces this
backend compilation snapshot.
For governed bulk descriptor publication and explicit reconciliation, prepare an isolated fresh snapshot of the complete published OpenAPI group collision domain; refreshing only the target group leaves duplicate operation IDs in cached non-target groups undetected. Fresh preparation alone is not READY and does not install a photograph. After the exact global/operation tuple commits, readiness and response composition use the installed, durably guarded photograph through withPublishedBulkOpenApiPublication, without fetching or regenerating OpenAPI. Do not replace shared cached group documents while one operation remains READY. When
the bulk lifecycle is active, OpenApiDocumentService must install and enforce its
durable invalidation guard for both public cache-clear and strict-refresh calls.
Implementations that cannot enforce the guard fail closed. Serialize preparation against local invalidation and return defensive copies of cached JSON trees so callers cannot mutate a shared document behind the fence. The canonical Springdoc
source caches its generated description by default; hosts that activate governed
bulk lifecycle must set springdoc.cache.disabled=true and retain strict exact-group
fetching with no fallback. HTTP Cache-Control revalidation alone does not bypass
Springdoc's calculated-description cache. Never let a host call a lower-level cache
API to skip the durable suspension signal.
When lifecycle is inactive, the official multigroup fresh-composition helper keeps HTTP preparation outside the public cache write lock. Serialize preparations separately, capture local invalidation epoch and public entries under short read locking, then recheck epoch and public/fresh parity under the write lock before installing complete cold entries and invoking the callback. A clear/refresh attempt advances the epoch even if its durable guard fails. Do not confuse that local epoch with upstream authority or use it to cache the source forever. Cold preparation must independently fetch ordinary public and fresh documents; never install fresh merely to compare it to itself. Keep the complete published collision domain. R2 publication and reconciliation do not use this public-cache parity algorithm.
Inspect OpenApiInternalRestTemplate and the official client bean. Defaults are
praxis.openapi.http.connect-timeout=1s, praxis.openapi.http.read-timeout=10s
(complete HTTP response, headers and body), and
praxis.openapi.bulk-composition-timeout=60s (aggregate preparation/admission).
Use positive Duration values in the supported millisecond range. The shared JDK client
waits for the complete response with the smaller request/remaining budget, requests
best-effort cancellation, and must not follow redirects. An opaque host RestTemplate
or replaced factory cannot silently prove bounded fresh composition. Prove factory
swap/restore rejection and preserve legitimate interceptors/error handlers; those
custom hooks are not covered by a forced cancellation guarantee.
Recheck admission after obtaining the control-plane connection and before the actual READY transition. Distinguish failure before attempting CAS from uncertain confirmation after the attempt: a pre-CAS timeout must not reconcile another publisher's READY as its own success. Do not check expiration after a confirmed READY and convert its effect to failure. If drift is already known under the write lock, perform the durable guard before cache eviction even after new-admission budget expiry; guard/pool/transaction/reconciliation have their own bounds. Explicit strict refresh retains its historical exclusive section; this change does not prove every cache fill or business operation has a hard wall-clock bound or that server-side work stops when the client cancels.
For the inactive fresh-composition helper, prove off-lock readers, epoch clear/refresh races, cold parity, failed guard, timed preparation/write-lock waits, slow headers/body, factory replacement, and pre-CAS failure with focused composition/transport/lifecycle tests. Then run the identified candidate JAR against the real host 53-group diagnostic before the workflow HTTP suite. A diagnostic with a local observer does not prove PostgreSQL suspension, execution, readiness, or release adoption; record candidate, integrated, published, and adopted states separately. R2 instead proves the complete attested photograph and its exact durable tuple before installation.
Every shared OpenAPI-document and schema-hash cache fill must participate in the
same read-lock/epoch protocol as invalidation. A fill that began before a clear
must not repopulate a stale document or hash after the clear completes. The
standard Springdoc freshness capability rejects any configured external
app.openapi.internal-base-url; custom OpenApiDocumentService implementations
may opt in only with independent freshness proof, rather than relying on
Cache-Control headers.
The declared OpenApiDocumentService capabilities
supportsFreshBulkLifecycleComposition() and
supportsFreshBulkLifecyclePublicCacheCoherence() are admission claims only; they do
not prove a candidate, public-cache relation, READY state, or authorization. In R2,
candidate preparation and explicit reconciliation capture the complete producer-attested
root/config/group photograph and prove its source fence. Initial publication binds the
global/operation CAS transitions to that photograph in the same transaction; only after
the exact tuple is committed or reconciled may a node verify it and install locally.
They must not compare an old local public cache with that candidate, clear caches, or
suspend durable state to recover a replica: a divergent old local view is precisely what
reconciliation repairs.
After the proof, installation replaces the local document/hash view with the
authoritative complete photograph. If a candidate or durable check fails, deny and
leave the node closed; do not invoke a response callback, retry publication, or
synthesize a generation. Once installed, readiness and action projection use that
guarded photograph rather than withFreshBulkLifecycleDocuments. A custom
implementation's default false capability is not proof.
When lifecycle is inactive, treat getDocumentForGroupStrict as a read, not an
implicit refresh. A cold strict load is supported; promotion of a public non-strict
entry must preserve the identical document. Reject a different exact document before
changing public JSON or cached hashes. Use the existing guarded explicit refresh or
invalidation path for replacement, followed by lifecycle republication where required.
Never upgrade a read lock while an HTTP schema materialization holds its enclosing read
lock. Prove changed-source rejection, identical promotion, cold strict loading, and the
existing guard/hash refresh behavior with
CachedOpenApiDocumentServiceStrictPromotionTest and
CachedOpenApiDocumentServiceRefreshTest.
With a publication guard installed, do not use strict loading or promotion to recover a cold/stale node or to prove a global photograph: cold or missing installation denies, and public snapshot reads use the installed photograph. Explicit reconciliation captures a complete attested photograph and checks the exact durable tuple; it performs no global public-cache comparison, cache clear, or durable suspension.
The standard /schemas/filtered path must hold the shared cache read lock from
operation/schema selection through document materialization and hash/ETag/304
response creation. Strict document replacement and hash invalidation use the
exclusive side of that same lock, so an in-flight old request cannot repopulate
a stale hash after suspension. Verify this property at the actual controller
callsite, not only in a cache unit test. When query selectors such as idField
contain a literal plus, encode it as %2B (and spaces as %20) so servlet query
decoding preserves the same selector and schemaId; prove URL, response body,
schema hash, ETag, and conditional 304 agree.
For each request, require the declared 3.0/3.1 dialect, exactly one JSON
representation of application/json or application/<subtype-token>+json, where
the subtype token uses valid ASCII tchar characters. Reject wildcard media
types, parameters, whitespace, invalid Unicode, unsupported composition, cycles,
reference siblings, external references, custom dialects, and ambiguous content.
Defaults, examples, descriptions, and x-ui remain literal schema data; do not
flatten allOf by dropping constraints.
For each successful response, inspect every explicit final status in 200 through
299. default, 2XX, and other status ranges do not establish success, and a
non-2xx response never proves it. Every accepted 2xx response needs exactly one
media type from that same JSON allowlist and one resolvable schema. Limit
resolution to the same local component references and bounds as request reading;
reject missing, external, cyclic, sibling, or ambiguous references and content.
Request schemas remain composition-free. Response schemas may preserve only a
non-empty oneOf list whose every variant resolves recursively against the same
snapshot; keep the operator and variant order in the canonical schema, and reject
non-array or empty oneOf lists, invalid variants, composition operators other
than oneOf, cyclic or external refs,
and depth/node budget violations. This supports canonical response shapes such as
RestApiLinks, where one relation serializes as one link object or a list when
multiple links share that relation. Never flatten or remove this oneOf in a host.
Compare the resolved schemas with SchemaCanonicalizer. It intentionally preserves metadata
such as descriptions, examples, and x-ui, so equality is conservative and
metadata drift blocks reuse. The structural fingerprint must directly include
the ordered (status, media type) variants and the complete shared canonical
schema. A schema-hash cache is an optimization only and is never fingerprint
authority.
The self-HTTP source must run after the server/document is available. This
structural binding does not prove startup readiness, provider availability,
authorization, capability/action projection, or an executable bulk registry. Use
CanonicalOperationResolver.requireResourceRequestBody with the configured
mapper.getTypeFactory() to obtain the operation and actual MVC body type,
including controller/interface generics. The binding does not certify custom
converters or arbitrary SpringDoc overrides. Keep the required concrete DTO
subset and fail on raw, wildcard, or optional bodies instead of guessing a class.
A bulk evaluation wrapper is not the unit update DTO; never infer the latter from
method names or the first PUT/PATCH operation.
Prove strict no-fallback group loading, one shared immutable snapshot, request
schema reading, and every explicit 2xx response tuple in focused reader and HTTP
fixtures. Include rejected default/2XX, non-2xx-only, missing or ambiguous
content, unsupported refs, and metadata-only schema differences. Then regress
OpenApiDocsSupport/ApiDocsController and the exact candidate JAR in
Quickstart. The HTTP fixture proves schema compilation, not persistence,
authorization, or bulk execution.
Governed OpenAPI Publication — R2/V15 Candidate
Treat the current governed-lifecycle implementation as an R2/V15 candidate under audit, not as the published rc.146 artifact, complete readiness, host adoption, or an Angular release. Start with docs/spec/BULK-OPERATION-LIFECYCLE.md, BulkOperationLifecycle, OpenApiDocumentService, and CachedOpenApiDocumentService; derive lifecycle claims from those sources and their exact evidence rather than from capabilities, a local cache entry, or an action projection.
Before a durable publication, prepare one immutable photograph from attested producer captures of the root, swagger-config, and the complete published group set. The digest binds the canonical ordered bytes of that full photograph. Each capture needs its own single-use attested nonce/lease, bound to the local Servlet context, path, GET request, and deadline. Do not treat an HTTP 200, a reusable internal header, a subset of groups, or a cached target group as that proof. A candidate whose producer, transport revision, context, source bytes, root, config, or group set cannot be attested fails closed.
Use fresh HTTP only to prepare or explicitly reconcile a candidate. requireReady, capability/action projection, and composition over an installed photograph must not fetch or regenerate OpenAPI. Candidate composition stays outside JDBC transactions; the short admission section performs the global PUBLISHED CAS and operation READY CAS atomically against the same generation/digest. A lost commit acknowledgement permits only an independent readback of that exact global and operation tuple. Never retry the CAS, mutation, or provider callback because acknowledgement was uncertain. Install the local photograph only after that commit is confirmed or reconciled, under its local source/transport and durable guards.
Inside an active writable operational unit, published structural reads use the existing immutable photograph and the attested bound connection. Validate the global generation/digest before and after composition through runtime.withConnection; retain its global SHARE until the unit commits or rolls back. Never acquire a cache read lock or open REQUIRES_NEW in that path: a publisher holding CACHE WRITE may already be waiting for that SHARE. Reject read-only, rollback-only and unrelated datasource/transaction bindings before building schema payloads. Receipt replay remains before gates reserved for new mutation; this read scope supplies no domain authorization or readiness admission.
Materialize defensive copies only for the requested group. This is a getter guarantee, not constant-cost canonical resolution: collision/group validation may still scan all published groups. Prove both the lazy getter with a realistic multi-group fixture and the complete host flow within its unchanged budget. Use PostgreSQL barriers/PIDs to show a bound reader finishes while a cache writer waits for its global SHARE, then rejects the suspended publication on a later read. Publication/preparation/installation/reconciliation, requireReady, and ephemeral response-frame capture still start outside operational transactions.
A cold or stale node remains closed until reconcilePublished(identity, readyGeneration) explicitly recaptures and verifies the durable photograph, descriptor, generation, and digest. That path is read-only: it neither clears caches nor suspends a global publication owned by another replica. clearCaches and strict refresh are invalidation paths, not local recovery tools; with the lifecycle installed they must first run the durable suspension guard, and a failed guard leaves the cache unmodified while invalidating prior local authority.
For a known unavailable publication, inspect CachedOpenApiDocumentService.requirePublishedSnapshot, GovernedOpenApiPublicationUnavailableException, and GlobalExceptionHandler.handleGovernedOpenApiPublicationUnavailable. Only IllegalStateException failures classified at that published-snapshot guard become the dedicated subtype; unrelated callbacks and unexpected IllegalStateException keep their existing mapping, normally sanitized HTTP 500. The canonical handler returns HTTP 503, envelope failure, category SYSTEM, stable code GOVERNED_OPENAPI_PUBLICATION_UNAVAILABLE, and the fixed safe message Governed OpenAPI publication is temporarily unavailable. The cause remains private diagnostic evidence. Cold, suspended, or stale photographs still deny serving without fresh HTTP, recapture, or domain retries. Recovery requires explicit governed publish or reconcilePublished under their existing state/generation rules. Use GovernedOpenApiPublicationUnavailableExceptionTest for the sanitized handler contract, retain the generic-500 test in GlobalExceptionHandlerTest, and prove the actual cold/suspended paths against the identified candidate. A direct handler test does not certify HTTP dispatch or host adoption. These outcomes belong to the R2/V15 candidate above, not the published rc.146 contract.
Require evidence tied to the exact candidate tree for paired global/operation rollback, stale-replica reconciliation, lost-commit readback, final fence rejection, provider removal, cold/stale photographs, and shared-photograph publication by multiple operations. Such PostgreSQL evidence does not prove real host security-chain installation, a fresh HTTP lifecycle run, the required HTTP+PostgreSQL host proof within 8 seconds in both modes, integration/adoption, or release publication. Keep those as explicit gates; do not label the candidate as rc.146, READY-complete, or adopted.
Decision Rules
- Do not fix missing schema semantics in Angular, quickstart, HTTP examples, or docs when the canonical source is the starter.
- Do not add parallel endpoints for request/response schema variants when
/schemas/filteredplus canonical operation resolution can express them. - Keep
schemaIdandschemaUrlaligned when adding structural dimensions such asincludeInternalSchemas,idField, orreadOnly. - Preserve the request/response boundary. Workflow actions and writable
surfaces must use
requestSchemaUrlor requestschemaUrlfor form inputs and may carryresponseSchemaUrlonly as response evidence. Read projections and view surfaces use response schemas. Do not let an Angular adapter or host choose the variant by inspecting method names, labels, widget mode, or local URL conventions. - If
ApiDocsControllerchanges, review cache headers,ETag,X-Schema-Hash,If-None-Match, and exposed headers in the same pass. - If
/schemas/catalogor capabilities are consumed for authoring, keep their roles separate: catalog enumerates candidates, an exact published capabilities href proves current operation/field eligibility, and/schemas/filteredsupplies structural property metadata. Do not infer one surface's freshness or authority from another's headers. - If
x-uishape changes, reviewdocs/spec/*.schema.json, examples, conformance docs, Angular consumers, and quickstart downstream tests.
Reactive Determinations are operation-specific x-ui operation metadata,
compiled from the canonical definition registry. Preserve stable identity,
form/trigger modes, typed input/output bindings, and provenance. Do not
republish removed Form Effect annotations or a second form-owned schema.
No Keyword Routing
Do not resolve resource, operation, schema, or field intent through keywords, regexes, aliases, or local fuzzy matching as the primary decision. Use canonical OpenAPI operations, resource keys, schema references, governed semantic catalogs, and declared tools for grounding; textual matching may only rank already-scoped candidates.
Aderence Inventory
Before adding schema fields, headers, query params, endpoint variants, or resolver branches, classify:
ja-suportado-so-uxja-suportado-mal-nomeado-ou-mal-materializadosuportado-parcialmentelacuna-real-de-contrato
Only lacuna-real-de-contrato justifies a new public schema contract. In that case name the missing data, canonical owner, consumers, derived docs/examples, and minimum validation.
Validation
Use focused local gates:
- bulk structural composition and schema variants:
mvn "-Dtest=BulkOperationStructuralCompilerTest,CanonicalRequestSchemaTest,CanonicalResponseSchemaTest" test - docs/schema refs/hash:
mvn "-Dtest=ApiDocsControllerTest,ApiDocsControllerPathResolutionTest,ApiDocsControllerSchemaHashTest,DomainCatalogControllerTest,FilteredSchemaReferenceResolverTest,OpenApiCanonicalOperationResolverTest" test - quickstart downstream proof for public schema changes:
QuickstartMetadataMigrationIntegrationTest,EventosFolhaPilotIntegrationTest, andOpenApiGroupResolutionIsolatedIntegrationTest - Angular consumer proof when schema runtime changes:
schema-metadata-client.spec.ts,fetch-with-etag.util.spec.ts, andgeneric-crud.service.spec.ts
Review README.md, CHANGELOG.md, docs/index.md, docs/guides/**, docs/spec/CONFORMANCE.md, docs/spec/*.schema.json, and docs/spec/examples/** when public schema semantics change. State why if no derived artifact is updated.
Companion Skills
Use
praxis-reactive-determinationswhen schema metadata drives governed reactive form execution.Use
praxis-metadata-resource-baselinefor resource-oriented controller/service hierarchy.Use
praxis-metadata-discovery-capabilitiesfor surfaces, actions, capabilities,_links, availability, stats, and export discovery.Use
praxis-metadata-domain-option-sourcesfor@DomainGovernance, semantic domain catalog, option sources, field access, and entity lookup contracts.Use
praxis-api-quickstart-operational-proofandpraxis-api-quickstart-cockpit-http-validationfor downstream HTTP proof of schema contracts in the reference host.Use
praxis-http-examples-contract-surfaceswhen the public executable HTTP corpus for/schemas/**, headers, or schema examples is affected.Use
praxis-core-resource-runtimefor Angular consumption of these contracts.Use
praxis-landing-public-docs-contractsandpraxis-landing-registries-sitemap-playgroundswhen public landing/docs, guides, sitemap, LLM files, examples, or playgrounds publish/schemas/filtered,x-ui, schema hash, or metadata grounding claims.
Installed photograph and one discovery-response frame
Prepare a fresh candidate only for publication or explicit reconciliation. withFreshBulkLifecycleDocuments does not make an operation READY and, once the governed publication guard is installed, must not be used as the ordinary readiness path. After the matching durable tuple has committed and the candidate is installed, withPublishedBulkOpenApiPublication may serve independent requests from that immutable photograph without HTTP fetch or SpringDoc regeneration; each scope still validates the durable tuple and local source/transport fence.
For one capability or action response, capture an ephemeral BulkLifecycleDocumentFence while the installed-photograph scope is active, then release cache/preparation locks before response assembly. The fence carries the cache epoch, transport revision, owner thread, and remaining composition deadline; its short reads validate before and after use. It is validity evidence for that response, not source authority, readiness itself, or permission to mutate. Provider recapture/composition and admitted database reads still execute under the short read section; custom code or a transaction already started is not forcibly interrupted. Do not describe this as a hard duration bound or SLA.
The lifecycle consumer must close its per-response fence and private response frame on every exit. Revalidate provider and durable generation/fingerprint/revision at each scoped readiness query and once after response assembly. Do not reuse a response frame, fence, or its approved projection across requests; the installed photograph is reusable only through a new guarded withPublishedBulkOpenApiPublication scope. Do not remove transactional admission checks. Test invalidation and strict refresh, failed invalidation guards, transport ABA, deadline exhaustion, another thread, cleanup after exceptions, and a subsequent independent request.
Tenant custom-field structural projection (Metadata #303)
For @CustomFields work, inspect customfields/CustomFieldDescriptor,
CustomFieldSchemaEnricher, ResourceTenantContextResolver, and the adoption
spec docs/spec/custom-fields-and-resource-facts.md in the metadata starter.
The annotation marks a named Map<String,Object> customFields container on
entities and DTOs/records. Never flatten extension keys with root JsonAnySetter.
CustomFieldDefinitionProvider supplies definitions scoped by canonical resource,
tenant and request/response schema role; it does not persist authored rules.
Capture one definition snapshot for projection and cache fingerprinting. Publish
properties, required keys, validation bounds, options and governance beneath the
container, with customFieldsContainer, customField, customFieldKey and
customFieldScope markers. Empty definitions must not leave a rendered empty
control or a dangling root required entry. Preserve ordinary schemas and existing
schemaId strings when no extension context exists. Tenant is carried by request
context, not invented schema URL query parameters; hash-cache entries must bind
tenant and the exact definition fingerprint. A cached hash from a different
tenant or earlier definition must never authorize 304.
The default tenant adapter validates X-Tenant/X-Tenant-ID; authenticated hosts replace the SPI rather than trusting header identity as authorization. Its result, including absence, is authoritative. Both 200 and 304 vary on both tenant headers; tenant-scoped responses must be private because a host may use authenticated context without either header. Providers must enforce their own trusted tenant scope; metadata selection alone does not enforce row tenancy.
Use RequestHeaderResourceTenantContextResolverTest, custom-field schema tests,
CustomFieldsResourceE2ETest, and the existing ApiDocs/schema-reference regression.
Run database-dependent proof only on an assigned remote Neon branch with verified
TLS and ordinary runtime privileges. H2JsonbFunctions can be unit tested as a JSON
parser without opening a local database. Update x-ui-field.schema.json and its
conformance example when the published markers change. This guidance accompanies
Metadata issue #303; confirm its PR is integrated before claiming released support.
For the #303 review corrections, derive filter projection from the MVC request
body implementing GenericFilterDTO, including inherited generic bindings through
CanonicalOperationResolver.resolveRequestBodyType; never infer a filter role from
route suffixes or DTO names. The provider still receives normalized request.
Publish IN as an array of scalar operands and IS_NULL as boolean, with nullable
no-op operands; remove write required/bounds/default/readonly from search criteria.
Do not carry stored-value options into an IS_NULL boolean control. Cross-check
published filter payloads against the actual Criteria/HTTP execution, including
empty IN, null, false and non-filterable keys.
When dynamic writable children are required, also require the root customFields
container; preserve static container requirements on active write/response schemas.
Readonly custom fields are excluded entirely from ordinary WRITE request schemas,
not merely marked optional/readOnly. This is a projection rule in the enricher:
the provider's request snapshot must still contain readonly definitions so the
write validator and replacement mapper can reject assignments and preserve stored
values. Never implement WRITE exclusion by filtering them out of the provider.
Keep them in response and in filter projection
when filterable; filtering a server-owned value does not authorize writing it.
Validate duplicate provider keys before role filtering, so duplicate definitions
cannot disappear behind readonly or filterable selection. Normalize schemaType
before provider lookup, schema identity and hash so REQUEST/request are equivalent.
Use CustomFieldSchemaProjectionTest and tenant/controller regressions to validate
complete payloads against the generated JSON Schema, not only metadata fragments.
Keep enum membership canonical: enumValues is supported on STRING/ENUM; ENUM requires a nonempty finite list. Options/optionSource are presentation and lookup contracts, not substitute validation authority. Reject invalid definitions at construction and prove both accepted and rejected values agree between schema and write validator. Dynamic selections without a finite enum remain STRING with host-owned domain validation. Update the spec/conformance examples alongside tests.
For Angular
…(truncated)