Decide which values may cross the client boundary
Not every value stored in a record belongs in a response. An internal processing flag should stay on the server. A connection secret needs to be entered and saved, but it should not reappear as readable text every time the settings are opened.
Wildo records these choices on the field. Its operation contracts use that declaration when accepting input and returning data, keeping field behavior connected across the resource’s read and write surfaces.
This works alongside record access. Permissions decide which records a caller may reach; field declarations describe which values the chosen operation can carry.
Example — Update connection settings without revealing the secret
An administrator enters a provider credential and saves it. Later, the settings show a mask in place of the secret. Saving the unchanged mask preserves the existing value, while entering a new value supplies a replacement through the credential’s write path.
For engineers
Separate credential identity from its secret
The provider-credential resource in provider-credentials.shared.schemas.ts keeps the tenant, provider and secret identity beside the write-only value. Source comments are omitted, and the schema continues after this excerpt:
export const OrganizationProviderCredentialSchema = z.object({
_id: z.string().min(1).isPrimaryKey().isSummaryField(),
organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
secretValue: z.string().min(1).isWriteOnlySecret(),
enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),
validationState: z
.enum(ProviderCredentialValidationState)
.default(ProviderCredentialValidationState.UNVALIDATED)
.isDBIndexed()
.isSummaryField(),
validationError: z.string().max(500).optional().excludeFromCreate().excludeFromUpdate(),
lastValidatedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
The identity fields are excluded from update so an existing credential is not silently repointed to another provider or secret slot. secretValue uses isWriteOnlySecret(): callers can submit it, but client-facing reads receive the mask. Status fields have their own ordinary schemas and are distinct from the protected value.
Select the right field posture
A backend-only field is excluded from ordinary client inputs and outputs. A write-only secret remains available for input and is masked in responses; an echoed mask is removed from a later request so it does not replace the stored secret. An ephemeral field represents a value disclosed by the operation that produces it, such as a freshly minted credential.
These choices have different purposes. Making the provider secret backend-only would prevent the administrator from supplying it through the normal form. Conversely, masking a stored internal flag would imply it was something a caller should write.
Compare the input and output boundary
| Value’s purpose | Client input | Client-facing output |
|---|---|---|
| Internal backend field | Excluded from ordinary derived requests. | Excluded from ordinary derived responses. |
| Provider secret | Accept the supplied secret. | Return its mask; an echoed mask is not a replacement secret. |
| Newly issued ephemeral value | Follow the issuing operation’s request contract. | Disclose through the producing operation’s response contract, not as a normal stored field to retrieve later. |
For the provider credential above, changing enabled and supplying a new secretValue have different effects. The boolean is ordinary data. The secret crosses the write boundary, is protected by the backend’s credential handler, and is masked on the way back. A normal read does not recover the submitted secret for the form.
Carry the declaration through the operation contract
The DTO builder constructs client-facing inputs and outputs separately from backend repository shapes. Server code retains access to the values it needs, while serializers use the operation’s response contract. Create-only disclosure and ephemeral disclosure also have dedicated audit handling at their response boundary.
Visibility declarations do not encrypt a value by themselves. In this provider-credential example, its backend write path seals the supplied value; the field marker governs what travels across the client boundary. Storage protection and client disclosure are complementary mechanisms.
Use separate operation response shapes when a product needs different field sets for different roles. The resource’s ordinary authorization still determines which records may be reached, and request validation governs the values accepted by each operation.